proxmox/unifi-api

UniFi API Library

TypeScript library for interacting with Ubiquiti UniFi/UDM Pro Controller REST API.

Features

• Type-safe API client with full TypeScript support
• Dual API mode support:
  • Official Local API (v1 endpoints) - API key authentication
  • Private Controller API (proxy/network endpoints) - Cookie-based session authentication
• Support for all UniFi devices (APs, switches, gateways)
• Complete device, client, network, and system management
• Built-in CLI tool for common operations

Installation

pnpm install
pnpm build

Usage

Basic Setup

Official API Mode (API Key)

import { UnifiClient, ApiMode } from 'unifi-api';

const client = new UnifiClient({
  baseUrl: 'https://192.168.1.1',
  apiMode: ApiMode.OFFICIAL,
  apiKey: 'your-api-key',
  siteId: 'default', // Optional
  verifySSL: false, // Set to true for production
});

Private API Mode (Username/Password)

import { UnifiClient, ApiMode } from 'unifi-api';

const client = new UnifiClient({
  baseUrl: 'https://192.168.1.1',
  apiMode: ApiMode.PRIVATE,
  username: 'admin',
  password: 'password',
  siteId: 'default', // Optional
  verifySSL: false, // Set to true for production
});

Device Management

import { DevicesService } from 'unifi-api';

const devicesService = new DevicesService(client);

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

// Get device by MAC address
const device = await devicesService.getDevice('aa:bb:cc:dd:ee:ff');

// Get device statistics
const stats = await devicesService.getDeviceStats();

Client Management

import { ClientsService } from 'unifi-api';

const clientsService = new ClientsService(client);

// List active clients
const clients = await clientsService.listClients();

// Get client by ID or MAC
const client = await clientsService.getClient('client-id-or-mac');

// Authorize guest access (Official API only)
await clientsService.authorizeGuest('client-id', {
  action: 'AUTHORIZE_GUEST_ACCESS',
  timeLimit: 3600,
  dataLimit: 1073741824, // 1GB in bytes
});

Network Management

import { NetworksService } from 'unifi-api';

const networksService = new NetworksService(client);

// List all networks
const networks = await networksService.listNetworks();

// Get network by ID
const network = await networksService.getNetwork('network-id');

Site Management

import { SitesService } from 'unifi-api';

const sitesService = new SitesService(client);

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

// Get site statistics
const stats = await sitesService.getSiteStats();

WLAN Management

import { WlansService } from 'unifi-api';

const wlansService = new WlansService(client);

// List all WLANs
const wlans = await wlansService.listWlans();

// Get WLAN by ID
const wlan = await wlansService.getWlan('wlan-id');

Events & Alarms

import { EventsService } from 'unifi-api';

const eventsService = new EventsService(client);

// List events
const events = await eventsService.listEvents(100);

// List alarms
const alarms = await eventsService.listAlarms(false);

System Operations

import { SystemService } from 'unifi-api';

const systemService = new SystemService(client);

// Get system information
const info = await systemService.getSystemInfo();

// Get health status
const health = await systemService.getHealth();

// Reboot system (requires Super Admin)
// await systemService.reboot();

CLI Tool

The library includes a CLI tool for common operations:

# Set environment variables in ~/.env
UNIFI_UDM_URL=https://192.168.1.1
UNIFI_API_MODE=private
UNIFI_USERNAME=admin
UNIFI_PASSWORD=password
UNIFI_SITE_ID=default

# List sites
unifi-cli sites

# List devices
unifi-cli devices

# Get device by MAC
unifi-cli device aa:bb:cc:dd:ee:ff

# List clients
unifi-cli clients

# Get client by ID
unifi-cli client client-id-or-mac

# List networks
unifi-cli networks

# UDM Pro config (Private API)
unifi-cli system-info     # Controller / self info
unifi-cli health          # Site health status
unifi-cli sysinfo         # System stats
unifi-cli firewall-rules  # Firewall rules
unifi-cli port-forward    # Port forwarding rules
unifi-cli config          # Dump full config summary (sysinfo, health, networks, firewall, port-forward)

API Modes

Official Local API (v1 endpoints)

• Authentication: API key (Bearer token)
• Endpoints: /v1/sites/{siteId}/...
• Documentation: Available in UniFi Network app (Settings → Control Plane → Integrations)
• API Key: Generate from Integrations page in UniFi Network app

Private Controller API (proxy/network endpoints)

• Authentication: Cookie-based session (username/password)
• Endpoints: /proxy/network/api/s/{site}/...
• Documentation: Reverse-engineered, may vary between versions
• Login: POST /api/auth/login with username/password

Notes

• UDM Pro uses /proxy/network prefix for all Network API paths
• Official API endpoints are version-specific
• Private API endpoints are reverse-engineered and may change between releases
• SSL verification is disabled by default (set verifySSL: true for production)

License

MIT