banshee/network-collection/network/unifi/https/network-9/devices

Devices of a UniFi site, by the API of UniFi Network 9

Returns, for each device a UniFi site has adopted (access points, switches, gateways), its state, the firmware it runs and whether an update is available, and the number of devices. Three watches are offered: a device not connected, a firmware update available, and a device missing.

Versions

UniFi Network 9 and later, on a UniFi OS console (Dream Machine, Cloud Key Gen2, Cloud Gateway, UniFi OS Server), the first to offer an API key. It sits under network-9/ for that reason: an older Network, or the Network application installed without UniFi OS, has no API key and another address.

How it works

One GET to the Network application of a UniFi OS console, <address>/proxy/network/api/s/<site>/stat/device, with the API key in the header X-API-KEY.

A device is named by its name, or by its MAC address when it has none.
The state is the number UniFi gives, in words: disconnected (0), connected (1), pending (2, waiting to be adopted), upgrading (4), provisioning (5), heartbeat-missed (6), adopting (7); any other number reads state and the number. "Device not connected" is critical when a device stays out of connected for 3 runs: an upgrade or a provisioning passes within that time.
The firmware is version; the update is available when UniFi says the device is upgradable, none otherwise.
An API key refused (401, 403) stops the collector as misconfigured; any other code than 200, as unreachable.

The API key comes from protocol:http:token, a secret variable: it only goes in the header, never in a value returned. The answer is not secret, its body having carried none.

Prerequisites

An API key created in UniFi Network, in its integration settings, set in protocol:http:token on the host or one of its folders. The collector only reads; the rights the key carries are those of the account that creates it, so create it from an account with the least rights the console allows.
The console reachable from the poller in https://. Its certificate follows the TLS profile of the probe: a console with its own certificate, not signed by a known authority, is accepted by trusting its first fingerprint, in the tab "Security", or by pinning it in protocol:http:fingerprint. The key never goes to http://.

Variables

Name	Label	Says	Default
`unifi:url`	Console address	the address of the console, without a slash at the end (`https://unifi.example`)	—
`unifi:site`	Site	the short name of the site, the one its address shows	`default`

Outputs

Name	Label	Unit	Per instance
`state`	State	—	yes, per device
`version`	Firmware	—	yes, per device
`update`	Firmware update	—	yes, per device
`devices`	Devices	—	no

Watches

Name	Title	Kind	Defaults	Checked by default
`not-connected`	Device not connected	expected value, on `state`	critical when the state is not `connected`, for 3 runs	yes
`update-available`	Firmware update available	state to avoid, on `update`	warning on `available`	no
`missing`	Device missing	expected instances, on `state`	no device named: it raises nothing until names are set on the probe	no

Limits

This address and the meaning of the state numbers are not published by Ubiquiti: they are those the API has kept for years and the community libraries read. The numbers 3, 8 and up differ between those libraries, and read state and their number here. Not verified without a console.
A device removed from the site leaves the list: only "Device missing" sees it.
The clients, the health of the site and its traffic are not read.