proxmox/site-manager-api/README.md

Site Manager API Library

TypeScript library for interacting with Ubiquiti UniFi Site Manager Cloud API.

Features

• Type-safe API client with full TypeScript support
• Cloud-based API for managing multiple UniFi deployments at scale
• Support for hosts, sites, devices, ISP metrics, and SD-WAN configurations
• Built-in CLI tool for common operations
• Rate limiting handling with automatic retry-after support
• Comprehensive error handling

Installation

pnpm install
pnpm build

Usage

Basic Setup

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

const client = new SiteManagerClient({
  apiKey: 'your-api-key',
  baseUrl: 'https://api.ui.com/v1', // Optional, defaults to this
});

Getting an API Key

1. Sign in to the UniFi Site Manager at unifi.ui.com
2. Navigate to the API section from the left navigation bar
3. Select "Create API Key"
4. Copy the generated key and store it securely (shown only once)

Host Management

import { HostsService } from 'site-manager-api';

const hostsService = new HostsService(client);

// List all hosts
const hosts = await hostsService.listHosts();

Site Management

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

const sitesService = new SitesService(client);

// List all sites
const sites = await sitesService.listSites();

Device Management

import { DevicesService } from 'site-manager-api';

const devicesService = new DevicesService(client);

// List all devices
const devices = await devicesService.listDevices();

Metrics and SD-WAN

import { MetricsService } from 'site-manager-api';

const metricsService = new MetricsService(client);

// Get ISP metrics
const metrics = await metricsService.getISPMetrics();

// Query ISP metrics with filters
const queriedMetrics = await metricsService.queryISPMetrics({ /* filters */ });

// List SD-WAN configurations
const sdwanConfigs = await metricsService.listSDWANConfigs();

// Get SD-WAN config by ID
const config = await metricsService.getSDWANConfig('config-id');

// Get SD-WAN config status
const status = await metricsService.getSDWANConfigStatus('config-id');

CLI Tool

The library includes a CLI tool for common operations:

# Set environment variable
export SITE_MANAGER_API_KEY=your-api-key

# List hosts
site-manager-cli hosts

# List sites
site-manager-cli sites

# List devices
site-manager-cli devices

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

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

Or using pnpm:

pnpm site-manager:cli hosts
pnpm site-manager:cli sites
pnpm site-manager:cli devices

Environment Variables

Create a ~/.env file with:

SITE_MANAGER_API_KEY=your-api-key-here
SITE_MANAGER_BASE_URL=https://api.ui.com/v1  # Optional

Error Handling

The library provides specific error classes:

import {
  SiteManagerApiError,
  SiteManagerAuthenticationError,
  SiteManagerNetworkError,
  SiteManagerRateLimitError,
} from 'site-manager-api';

try {
  const sites = await sitesService.listSites();
} catch (error) {
  if (error instanceof SiteManagerRateLimitError) {
    console.log(`Rate limited. Retry after ${error.retryAfter} seconds`);
  } else if (error instanceof SiteManagerAuthenticationError) {
    console.error('Authentication failed - check your API key');
  } else if (error instanceof SiteManagerNetworkError) {
    console.error('Network error:', error.cause);
  } else {
    console.error('API error:', error);
  }
}

Rate Limiting

The Site Manager API has rate limits:

• Early Access (EA) version: 100 requests per minute
• v1 stable release: 10,000 requests per minute

If you exceed these limits, the library will throw a SiteManagerRateLimitError with a retryAfter property indicating when you can retry.

API Status

The Site Manager API is currently read-only. Write endpoints are planned for future versions.

Documentation

• Official Documentation
• API Reference

License

MIT