products:software:unifi-controller:api

This is an old revision of the document!


Documentation of API endpoints on the UniFi controller software. This is a reverse engineering project that is based on browser captures, jar dumps, and reviewing other software that has been written to work with the controller. It's received minimal testing.

There are two main types of calls. One would be the REST-like which provide get/post/put/delete where post is to the base and put/delete are often tied to the _id of the object that you are working with. The second major type of web interface provided is an agent/call based system where you pass a command to an agent to perform an action. Both use application/json formatting for all data transfer. When updating a specific object you must use PUT or else a new object will be created.

NOTE: All calls are relative to the base controller URL

Calls return both a web status as well as json formatted output. 200 codes indicate a successful call and other indicate errors. I am using the placeholder `{site}` for the site name which for many installations will be `default`.

# Login required
{ "data" : [ ] , "meta" : { "msg" : "api.err.LoginRequired" , "rc" : "error"}}
# Call was a success but returned no values
{ "data" : [ ] , "meta" : { "rc" : "ok"}}
# NOTE: If meta contains a count it's because the data values have been truncated
'meta': {'count': 4818, 'rc': 'ok'} # from the api/s/{site}/stat/event endpoint

These are REST calls that can be made without a site context. I do not believe any updates ( PUT ) can be called on these endpoints.

Path Method Notes
status GET Returns some very basic server information - This appears to be the only endpoint that can be reached without an authentication
{ "data" : [ ] , "meta" : { "rc" : "ok" , "server_version" : "5.7.23" , "up" : true , "uuid" : "0e727580-ffff-ffff-ffff-403dcd5a7bd4"}}
api/login POST requires dict of username, password, and optionally remember=true for long-running sessions. Returns 200 for success and a cooke that is your session
api/logout GET destroys the sever side session id which will make future attempts with that cookie fail
api/self GET Logged in user
api/self/sites GET Get basic information for all sites on this controller
api/stat/sites GET Same as above with an additional information on health and new alerts for each site
api/stat/admin GET List administrators and permissions for all sites

All commands are presumed to be prefixed with `api/s/{site}`

Path Method Notes
stat/health GET Health status of the site
self GET Logged in user
stat/ccode GET List of country codes
stat/current-channel GET List of all RF channels based on the site country code
stat/sysinfo GET Some high-level information about the controller
stat/event GET List site events by most recent first, 3000 result limit
rest/event GET List site events by oldest, no limit?
stat/alarm GET List alarms by most recent, 3000 result limit?
rest/alarm GET List alarms by oldest, no limit?
stat/sta GET List of all _active_ clients on the site
rest/user GET/POST/PUT List of all configured/known clients on the site
stat/device-basic GET List of site devices with only 'adopted', 'disabled', 'mac', 'state', 'type' keys, useful for filtering on type
stat/device GET/POST Detailed list of all devices on site. Can be filtered by posting `{"macs": ["mac1", … ]}`
rest/device/{_id} PUT Updates to devices get PUT here, why?
rest/setting GET/PUT Detailed site settings, updating requires adding key and _id to path for PUT
stat/routing GET All active routes on the device
rest/routing GET/PUT User defined routes
rest/firewallrule GET/PUT User defined firewall rules. This does not show auto-generated rules
rest/firewallgroup GET/PUT User defined firewall groups.
rest/tag GET/PUT? Tagged macs
stat/rogueap GET/POST Neighboring APs optional json post 'within' = seen in the last x hours
stat/sitedpi GET/POST DPI stats requires type="by_app" or "by_cat"
stat/stadpi GET/POST DPI stats requires type="by_app" or "by_cat" optionally filtered macs=[…, ]
stat/dynamicdns GET DynamicDNS information and status like current ip, last changed, and status
rest/dynamicdns GET/PUT DynamicDNS configuration
rest/portconf GET Switch port profiles
stat/spectrumscan GET Get RF scan results, can be for a specific mac by appending to endpoint
rest/radiusprofile GET/POST/PUT Radius profiles
rest/account GET/POST/PUT Radius accounts
rest/portforward GET List all port forwards configured on the site
stat/report/{interval}.{type} POST Intervals are '5minutes', 'hourly', and 'daily'. Report types are 'site', 'user', and 'ap'. Must specify attributes to be returned 'bytes', 'wan-tx_bytes', 'wan-rx_bytes', 'wlan_bytes', 'num_sta', 'lan-num_sta', 'wlan-num_sta', 'time', 'rx_bytes', 'tx_bytes'. Can be filtered with 'macs': […]

