Unifi Operator

UniFi Operator

Operate a UniFi OS console (UDM, UDM-Pro/SE, UDR, UCG, Cloud Key Gen2+, or self-hosted Network/Protect) over HTTP. Two product apps, each with a stable official API and a comprehensive private API:

• Network — gateways, switches, APs, clients, VLANs, WLANs, firewall, routing, port-forwards, DPI, guest/hotspot, device adoption & lifecycle.
• Protect — cameras, recordings, snapshots, smart-detection events, lights, sensors, chimes, sirens, viewers, alarm manager, realtime updates.

All four surfaces live on one console at port 443 behind a self-signed TLS cert (every curl uses -k). Cloud Site Manager (api.ui.com) is out of scope — this skill is local-console only.

API surface map

Pick the official surface first (stateless API key, survives upgrades). Drop to the private surface for anything official omits: firewall/WLAN CRUD on older firmware, client block/unblock, device adopt/locate/speedtest, full Protect bootstrap, recorded-video export, and the realtime updates socket.

References

Environment & auth quick-start

HOST="192.168.1.1"          # console IP or hostname
CURL=(curl -ksS)            # -k self-signed, -s quiet, -S show errors

Official APIs — API key (stateless)

One console-wide key (created in Settings → Control Plane → Integrations in either Network or Protect; inherits the creating admin's permissions). Same key works for both Network and Protect on that console.

KEY="paste-api-key"
H=(-H "X-API-KEY: $KEY" -H "Accept: application/json")

"${CURL[@]}" "${H[@]}" "https://$HOST/proxy/network/integration/v1/info"      # Network version
"${CURL[@]}" "${H[@]}" "https://$HOST/proxy/protect/integration/v1/meta/info" # Protect version

Private APIs — login + CSRF (cookie session)

Login once; reuse the cookie jar. Mutating calls (POST/PUT/PATCH/DELETE) require the CSRF token returned by login. A local admin account is required — Ubiquiti cloud SSO logins and MFA-enabled accounts do not work for scripted login (see auth reference).

CSRF=$("${CURL[@]}" -c /tmp/uni.jar -D - -o /dev/null \
  -X POST "https://$HOST/api/auth/login" \
  -H "Content-Type: application/json" \
  -d '{"username":"admin","password":"secret"}' \
  | awk 'tolower($1)=="x-csrf-token:"{print $2}' | tr -d '\r')

S=("${CURL[@]}" -b /tmp/uni.jar)                          # authenticated GET
M=("${CURL[@]}" -b /tmp/uni.jar -H "x-csrf-token: $CSRF") # authenticated mutation

"${S[@]}" "https://$HOST/proxy/network/api/self/sites"    # list sites -> use .name as <site>
"${S[@]}" "https://$HOST/proxy/protect/api/bootstrap"     # entire Protect state

<site> in private Network paths is the internal slug (often default), from self/sites[].name — not the display label. Response envelope is {"meta":{"rc":"ok"},"data":[...]}; rc:"error" carries meta.msg.

Capability → endpoint matrix

Network

Protect

Essential recipes

# --- Network: official ---
NB="https://$HOST/proxy/network/integration/v1"
SITE=$("${CURL[@]}" "${H[@]}" "$NB/sites" | jq -r '.data[0].id')   # most consoles: one site

# Find a noisy guest and read its detail
"${CURL[@]}" "${H[@]}" --get "$NB/sites/$SITE/clients" \
  --data-urlencode "filter=name.like('guest*')" --data-urlencode "limit=50" | jq

# PoE power-cycle port 5 of a switch (deviceId from /devices)
"${CURL[@]}" "${H[@]}" -H "Content-Type: application/json" -X POST \
  "$NB/sites/$SITE/devices/$DEVICE/interfaces/ports/5/actions" -d '{"action":"POWER_CYCLE"}'

# Issue 10 lobby vouchers, 24h, 1 GB cap
"${CURL[@]}" "${H[@]}" -H "Content-Type: application/json" -X POST \
  "$NB/sites/$SITE/hotspot/vouchers" \
  -d '{"name":"Lobby","count":10,"timeLimitMinutes":1440,"dataUsageLimitMBytes":1024}'

# --- Network: private (block a client the official API can't) ---
NP="https://$HOST/proxy/network/api/s/default"
"${M[@]}" -H "Content-Type: application/json" -X POST \
  "$NP/cmd/stamgr" -d '{"cmd":"block-sta","mac":"aa:bb:cc:dd:ee:ff"}'

# --- Protect: snapshot every camera ---
PB="https://$HOST/proxy/protect/integration/v1"
for id in $("${CURL[@]}" "${H[@]}" "$PB/cameras" | jq -r '.[].id'); do
  "${CURL[@]}" "${H[@]}" "$PB/cameras/$id/snapshot?highQuality=true" -o "cam-$id.jpg"
done

# --- Protect: export last 10 minutes of recorded video (private) ---
NOW=$(($(date +%s)*1000)); AGO=$((NOW-600000))
"${S[@]}" "https://$HOST/proxy/protect/api/video/export?camera=$CAM&start=$AGO&end=$NOW&channel=0" -o clip.mp4

Red flags