Unifi Notes Revision as of Sunday, 23 June 2024 at 17:04 UTC

API

UniFi provides an API which is ill-documented. Here are some resources that helped me do what I wanted with the API:

• UniFi API Browser Application
• GitHub Gist to enable and disable WiFi

I used this to kick my stupid printer every hour.

Because I don’t trust things to continue to be on the internet. Here’s the source:

Cached, Unofficial API Docs

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 (e.g. https://192.168.0.1/proxy/network/api/s/default/self)

Examples

# authenticate and save the cookie contents in local file cookie.txt with switch '-c'
curl -k -X POST --data '{"username": "usr", "password": "$pw"}' --header 'Content-Type: application/json' -c cookie.txt https://udmp:443/api/auth/login
# responds with json data

# pass the local file cookie.txt with switch '-b'
curl -k -X GET -b cookie.txt https://udmp/proxy/network/api/s/default/self
# responds with proper json

import requests
from requests.packages.urllib3.exceptions import InsecureRequestWarning
requests.packages.urllib3.disable_warnings(InsecureRequestWarning)
headers = {"Accept": "application/json","Content-Type": "application/json"}
data = {'username': 'usr', 'password': 'pw'}
s = requests.Session()
r = s.post('https://udmp:443/api/auth/login', headers = headers,  json = data , verify = False, timeout = 1)
print(r.status_code)
print(s.get('https://udmp/proxy/network/api/s/default/self', headers = headers, verify = False, timeout = 1).text)

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.

Site Endpoints

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

Callable commands

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

Data Tables

This data was extracted from the javascript of the site.

There are 2,213 named applications in the javascript dynamic.dpi.js. See extracted [[products:software:unifi-controller:api:cat_app_json|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

# Update User (User are the clients)
api/s/{site}/upd/user/{UserId}
you can get the users and the userid from "/api/s/{SiteId}/stat/alluser" (All Clients) or "/api/s/{SiteId}/stat/sta" (Active Clients) which contains the client id (_id).
example: change name of user with clientid 5aca464bb79fc60200460394 to 'test-raw':
${curl_cmd} --data "json={'name':'test-raw'}" $baseurl/api/s/$site/upd/user/5aca464bb79fc60200460394

# Get Hotspot Configuration
guest/s/{site}/hotspotconfig
You will get in "auth" the value "none" if it is not activated, if it is activated you will get for exemple "hotspot" and many other values on the design of the page.

# Get Hotspot Packages
guest/s/{site}/hotspotpackages
 ??

# Get trafficrules
v2/api/site/{site}/trafficrules
also possible to add new rule with a POST request.

# Edit trafficrules
v2/api/site/{site}/trafficrules/{id}/
PUT or DELETE request to update or delete traffic rule
GET is not allowed on specific trafficrules.
With PUT the result code is 201 and not 200 for successful change.

# 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).