skill-unifi/endpoints.md

UDM Pro — referencia rápida de endpoints

Base URL: https://192.168.87.5/proxy/network/integration/v1 Auth: header X-API-KEY: $UNIFI_API_KEY en TODAS las requests.

Todas las respuestas vienen como { "offset", "limit", "count", "totalCount", "data": [...] }.

Sites

Método	Ruta	Devuelve
GET	/sites	Lista de sites del controller. Para nosotros casi siempre default.

query.sh /sites

Devices (APs, switches, gateway)

Método	Ruta	Devuelve
GET	/sites/{site}/devices	Todos los devices UniFi adoptados (APs, switches, UDM).
GET	/sites/{site}/devices/{deviceId}	Detalle de un device.
GET	/sites/{site}/devices/{deviceId}/statistics/latest	Stats actuales: uptime, CPU/RAM, load, uplink tx/rx Bps, % retries por radio.
POST	/sites/{site}/devices/{deviceId}/actions	Acciones (RESTART, etc). No usar — la skill es read-only.

Campos REALES del device (verificado contra el UDM):

• id, name, model, macAddress, ipAddress
• state: ONLINE | OFFLINE | PROVISIONING | UPGRADING | ADOPTING | ...
• firmwareVersion, firmwareUpdatable
• features: lista (accessPoint, switching, gateway, ...)
• interfaces: lista de interfaces que el device expone (radios, ports, ...)
• supported: bool

⚠️ No incluye: uptime (está en statistics/latest), count de clientes conectados, temperatura, info por puerto del switch, MAC del WAN. Para esos datos → Classic API.

query.sh "/sites/{site}/devices" | jq '.data[] | {name, model, state, ipAddress, macAddress}'

Campos REALES de /devices/{id}/statistics/latest (verificado):

• uptimeSec, lastHeartbeatAt, nextHeartbeatAt
• loadAverage1Min/5Min/15Min
• cpuUtilizationPct, memoryUtilizationPct
• uplink.txRateBps, uplink.rxRateBps
• interfaces.radios[]: frequencyGHz, txRetriesPct (>10% = saturación inalámbrica)

Clients (lo conectado a tu red)

Método	Ruta	Devuelve
GET	/sites/{site}/clients	Clientes activos (wired + wireless). Soporta ?offset=&limit=.
GET	/sites/{site}/clients/{clientId}	Detalle de un cliente.

Campos REALES del cliente (verificado contra el UDM):

• id, name (alias asignado en la UI; NO viene hostname ni el name del DHCP)
• macAddress, ipAddress
• type: WIRED | WIRELESS
• connectedAt (ISO timestamp)
• uplinkDeviceId (id del AP/switch al que está pegado)
• access.type: DEFAULT | ...

⚠️ NO incluye: txBytes/rxBytes (bytes consumidos), signal/RSSI, rxRate/txRate, wlanName/SSID, lastSeen, hostname. Para esos datos → Classic API (/stat/sta).

# Buscar por MAC (case-insensitive)
query.sh "/sites/{site}/clients" | jq --arg m "AA:BB:CC:DD:EE:FF" '.data[] | select((.macAddress // "") | ascii_upcase == ($m | ascii_upcase))'

# Buscar por IP
query.sh "/sites/{site}/clients" | jq '.data[] | select(.ipAddress == "192.168.87.142")'

# Saber a qué AP/switch está pegado un cliente (resolviendo el uplinkDeviceId)
query.sh "/sites/{site}/clients" | jq '.data[] | {name, ip: .ipAddress, uplinkDeviceId}'
query.sh "/sites/{site}/devices" | jq '.data[] | {id, name}'  # mapeo manual

Networks (VLANs / redes definidas en el UDM)

Método	Ruta	Devuelve
GET	/sites/{site}/networks	Lista de networks configuradas (VLANs).

Campos: id, name, vlanId, enabled, default, management (GATEWAY, WIFI, ...), zoneId, metadata.origin (SYSTEM_DEFINED | USER_DEFINED).

