Skip to content

UniFi API

REST API service for querying UniFi network controllers. Supports multiple sites (UK and FR).

Overview

Property Value
Location hub2 (OVH Dedicated Server)
Container charliehub_unifi_api
Port 8002
URL https://unifi.charliehub.net

Controllers

Site Controller IP Network
UK UCG Ultra REDACTED_IP REDACTED_SUBNET
FR UCG Ultra REDACTED_IP REDACTED_SUBNET

API Endpoints

All endpoints accept ?site=uk or ?site=fr parameter (defaults to UK).

Health & Info

# Health check
curl https://unifi.charliehub.net/health

# List available controllers
curl https://unifi.charliehub.net/api/controllers

Clients & Devices

# Active clients (UK)
curl "https://unifi.charliehub.net/api/clients?site=uk"

# Active clients (FR)
curl "https://unifi.charliehub.net/api/clients?site=fr"

# All known devices
curl https://unifi.charliehub.net/api/devices

Networks & Port Forwards

# Networks/VLANs
curl "https://unifi.charliehub.net/api/networks?site=uk"

# Port forwards
curl "https://unifi.charliehub.net/api/port-forwards?site=uk"

Firewall Rules

# Traffic rules
curl "https://unifi.charliehub.net/api/firewall/rules?site=uk"

# Traffic routes
curl "https://unifi.charliehub.net/api/firewall/routes?site=uk"

Configuration

Environment variables in docker-compose.yml:

environment:
  - UNIFI_HOST_UK=https://REDACTED_IP
  - UNIFI_HOST_FR=https://REDACTED_IP
  - UNIFI_USERNAME=${UNIFI_USERNAME}
  - UNIFI_PASSWORD=${UNIFI_PASSWORD}
  - UNIFI_SITE=default

Authentication

The API uses cookie-based session authentication with the UniFi controllers. Sessions are cached and refreshed automatically.

Supports 2FA via TOTP if configured: 

- UNIFI_TOTP_SECRET=${UNIFI_TOTP_SECRET}  # Optional

Web UI

Access the UniFi API explorer at https://unifi.charliehub.net (requires Authelia login).

Direct controller access: - UK: https://REDACTED_IP (via WireGuard) - FR: https://REDACTED_IP (via WireGuard)

Common Tasks

Check Client Connectivity

# See all connected clients across both sites
curl -s "https://unifi.charliehub.net/api/clients?site=uk" | jq '.data | length'
curl -s "https://unifi.charliehub.net/api/clients?site=fr" | jq '.data | length'

Find Device by MAC

curl -s "https://unifi.charliehub.net/api/clients?site=uk" | \
  jq '.data[] | select(.mac == "aa:bb:cc:dd:ee:ff")'

List Port Forwards

curl -s "https://unifi.charliehub.net/api/port-forwards?site=uk" | \
  jq '.data[] | {name, dst_port, fwd_ip, fwd_port, enabled}'

Troubleshooting

API Returns 401

Session expired or credentials invalid:

# Check container logs
docker logs charliehub_unifi_api --tail 50

# Verify controller is reachable
curl -sk https://REDACTED_IP/api/auth/login

Controller Unreachable

Ensure WireGuard VPN is connected:

# From hub2
sudo wg show
ping REDACTED_IP
ping REDACTED_IP

Historical Note

Previously, UniFi was managed via Terraform on VM1111. This was deprecated when services were migrated to hub2. The UniFi API now provides read-only access to controller data. For configuration changes, use the UniFi controller UI directly.