unifi-best-practices
Health Pass
- License — License: CC-BY-4.0
- Description — Repository has a description
- Active repo — Last push 0 days ago
- Community trust — 32 GitHub stars
Code Warn
- process.env — Environment variable access in examples/block-client.ts
- process.env — Environment variable access in examples/events-websocket.ts
- process.env — Environment variable access in examples/lib/classic.ts
- network request — Outbound network request in examples/lib/classic.ts
- process.env — Environment variable access in examples/lib/integration.ts
- network request — Outbound network request in examples/lib/integration.ts
- process.env — Environment variable access in examples/lib/site-manager.ts
- network request — Outbound network request in examples/lib/site-manager.ts
Permissions Pass
- Permissions — No dangerous permissions requested
No AI report is available for this listing yet.
UniFi API integration guide: official Network API, Site Manager and Cloud Connector, and the classic controller API with CSRF, 2FA and WebSocket events. Docs, TypeScript examples and a skill for Claude Code and Codex.
UniFi API best practices
A practical guide to integrating with Ubiquiti UniFi networks: the official Network API, the Site Manager API and Cloud Connector, and the unofficial classic controller API. It has documentation, runnable TypeScript examples, and a skill that gives Claude Code and Codex the same knowledge.
The official parts are checked against Ubiquiti's OpenAPI specs (Network API v11.0.97, Site Manager v1.0.0). The classic API has no official documentation, so those pages are based on widely used open-source clients and say where behaviour differs between versions.
Docs
| Page | What it covers |
|---|---|
| Overview | The four APIs, which one to use, sites, IDs and MAC format |
| Authentication | API keys, classic login, CSRF, 2FA, session expiry, TLS |
| Network API | Official endpoints, pagination, filtering, actions, vouchers, Cloud Connector |
| Site Manager API | Hosts, sites, devices, ISP metrics, SD-WAN, rate limits |
| Classic API | URL layout, response envelope, conventions |
| Classic: devices | List, restart, adopt, upgrade, locate, PoE power-cycle |
| Classic: clients | Active and known clients, block, kick, forget, guests |
| Classic: networks and WLANs | Networks, SSIDs, port profiles |
| Classic: firewall and routing | Legacy rules, zone-based firewall, port forwards, routes |
| Classic: hotspot | Vouchers and guest payments |
| Classic: events and statistics | Events, alarms, system log, reports, Network 11 stats engine |
| Classic: sites, admins, backups | Site management, admins, backups |
| WebSocket events | Live events from the controller |
| Errors and rate limits | Error formats and retry rules for every API |
| Troubleshooting | Symptoms, causes and fixes |
Examples
TypeScript, no runtime dependencies. Node.js 22.18 or later runs the .ts files directly.
cd examples
cp .env.example .env # set UNIFI_HOST and UNIFI_API_KEY
node --env-file=.env list-devices.ts
| Script | API | What it does |
|---|---|---|
lib/integration.ts |
Network API | Client with pagination, filters, 429 handling, local or via Cloud Connector |
lib/site-manager.ts |
Site Manager | Client with nextToken paging |
lib/classic.ts |
Classic | Login, CSRF, 2FA, re-login, WebSocket |
list-hosts.ts |
Site Manager | Consoles and sites on your account |
list-devices.ts |
Network API | Adopted devices, with an optional filter |
list-clients.ts |
Network API | Connected clients, with an optional filter |
restart-device.ts |
Network API | Restart a device by MAC |
power-cycle-port.ts |
Network API | Power-cycle a PoE port |
authorize-guest.ts |
Network API | Authorize a hotspot guest |
create-vouchers.ts |
Network API | Generate hotspot vouchers |
block-client.ts |
Classic | Block, unblock or disconnect a client |
events-websocket.ts |
Classic | Live controller events, with reconnect |
Skill for Claude Code and Codex
skills/unifi-network teaches an AI coding agent the rules from this guide: which API to choose, site IDs, pagination and filters, actions, connector limits, classic login with CSRF and 2FA, units and the common version traps. It follows the Agent Skills format.
Claude Code
/plugin marketplace add uchkunr/unifi-best-practices
/plugin install unifi-network@unifi-best-practices
Codex
codex plugin marketplace add uchkunr/unifi-best-practices
codex plugin add unifi-network@unifi-best-practices
Manual install. Copy skills/unifi-network to ~/.claude/skills/ (Claude Code) or ~/.agents/skills/ (Codex), or to .claude/skills/ / .agents/skills/ inside one project.
License
- Documentation (
docs/, this README): CC BY 4.0. Share and adapt with attribution. - Code (
examples/,skills/) and code snippets in the docs: MIT (examples, skills).
Not affiliated with or endorsed by Ubiquiti. UniFi and Ubiquiti are trademarks of Ubiquiti Inc.
Reviews (0)
Sign in to leave a review.
Leave a reviewNo results found