d-bis/proxmox
4
0
Fork 0
Code Issues Pull Requests Actions 1 Packages Projects Releases Wiki Activity
Files
3e9645274a5f6e2cbc5bae1dff55d3aed0295cbf
proxmox/docs/04-configuration/UNIFI_API_COMPARISON.md
defiQUG fbda1b4beb
Some checks failed
Deploy to Phoenix / deploy (push) Has been cancelled
Details
docs: Ledger Live integration, contract deploy learnings, NEXT_STEPS updates 
- ADD_CHAIN138_TO_LEDGER_LIVE: Ledger form done; public code review repo bis-innovations/LedgerLive; init/push commands
- CONTRACT_DEPLOYMENT_RUNBOOK: Chain 138 gas price 1 gwei, 36-addr check, TransactionMirror workaround
- CONTRACT_*: AddressMapper, MirrorManager deployed 2026-02-12; 36-address on-chain check
- NEXT_STEPS_FOR_YOU: Ledger done; steps completable now (no LAN); run-completable-tasks-from-anywhere
- MASTER_INDEX, OPERATOR_OPTIONAL, SMART_CONTRACTS_INVENTORY_SIMPLE: updates
- LEDGER_BLOCKCHAIN_INTEGRATION_COMPLETE: bis-innovations/LedgerLive reference

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-02-12 15:46:57 -08:00

241 lines
6.9 KiB
Markdown
Raw Blame History

# 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)
Reference in New Issue View Git Blame Copy Permalink