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

{
  "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
• 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:

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
• External Hotspot API for Authorization Clients
• Ubiquiti Community Wiki - UniFi Controller API