proxmox/docs/04-configuration/UNIFI_API_COMPARISON.md

UniFi API Comparison Guide

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

---

Overview

Ubiquiti provides multiple APIs for managing UniFi deployments. This document compares the different API options available and helps you choose the right one for your needs.

API Types

1. Site Manager API (Cloud)

Base URL: https://api.ui.com/v1/
Authentication: API key from unifi.ui.com
Documentation: developer.ui.com/site-manager-api

Characteristics

• Location: Cloud-based (api.ui.com)
• Scope: Multiple UniFi deployments
• Status: Read-only (write operations planned)
• Rate Limits:
  • Early Access: 100 requests/min
  • v1 stable: 10,000 requests/min
• Use Case: Multi-site management, cloud-based monitoring

Available Endpoints

• /hosts - List all hosts
• /sites - List all sites
• /devices - List all devices
• /isp-metrics - ISP performance metrics
• /sd-wan-configs - SD-WAN configurations

When to Use

• Managing multiple UniFi deployments
• Cloud-based monitoring and analytics
• Centralized multi-site management
• ISP metrics and SD-WAN monitoring

---

2. Official Local API

Base URL: https://YOUR-UDM-IP/proxy/network/integration/v1/
Authentication: API key from local controller
Documentation: Available in UniFi Network app (Settings → Control Plane → Integrations)

Characteristics

• Location: Local (UDM Pro/Controller)
• Scope: Single controller/site
• Status: Limited endpoints (sites endpoint verified)
• Endpoints: Version-specific, documented in controller
• Use Case: Single-site automation with official API

Available Endpoints (Verified)

• /proxy/network/integration/v1/sites - List sites

Known Limitations

• Many endpoints return 404/400 errors
• Endpoint availability varies by version
• Limited documentation
• Fewer endpoints compared to Private API

When to Use

• Single-site automation
• Prefer official/supported API
• Limited functionality is acceptable
• Need API key authentication (not username/password)

---

3. Private Controller API

Base URL: https://YOUR-UDM-IP/proxy/network/api/s/{site}/
Authentication: Cookie-based session (username/password)
Documentation: Reverse-engineered, community-maintained

Characteristics

• Location: Local (UDM Pro/Controller)
• Scope: Single controller/site
• Status: Full functionality
• Endpoints: Comprehensive, reverse-engineered
• Use Case: Single-site automation with full control

Available Endpoints

• Sites, devices, clients, networks, VLANs
• WLANs, firewall rules, routing
• Events, alarms, system info
• Full read/write access

Known Limitations

• Requires local admin account
• Not compatible with 2FA/SSO
• Undocumented (reverse-engineered)
• May change between versions
• No official support

When to Use

• Single-site automation
• Need full functionality
• Can create local admin account without 2FA
• Comfortable with undocumented API

---

Comparison Table

Feature	Site Manager API	Official Local API	Private Local API
Location	Cloud	Local	Local
Scope	Multiple deployments	Single controller	Single controller
Authentication	API key (cloud)	API key (local)	Username/password
2FA/SSO Support	✅ Yes	✅ Yes	❌ No
Read/Write	Read-only	Read-only (limited)	Full access
Endpoints	Limited (cloud-focused)	Very limited	Comprehensive
Documentation	Official	Version-specific	Community
Rate Limits	Yes (100-10k/min)	No	No
Multi-site	✅ Yes	❌ No	❌ No
Stability	Stable (official)	Evolving	May change
Use Case	Cloud management	Simple automation	Full automation

Choosing the Right API

Use Site Manager API If:

• ✅ Managing multiple UniFi deployments
• ✅ Need cloud-based access
• ✅ Want official/supported API
• ✅ Monitoring multiple sites
• ✅ Need ISP metrics/SD-WAN data
• ✅ Read-only operations are sufficient

Use Official Local API If:

• ✅ Managing single site
• ✅ Prefer official API
• ✅ Have API key from local controller
• ✅ Limited functionality is acceptable
• ✅ Need API key authentication

Use Private Local API If:

• ✅ Managing single site
• ✅ Need full functionality
• ✅ Can create local admin (no 2FA)
• ✅ Comfortable with undocumented API
• ✅ Need write operations
• ✅ Need comprehensive endpoints

Integration Packages

This project provides integration packages for all APIs:

Site Manager API (Cloud)

• Package: site-manager-api
• MCP Server: mcp-site-manager
• CLI: site-manager-cli
• Setup: SITE_MANAGER_API_SETUP.md

Local APIs

• Package: unifi-api
• MCP Server: mcp-unifi
• CLI: unifi-cli
• Setup: UNIFI_API_SETUP.md

Using Multiple APIs Together

You can use multiple APIs simultaneously:

// Cloud API for multi-site overview
import { SiteManagerClient, SitesService } from 'site-manager-api';
const cloudClient = new SiteManagerClient({ apiKey: process.env.SITE_MANAGER_API_KEY });
const cloudSites = await new SitesService(cloudClient).listSites();

// Local API for detailed control
import { UnifiClient, DevicesService } from 'unifi-api';
const localClient = new UnifiClient({
  baseUrl: 'https://192.168.0.1',
  apiMode: ApiMode.OFFICIAL,
  apiKey: process.env.UNIFI_API_KEY,
});
const devices = await new DevicesService(localClient).listDevices();

Migration Guide

From Private API to Official API

Challenges:

• Limited endpoints in Official API
• Many operations not available
• Need to use API key instead of username/password

Recommendation:

• Use Official API for available endpoints
• Fall back to Private API for unsupported operations
• Consider Site Manager API for multi-site scenarios

From Local to Cloud (Site Manager)

Benefits:

• Multi-site management
• Centralized access
• Official/supported API

Limitations:

• Currently read-only
• Different endpoint structure
• Requires internet connectivity
• Rate limits apply

Documentation References

• Site Manager API Setup
• UniFi Local API Setup
• UniFi Endpoints Reference
• UniFi Configuration Status

Getting Help

• Site Manager API: developer.ui.com/site-manager-api
• Official Local API: Check UniFi Network app (Settings → Control Plane → Integrations)
• Private API: Ubiquiti Community Wiki