claudetools/.claude/skills/unifi-wifi/references/site-manager-api.md

UniFi Site Manager cloud API + connector (remote, outside-UOS access)

Empirically mapped 2026-06-17 against ACG's live account key (vault services/unifi-site-manager), corroborated by Grok + Gemini web search. This is the "access UniFi outside the UOS environment" path, and it reaches UOS-parity depth for the whole fleet remotely.

Backend script: scripts/gw-sitemanager.sh. Base host: https://api.ui.com. Auth: header X-API-KEY: <key> (account-level Site Manager key, owner mike@). Read-heavy; some POST actions exist (device restart, client block) - not wired in yet.

Three tiers

Tier 1 - Site Manager API (/v1/..., cloud, fleet overview)

Endpoint	Returns
GET /v1/hosts	All consoles (id, hardwareId, ipAddress WAN, type, owner, reportedState incl. controllers[] with each app's integrationApis location). 36 for ACG.
GET /v1/hosts/{id}	One console detail.
GET /v1/sites	Sites across hosts (82): meta, statistics.counts (device/client counts), statistics.gateway (IPS mode/signature), ispInfo (ASN/provider), percentages.txRetry.
GET /v1/devices	Per-host device inventory: name, model, ip, status, firmware, uptime, adoption. No RF.
GET /v1/isp-metrics/{5m|1h}	Per host/site WAN time-series periods[] (~264): metricTime + data.wan {avgLatency, maxLatency, download_kbps, upload_kbps, packetLoss, uptime, downtime}. Newer gateways (UCG/UDM-SE) populate it; older UDM Pro may report zeros.
GET /v1/sd-wan-configs	SD-WAN configs (0 for ACG).

/ea/* mirrors most of these. Response wrapper: {data, httpStatusCode, traceId} (Site Manager) ; sub-resource paths like /v1/hosts/{id}/devices 404 - use the flat collections and filter by hostId.

Tier 2 - Cloud CONNECTOR proxy -> console LOCAL Network API (UOS PARITY)

The key unlock. The account key proxies into each console's local UniFi Network API remotely, no LAN/VPN:

https://api.ui.com/v1/connector/consoles/{consoleId}/proxy/network/<local-path>

{consoleId} = the host id from /v1/hosts. Two sub-surfaces both work:

• Official Integration API - /proxy/network/integration/v1/...

  • /info, /sites (returns site UUIDs), /sites/{uuid}/devices, /sites/{uuid}/devices/{id}, /sites/{uuid}/devices/{id}/statistics/latest, /sites/{uuid}/clients, /clients/{mac}.
  • Device interfaces.radios[]: frequencyGHz, channel, channelWidthMHz, wlanStandard; live stats add txRetriesPct.
  • Clean/supported but shallower than the internal API (client list lacks RSSI in v1 on Net 10.4).
  • Has POST actions: device /restart, client /block /unblock.

• Internal stat API - /proxy/network/api/s/{site}/stat/... (site = short name, usually default)

  • GET .../stat/device -> per-device radio_table_stats[]: cu_total (channel utilization = airtime), cu_self_rx, cu_self_tx, channel, last_channel, bw, tx_power, num_sta, satisfaction, tx_retries, tx_retries_pct, ast_txto/ast_cst/ast_be_xmit. == the UOS Mongo ace_stat depth.
  • GET .../stat/sta -> per-client: rssi, signal, noise, satisfaction, channel, radio, essid, tx_rate, rx_rate, tx_retries, anomalies.
  • GET .../v2/api/site/{site}/... also reachable.
  • This is what gw-sitemanager.sh net <console> radios|clients uses.

Tier 3 - the OLD path (UOS Mongo ace/ace_stat)

Still used by the rest of the unifi-wifi skill (audit-site.sh, model-rank.sh, etc.) for UOS-ADOPTED sites. Tier 2 now gives the same data for NON-UOS consoles (and the whole fleet).

Parity verdict

• Tier 1 alone: inventory + health + WAN/ISP telemetry. NOT RF/per-client.
• Tier 2 (connector -> internal stat API): full UOS parity - per-radio airtime/channel/ tx-power and per-client RSSI/satisfaction - for ANY of the 36 consoles, remotely, with the one account key. Broader coverage than UOS (UOS only sees UOS-adopted sites).

Examples

S=.claude/skills/unifi-wifi/scripts/gw-sitemanager.sh
bash $S fleet                       # all 36 consoles: WAN IP, model, #devices, online
bash $S devices "Brooklyn/Skybar"   # device inventory for a console
bash $S sites brooklyn              # site health (counts, IPS, ISP)
bash $S isp "CGU-Curves" 5m 12      # WAN latency/throughput history
bash $S net brooklyn radios         # DEEP per-AP airtime/channel/txpower (parity)
bash $S net brooklyn clients        # DEEP per-client RSSI/signal/satisfaction
bash $S net brooklyn raw /integration/v1/sites   # proxy any /proxy/network/... path

Gotchas

• Direct WAN SSH/HTTPS to a standalone UDM is usually firewalled (Brooklyn 67.1.139.219: 22/443/8443 filtered) - the connector is the remote path, not direct.
• Internal stat API uses the site SHORT name (default), not the integration UUID. Override with net <c> radios --site <name> for multi-site consoles.
• Older gateways report empty ISP metrics; radio/client data still works via the connector.
• Key is account-level (owner). Non-owner/org keys may 403 on some endpoints.
• Sources: developer.ui.com (Site Manager + Network), help.ui.com "Getting Started with the Official UniFi API", Art-of-WiFi UniFi-API-client (connect_via_site_manager).