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
UDM Pro API
NOTE: There are two critical differences between Unifi controllers and the UDM Pro's API:
- The login endpoint is /api/auth/login
- All API endpoints need to be prefixed with /proxy/network
Controller Endpoints
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. NOTE: On UDM Pros this is api/auth/login. |
api/logout | POST | 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 |
Site Endpoints
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/wlanconf | GET/PUT | List WLANs, edit current WLANs and create new WLANs |
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 ) |
stamgr | unauthorize-guest | Unauthorize a client device, mac = client mac (required) |
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 | migrate | mac = device mac ( required ), inform_url = New Inform URL to push to device (required) |
devmgr | cancel-migrate | mac = device mac ( 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 |
UFLHD | uap | UniFi AP-Flex-HD |
UHDIW | uap | UniFi AP-HD-In Wall |
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 |
US48PRO | usw | UniFi Switch Pro 48 |
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 dynamic.dpi.js. See extracted cat_app.json to include for lookups and example usage.
The application id is a compound id using bitwise shift left on the category id + application id sent from the api using `list_dpi_stats_filtered`
function compoundId($cat, $app){ return (intval($cat) << 16) + intval($app); }
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
Update of Port Forward Rules
This may apply to other configurations, but initial testing shows that port forward rules can be enabled/disabled using PUT against the endpoint /api/s/{site}/rest/portforward/{rule-id} with a body such as:
{ "enabled": true }
The rule ID can be retrieved using the above described port forwarding GET request and is found in the "_id" key.
New rules can be created using POST, but be aware that there seems to be very little validation (it's possible to create entries with no information other than the fact that they're enabled, for example).