⚠️ NO devuelve subnet, DHCP range, gateway IP, ni reglas de firewall — solo metadatos.

Hotspot vouchers

Método	Ruta
GET	/sites/{site}/hotspot/vouchers

Irrelevante para nosotros — el portal cautivo lo maneja radiusNucleo con FreeRADIUS, no el hotspot nativo del UDM.

Info global

Método	Ruta	Devuelve
GET	/info	{ applicationVersion } — versión de UniFi Network App.

Paginación

Todos los listados aceptan ?offset=N&limit=M (default offset=0, limit=25, max 200). Si count < totalCount, hay más páginas:

query.sh "/sites/{site}/clients?limit=200&offset=0"
query.sh "/sites/{site}/clients?limit=200&offset=200"

Classic API (vía query-classic.sh)

Login flow stateful (cookie + CSRF cacheados 25 min). Path corto se prefija a /proxy/network/api/s/$UNIFI_SITE_NAME. Site name = default (no UUID).

Respuesta envuelta en { "meta": { "rc": "ok" }, "data": [...] } (vs Integration que usa { "data": [...], "totalCount": N }).

Estado del sistema

Path corto	Devuelve
/stat/health	Health por subsistema: wlan, wan, www, lan, vpn. Status ok/warning/error, counts, ISP, throughput, uptime. Lo más útil para diagnóstico rápido.
/stat/sysinfo	Info del controller (versión, build, hostname, license).
/stat/dashboard	Resumen agregado (similar al dashboard de la UI).

Clientes (con campos que la Integration NO devuelve)

Path corto	Devuelve
/stat/sta	Clientes activos con tx_bytes, rx_bytes, signal, rssi, essid, radio, radio_proto, tx_rate, rx_rate, hostname, uptime, last_seen.
/rest/user	TODOS los users (incluso offline), con note, usergroup_id, etc.
/stat/user/<MAC>	Detalle de un user específico por MAC.

# Top 10 consumidores ahora mismo
query-classic.sh /stat/sta | python -c "
import json, sys
d = json.load(sys.stdin)['data']
top = sorted(d, key=lambda c: -(c.get('tx_bytes',0)+c.get('rx_bytes',0)))[:10]
for c in top:
    print(c.get('hostname','?'), c.get('mac'), c.get('tx_bytes',0)+c.get('rx_bytes',0))
"

Eventos y alarmas

Path corto	Devuelve
/stat/event	Eventos del controller (login, roaming, AP up/down, etc). Acepta ?within=24 (horas) y ?_limit=N.
/stat/alarm	Alarmas activas.
/list/alarm	Histórico de alarmas.

Configs (read-only via View Only)

Path corto	Devuelve
/list/wlanconf o /rest/wlanconf	SSIDs definidas (nombre, banda, security, vlan).
/rest/networkconf	Networks/VLANs (subnet, DHCP range, gateway).
/rest/firewallrule	Reglas de firewall.
/rest/portforward	Port forwards.
/rest/setting/<key>	Settings del site.

DPI / App usage

Path corto	Devuelve
/stat/stadpi	DPI por cliente (qué apps consumen, cuántos bytes).
/stat/sitedpi	DPI agregado del site.

Devices con stats completos

Path corto	Devuelve
/stat/device	Devices con stats embebidos (CPU, mem, temperatura, throughput por puerto, count de clientes por AP, etc). Mucho más rico que /sites/{site}/devices de Integration.
/stat/device/<MAC>	Detalle de un device.

Errores comunes

HTTP	Causa probable
401	API Key inválida o caducada. Regenerá.
403	El admin que generó la key no tiene permiso sobre ese site.
404	Path mal escrito o site/device/client no existe.
5xx + cuerpo HTML	Le pegaste a UniFi OS root, no a /proxy/network/integration/v1.
connection refused / timeout	No estás en la LAN o el UDM está caído.