# unifi-network

> Interact with UniFi Network controllers via the LOCAL Integration API v1 (NOT the cloud Site Manager API). Use when: (1) querying network devices, clients, or statistics, (2) managing networks, WiFi SSIDs, firewall zones, ACL rules, (3) generating/managing hotspot vouchers, (4) listing VPN servers, WAN interfaces, RADIUS profiles. Supports UDM, UDM-Pro, UDM-SE, and Cloud Key controllers with full CRUD operations.

- Author: Bryan Li
- Repository: btli/skills
- Version: 20251214122149
- Stars: 0
- Forks: 0
- Last Updated: 2026-02-07
- Source: https://github.com/btli/skills
- Web: https://mule.run/skillshub/@@btli/skills~unifi-network:20251214122149

---

---
name: unifi-network
description: |
  Interact with UniFi Network controllers via the LOCAL Integration API v1 (NOT the cloud Site Manager API). Use when: (1) querying network devices, clients, or statistics, (2) managing networks, WiFi SSIDs, firewall zones, ACL rules, (3) generating/managing hotspot vouchers, (4) listing VPN servers, WAN interfaces, RADIUS profiles. Supports UDM, UDM-Pro, UDM-SE, and Cloud Key controllers with full CRUD operations.
---

# UniFi Network Integration API (Local)

Query and manage UniFi Network controllers using the **local** Integration API v1.

> **Important:** This is the **LOCAL Integration API** that runs on your UniFi controller (UDM/Cloud Key), NOT the cloud-based Site Manager API at `api.ui.com`. The Site Manager API is for remote management via Ubiquiti's cloud; this API connects directly to your controller on your local network.

## Configuration

```bash
export UNIFI_HOST="172.16.0.1"
export UNIFI_NETWORK_API_KEY="your-api-key"
export UNIFI_SITE_ID="default"
```

Retrieve API key from Phase:
```bash
export UNIFI_NETWORK_API_KEY=$(phase secrets get UNIFI_NETWORK_API_KEY --app claude-code --env development | jq -r .value)
```

## Quick Start

```bash
# Controller info
scripts/unifi info

# List sites (get site IDs)
scripts/unifi sites

# List devices
scripts/unifi devices --site default

# List clients with filter
scripts/unifi clients --site default --filter "hostname.like('iPhone*')"
```

## Commands

### Global (no site required)
| Command | Description |
|---------|-------------|
| `info` | Controller system info |
| `sites` | List all sites |
| `pending` | List pending devices |
| `countries` | List country codes |
| `dpi-apps` | List DPI applications |
| `dpi-categories` | List DPI categories |

### Site-Scoped (require `--site`)
| Command | Description |
|---------|-------------|
| `devices` | List adopted devices |
| `device <id>` | Get device details |
| `device-stats <id>` | Get device statistics |
| `clients` | List connected clients |
| `client <id>` | Get client details |
| `networks` | List networks |
| `network <id>` | Get network details |
| `wifi` | List WiFi broadcasts |
| `wifi-detail <id>` | Get WiFi details |
| `vouchers` | List hotspot vouchers |
| `firewall-zones` | List firewall zones |
| `acl-rules` | List ACL rules |
| `traffic-lists` | List traffic matching lists |
| `wans` | List WAN interfaces |
| `vpn-servers` | List VPN servers |
| `vpn-tunnels` | List site-to-site tunnels |
| `radius` | List RADIUS profiles |

## Options

- `--host <ip>` - Override UNIFI_HOST
- `--site <id>` - Override UNIFI_SITE_ID
- `--filter <expr>` - Filter expression
- `--limit <n>` - Results per page (max 200)
- `--offset <n>` - Pagination offset
- `--raw` - Raw JSON output

## Filtering

Use `--filter` with property expressions:

```bash
# Pattern matching
--filter "name.like('Guest*')"

# Equality
--filter "state.eq('CONNECTED')"

# Compound
--filter "and(enabled.eq(true), name.like('Office*'))"

# Negation
--filter "not(expired.eq(true))"
```

Functions: `eq`, `ne`, `gt`, `ge`, `lt`, `le`, `like`, `in`, `notIn`, `isNull`, `isNotNull`, `contains`, `containsAny`, `containsAll`

## Direct API Access

For write operations (create/update/delete), use curl directly:

```bash
# Create network
curl -sk -X POST "https://${UNIFI_HOST}/proxy/network/integration/v1/sites/${UNIFI_SITE_ID}/networks" \
  -H "X-API-KEY: ${UNIFI_NETWORK_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{"name": "Guest", "vlanId": 100, ...}'

# Delete voucher
curl -sk -X DELETE "https://${UNIFI_HOST}/proxy/network/integration/v1/sites/${UNIFI_SITE_ID}/hotspot/vouchers?filter=expired.eq(true)" \
  -H "X-API-KEY: ${UNIFI_NETWORK_API_KEY}"
```

## Resources

- [references/api-endpoints.md](references/api-endpoints.md) - Endpoint reference with filtering
- [references/openapi.json](references/openapi.json) - Full OpenAPI 3.1 spec with schemas

## Common Tasks

### Find disconnected devices
```bash
scripts/unifi devices --site default | jq '.data[] | select(.state != "CONNECTED")'
```

### List wireless clients
```bash
scripts/unifi clients --site default --filter "type.eq('WIRELESS')"
```

### Get device uptime
```bash
scripts/unifi device-stats <device-id> --site default | jq '.uptime'
```

### List active vouchers
```bash
scripts/unifi vouchers --site default --filter "not(expired.eq(true))"
```