Callable commands

Posting to the endpoint `api/s/{site}/cmd/<manager>` with the `json {"cmd": "command"}` you can invoke commands on the controller.

Manager Call Notes
evtmgt archive-all-alarms
sitemgr add-site desc = Descriptive name ( required ), name = shortname ( in the URL )
sitemgr delete-site name = short name ( required )
sitemgr update-site desc = Descriptive name ( required )
sitemgr get-admins List all administrators and permission for this site
sitemgr move-device mac = device mac ( required ), site_id = 24 digit id ( required )
sitemgr delete-device mac = device mac ( required )
stamgr block-sta mac = client mac ( required )
stamgr unblock-sta mac = client mac ( required )
stamgr kick-sta Disconnect: mac = client mac (required )
stamgr forget-sta Forget a client ( controller 5.9.x only )
devmgr adopt mac = device mac ( required )
devmgr restart mac = device mac ( required )
devmgr force-provision mac = device mac ( required )
devmgr power-cycle mac = switch mac ( required ), port_idx = PoE port to cycle ( required )
devmgr speedtest Start a speed test
devmgr speedtest-status get the current state of the speed test
devmgr set-locate mac = device mac ( required ) blink unit to locate
devmgr unset-locate mac = device mac ( required ) led to normal state
devmgr upgrade mac = device mac ( required ) upgrade firmware
devmgr upgrade-external mac = device mac ( required ), url = firmware URL ( required )
devmgr spectrum-scan mac = device mac ( ap only, required ) trigger RF scan
backup list-backup list of autobackup files
backup delete-backup filename ( required )
system backup create a backup. This appears to backup to a fixed location in the filesystem
stat clear-dpi resets the site wide DPI counters
Data Tables

This data was extracted from the javascript of the site.

Device Code Device Type Device Name
BZ2 uap UniFi AP
BZ2LR uap UniFi AP-LR
U2HSR uap UniFi AP-Outdoor+
U2IW uap UniFi AP-In Wall
U2L48 uap UniFi AP-LR
U2Lv2 uap UniFi AP-LR v2
U2M uap UniFi AP-Mini
U2O uap UniFi AP-Outdoor
U2S48 uap UniFi AP
U2Sv2 uap UniFi AP v2
U5O uap UniFi AP-Outdoor 5G
U7E uap UniFi AP-AC
U7EDU uap UniFi AP-AC-EDU
U7Ev2 uap UniFi AP-AC v2
U7HD uap UniFi AP-HD
U7SHD uap UniFi AP-SHD
U7NHD uap UniFi AP-nanoHD
UCXG uap UniFi AP-XG
UXSDM uap UniFi AP-BaseStationXG
UCMSH uap UniFi AP-MeshXG
U7IW uap UniFi AP-AC-In Wall
U7IWP uap UniFi AP-AC-In Wall Pro
U7MP uap UniFi AP-AC-Mesh-Pro
U7LR uap UniFi AP-AC-LR
U7LT uap UniFi AP-AC-Lite
U7O uap UniFi AP-AC Outdoor
U7P uap UniFi AP-Pro
U7MSH uap UniFi AP-AC-Mesh
U7PG2 uap UniFi AP-AC-Pro
p2N uap PicoStation M2
US8 usw UniFi Switch 8
US8P60 usw UniFi Switch 8 POE-60W
US8P150 usw UniFi Switch 8 POE-150W
S28150 usw UniFi Switch 8 AT-150W
USC8 usw UniFi Switch 8
US16P150 usw UniFi Switch 16 POE-150W
S216150 usw UniFi Switch 16 AT-150W
US24 usw UniFi Switch 24
US24P250 usw UniFi Switch 24 POE-250W
US24PL2 usw UniFi Switch 24 L2 POE
US24P500 usw UniFi Switch 24 POE-500W
S224250 usw UniFi Switch 24 AT-250W
S224500 usw UniFi Switch 24 AT-500W
US48 usw UniFi Switch 48
US48P500 usw UniFi Switch 48 POE-500W
US48PL2 usw UniFi Switch 48 L2 POE
US48P750 usw UniFi Switch 48 POE-750W
S248500 usw UniFi Switch 48 AT-500W
S248750 usw UniFi Switch 48 AT-750W
US6XG150 usw UniFi Switch 6XG POE-150W
USXG usw UniFi Switch 16XG
UGW3 ugw UniFi Security Gateway 3P
UGW4 ugw UniFi Security Gateway 4P
UGWHD4 ugw UniFi Security Gateway HD
UGWXG ugw UniFi Security Gateway XG-8
UP4 uph UniFi Phone-X
UP5 uph UniFi Phone
UP5t uph UniFi Phone-Pro
UP7 uph UniFi Phone-Executive
UP5c uph UniFi Phone
UP5tc uph UniFi Phone-Pro
UP7c uph UniFi Phone-Executive
DPI Category Code Name
0 Instant messaging
1 P2P
3 File Transfer
4 Streaming Media
5 Mail and Collaboration
6 Voice over IP
7 Database
8 Games
9 Network Management
10 Remote Access Terminals
11 Bypass Proxies and Tunnels
12 Stock Market
13 Web
14 Security Update
15 Web IM
17 Business
18 Network Protocols
19 Network Protocols
20 Network Protocols
23 Private Protocol
24 Social Network
255 Unknown

