# 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](https://developer.ui.com/site-manager-api/gettingstarted)

#### 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](./SITE_MANAGER_API_SETUP.md)

### Local APIs

- **Package**: `unifi-api`
- **MCP Server**: `mcp-unifi`
- **CLI**: `unifi-cli`
- **Setup**: [UNIFI_API_SETUP.md](./UNIFI_API_SETUP.md)

## Using Multiple APIs Together

You can use multiple APIs simultaneously:

```typescript
// 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](./SITE_MANAGER_API_SETUP.md)
- [UniFi Local API Setup](./UNIFI_API_SETUP.md)
- [UniFi Endpoints Reference](./UNIFI_ENDPOINTS_REFERENCE.md)
- [UniFi Configuration Status](./UNIFI_CONFIGURATION_STATUS.md)

## Getting Help

- **Site Manager API**: [developer.ui.com/site-manager-api](https://developer.ui.com/site-manager-api/gettingstarted)
- **Official Local API**: Check UniFi Network app (Settings → Control Plane → Integrations)
- **Private API**: [Ubiquiti Community Wiki](https://www.ubntwiki.com/products/software/unifi-controller/api)