proxmox/docs/04-configuration/UNIFI_ENDPOINTS_REFERENCE.md

# UniFi API Endpoints Reference

**Last Updated:** 2025-01-20  
**Document Version:** 1.0
**Status:** Active Documentation

---

## Overview

This document provides a reference for UniFi Controller API endpoints. The UniFi API has two modes:

1. **Official Local API** (v1 endpoints) - Documented, version-specific
2. **Private Controller API** (proxy/network endpoints) - Reverse-engineered, may vary between versions

## Important Notes

- **Official API endpoints** are version-specific and available in your UniFi Network app (Settings → Control Plane → Integrations)
- **Private API endpoints** are reverse-engineered and may change between releases
- **UDM Pro** uses `/proxy/network` prefix for all Network API paths
- For complete, up-to-date documentation, check your UniFi Network app's Integrations page

## Official Local API (v1 endpoints)

### Base Path
```
/proxy/network/integration/v1/
```

### Authentication
```
X-API-KEY: {apiKey}
Accept: application/json
```

### Known Endpoints (Verified)

#### Sites
- `GET /proxy/network/integration/v1/sites` - List all sites
  - Response format: `{ "offset": 0, "limit": 25, "count": N, "totalCount": N, "data": [...] }`
  - Site objects contain: `{ "internalReference": "site-id", "name": "Site Name" }`

### Endpoint Discovery Notes

**Site ID Format:**
- Use the `internalReference` value from the sites list as the site ID
- The value "default" may not work - use the actual `internalReference` value from the sites response

**Available Endpoints:**
- The Official API endpoints are version-specific and limited
- Many endpoints return 404 (NOT_FOUND) or 400 (BAD_REQUEST) errors
- Endpoint availability depends on your UniFi Network app version

**Recommendation:**
- Check your UniFi Network app's Integrations page (Settings → Control Plane → Integrations) for complete, version-specific endpoint documentation
- The Official API may have fewer endpoints available compared to the Private API
- Consider using Private API for endpoints not available in Official API

### Documentation Sources

For complete endpoint documentation:
1. Access your UniFi Network app
2. Navigate to: **Settings → Control Plane → Integrations**
3. View the version-specific API documentation
4. Look for OpenAPI/Swagger specification if available

## Private Controller API (proxy/network endpoints)

### Base Path
```
/proxy/network/api/s/{site}/
```

### Authentication
- Cookie-based session (obtained via `POST /api/auth/login`)
- Login endpoint: `/api/auth/login` (not prefixed)

### Controller/Global Endpoints

#### Authentication
- `POST /api/auth/login` - Login (save cookie)
- `POST /api/logout` - Logout
- `GET /api/self` - Get current user info
- `GET /api/self/sites` - List sites
- `GET /api/stat/sites` - Site statistics
- `GET /api/stat/admin` - Admin statistics

### Site-Scoped Endpoints

#### Health / Identity / System Info
- `GET /api/s/{site}/self` - Site self info
- `GET /api/s/{site}/stat/health` - Site health status
- `GET /api/s/{site}/stat/sysinfo` - System information
- `GET /api/s/{site}/stat/ccode` - Country code
- `GET /api/s/{site}/stat/current-channel` - Current channel info

#### Events / Alarms
- `GET /api/s/{site}/stat/event` - List events
- `GET /api/s/{site}/rest/event` - REST events (varies by version)
- `GET /api/s/{site}/stat/alarm` - List alarms
- `GET /api/s/{site}/rest/alarm` - REST alarms (+ `?archived=false`)

#### Clients
- `GET /api/s/{site}/stat/sta` - Active clients
- `GET /api/s/{site}/rest/user` - Known/configured clients
- `POST /api/s/{site}/rest/user` - Create client
- `PUT /api/s/{site}/rest/user/{userId}` - Update client
- `POST /api/s/{site}/upd/user/{userId}` - Update client (alternative)