There are 2,213 named applications in the javascript. I will find a way to post them.

Uncategorized

Dump of found endpoints waiting for documentation

# logged in user
api/s/{site}/self

# Country codes
api/s/{site}/stat/ccode
# Availible WiFi channels
api/s/{site}/stat/current-channel

# Dashboard health
api/s/{site}/stat/health

# Active client devices
api/s/{site}/stat/sta
# Configured clients
api/s/{site}/stat/user

# Devices
api/s/{site}/stat/device-basic - mac, type
api/s/{site}/stat/device - can be filtered with macs: [ ..., ... ]

# Detailed site settings
api/s/{site}/stat/sysinfo

# /rest/ endpoints also have a /cnt/ which returns the count for the data portion
# can be used for any but seems targeted towards alarms

# Site settings
api/s/{site}/rest/setting - this is a big one with a weird mechanism for updating

# Firewall rules
api/s/{site}/rest/firewallrule - only lists user-defined rules

# Firewall groups
api/s/{site}/rest/firewallgroup

# routes
api/s/{site}/rest/routing

# Alarms
# List of alarms
api/s/{site}/rest/alarm
# list of unarchived alarms
api/s/{site}/rest/alarm?archived=false

# User groups - bandwith settings
api/s/{site}/rest/usergroup

# ?
api/s/{site}/rest/wlangroup

# Wireless networks
api/s/{site}/rest/wlanconf

# ?
api/s/{site}/rest/tag

# Site networks
api/s/{site}/rest/networkconf

# example backup path
dl/autobackup/autobackup_5.7.23_20180513_0000_1526169600008.unf

# Insights - sessions
api/s/{site}/stat/session?type=all&start=1526515200&end=1526688000

# Insights - EDU streams
api/s/{site}/stat/stream

# Switch port conf?
api/s/{site}/rest/portconf

# Configured port forwards and uPNP - transfer bytes is listed but doesn't appear populated
api/s/{site}/stat/portforward


# Possible list of all callable managers
system
devmgr
stamgr
evtmgr
cfgmgr
hotspot
sitemgr
streammgr
backup
throughput
stat
firmware
firewall
elite



Fatal error: Allowed memory size of 134217728 bytes exhausted (tried to allocate 20480 bytes) in /home/nevyxvrt/ubntwiki.com/lib/plugins/authplain/auth.php on line 446
dokuwiki\Exception\FatalException: Allowed memory size of 134217728 bytes exhausted (tried to allocate 20480 bytes)

dokuwiki\Exception\FatalException: Allowed memory size of 134217728 bytes exhausted (tried to allocate 20480 bytes)

An unforeseen error has occured. This is most likely a bug somewhere. It might be a problem in the authplain plugin.

More info has been written to the DokuWiki error log.