proxmox/docs/04-configuration/SITE_MANAGER_API_SETUP.md

Site Manager API Setup Guide

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

---

Overview

This guide covers setting up API integration for Ubiquiti UniFi Site Manager Cloud API using the Site Manager API library and MCP server.

The Site Manager API is a cloud-based API that allows you to manage multiple UniFi deployments at scale through the UniFi Site Manager portal (unifi.ui.com).

Prerequisites

• UniFi account with access to Site Manager (unifi.ui.com)
• Node.js 18+ and pnpm installed
• API key from UniFi Site Manager

Key Differences from Local APIs

Feature	Site Manager API (Cloud)	Local APIs
Location	Cloud (api.ui.com)	Local (UDM Pro IP)
Scope	Multiple deployments	Single controller
Auth	API key (cloud)	API key (local) or username/password
Use Case	Multi-site management	Single site automation

Step 1: Get API Key

1. Sign in to UniFi Site Manager

   • Go to unifi.ui.com
   • Sign in with your UniFi account

2. Navigate to API Section

   • Click on "API" in the left navigation bar
   • Or go directly to the API settings page

3. Create API Key

   • Click "Create API Key"
   • Copy the generated key immediately
   • Important: The key is shown only once - store it securely!

4. Store the API Key

   • The key will be used in environment variables
   • Keep it secure - it provides access to your UniFi deployments

Step 2: Configure Environment Variables

Create or update ~/.env file:

# Site Manager API Configuration
SITE_MANAGER_API_KEY=your-api-key-here
SITE_MANAGER_BASE_URL=https://api.ui.com/v1  # Optional, this is the default

Security Notes:

• Never commit the .env file to version control
• Store the API key securely
• Rotate the key periodically if needed

Step 3: Install and Build

# Install dependencies
pnpm install

# Build packages
pnpm site-manager:build

Step 4: Test the Integration

Using CLI Tool

# List hosts
pnpm site-manager:cli hosts

# List sites
pnpm site-manager:cli sites

# List devices
pnpm site-manager:cli devices

# Get ISP metrics
pnpm site-manager:cli isp-metrics

# List SD-WAN configurations
pnpm site-manager:cli sd-wan-configs

Using Node.js

import { SiteManagerClient, SitesService } from 'site-manager-api';

const client = new SiteManagerClient({
  apiKey: process.env.SITE_MANAGER_API_KEY!,
});

const sitesService = new SitesService(client);
const sites = await sitesService.listSites();
console.log(sites);

Step 5: MCP Server Setup (Optional)

For Claude Desktop

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "site-manager": {
      "command": "node",
      "args": [
        "/path/to/proxmox/mcp-site-manager/dist/index.js"
      ]
    }
  }
}

The server will automatically load environment variables from ~/.env.

Start MCP Server

# Start server
pnpm site-manager:start

# Development mode (with auto-reload)
pnpm site-manager:dev

Available Endpoints

The Site Manager API provides access to:

• Hosts: List all hosts across deployments
• Sites: List all sites
• Devices: List all devices across deployments
• ISP Metrics: Get ISP performance metrics
• SD-WAN Configs: List and query SD-WAN configurations

API Status

• Current Status: Read-only
• Write Operations: Planned for future versions
• Rate Limits:
  • Early Access (EA): 100 requests per minute
  • v1 stable: 10,000 requests per minute

Rate Limiting

If you exceed rate limits, the API will return a 429 Too Many Requests status with a Retry-After header. The library handles this automatically by throwing a SiteManagerRateLimitError with the retry time.

Troubleshooting

Authentication Errors

• Verify SITE_MANAGER_API_KEY is correct
• Check that the API key hasn't expired or been revoked
• Ensure the API key was created from unifi.ui.com (not local controller)
• Test the API key with curl:

  curl -X GET 'https://api.ui.com/v1/hosts' \
    -H 'X-API-KEY: YOUR_API_KEY' \
    -H 'Accept: application/json'
  

Connection Errors

• Verify internet connectivity
• Check that api.ui.com is accessible
• Ensure firewall allows outbound HTTPS connections
• Verify DNS resolution for api.ui.com

Rate Limit Errors

• Check your API version (EA vs v1)
• Implement exponential backoff
• Reduce request frequency
• Use the retryAfter value from the error to wait before retrying

Documentation References

• Official Site Manager API Documentation
• Site Manager API Library README
• MCP Server README

Next Steps

• Explore available endpoints in the API documentation
• Integrate with your automation workflows
• Set up monitoring for rate limits
• Consider caching responses for frequently accessed data