#### Devices
- `GET /api/s/{site}/stat/device-basic` - Basic device list
- `GET /api/s/{site}/stat/device` - Device list
- `POST /api/s/{site}/stat/device` - Filter devices by MAC list
- `GET /api/s/{site}/stat/device/{mac}` - Get device by MAC (UDM variant)
- `PUT /api/s/{site}/rest/device/{_id}` - Update device

#### Networks / VLANs
- `GET /api/s/{site}/rest/networkconf` - List networks/VLANs
- `PUT /api/s/{site}/rest/networkconf/{_id}` - Update network

#### WLANs
- `GET /api/s/{site}/rest/wlanconf` - List WLAN configurations
- `GET /api/s/{site}/rest/wlanconf/{_id}` - Get WLAN by ID
- `PUT /api/s/{site}/rest/wlanconf/{_id}` - Update WLAN

#### Firewall / Routing
- `GET /api/s/{site}/rest/firewallrule` - List firewall rules
- `PUT /api/s/{site}/rest/firewallrule/{_id}` - Update firewall rule
- `GET /api/s/{site}/rest/firewallgroup` - List firewall groups
- `GET /api/s/{site}/stat/routing` - Routing statistics
- `GET /api/s/{site}/rest/routing` - Routing configuration (varies by version)
- `GET /api/s/{site}/stat/portforward` - Port forwarding rules
- `PUT /api/s/{site}/rest/portforward/{rule-id}` - Update port forward rule

#### Traffic Rules (v2 style)
- `GET /v2/api/site/{site}/trafficrules` - List traffic rules
- `POST /v2/api/site/{site}/trafficrules` - Create traffic rule
- `PUT /v2/api/site/{site}/trafficrules/{id}/` - Update traffic rule
- `DELETE /v2/api/site/{site}/trafficrules/{id}/` - Delete traffic rule

#### Hotspot
- `GET /guest/s/{site}/hotspotconfig` - Hotspot configuration
- `GET /guest/s/{site}/hotspotpackages` - Hotspot packages

### System Operations (UDM-level)

**Note:** These require Super Admin rights and `X-CSRF-Token` header

- `POST /api/system/poweroff` - Power off system
- `POST /api/system/reboot` - Reboot system

## Response Format

### Private API Response

```json
{
  "meta": {
    "rc": "ok"
  },
  "data": [...]
}
```

- `meta.rc`: `"ok"` for success, `"error"` for failure
- `meta.msg`: Error message if `rc` is `"error"`
- `data`: Array of response objects

### Official API Response

Format varies - see your UniFi Network app's Integrations documentation.

## Getting Complete Endpoint Documentation

### For Official API

1. Access your UniFi Network app
2. Navigate to **Settings → Control Plane → Integrations**
3. View the API documentation (version-specific)
4. Look for OpenAPI/Swagger spec if available

### For Private API

- See [Ubiquiti Community Wiki](https://www.ubntwiki.com/products/software/unifi-controller/api)
- Note: Endpoints are reverse-engineered and may vary between versions

## Usage with unifi-api Library

The `unifi-api` library abstracts endpoint differences based on API mode. Use the service classes:

```typescript
import { UnifiClient, ApiMode } from 'unifi-api';

const client = new UnifiClient({
  baseUrl: 'https://192.168.1.1',
  apiMode: ApiMode.PRIVATE, // or ApiMode.OFFICIAL
  // ... credentials
});

// Services handle endpoint construction automatically
const devices = await devicesService.listDevices();
```

## References

- [Getting Started with the Official UniFi API](https://help.ui.com/hc/en-us/articles/30076656117655-Getting-Started-with-the-Official-UniFi-API)
- [External Hotspot API for Authorization Clients](https://help.ui.com/hc/en-us/articles/31228198640023-External-Hotspot-API-for-Authorization-Clients)
- [Ubiquiti Community Wiki - UniFi Controller API](https://www.ubntwiki.com/products/software/unifi-controller/api)