proxmox/docs/04-configuration/UDM_PRO_API_ENDPOINT_EXPLORATION.md

UDM Pro API Endpoint Exploration

Last Updated: 2025-01-20
Status: Active Documentation API Documentation: UniFi Network API Documentation

---

Overview

This document tracks the exploration of available API endpoints for the UDM Pro using the Official UniFi Network API (v1 integration endpoints).

Base URL: https://192.168.0.1/proxy/network/integration/v1/
Authentication: X-API-KEY header
Site ID: 88f7af54-98f8-306a-a1c7-c9349722b1f6 (Default site)

---

Available Endpoints

✅ Working Endpoints

Sites

• GET /proxy/network/integration/v1/sites
  • Status: ✅ Working
  • Description: List all sites
  • Response: { "offset": 0, "limit": 25, "count": N, "totalCount": N, "data": [...] }

Networks/VLANs

• GET /proxy/network/integration/v1/sites/{siteId}/networks

  • Status: ✅ Working
  • Description: List all networks/VLANs
  • Response: Paginated list of network configurations
  • Query Parameters: limit, offset

• GET /proxy/network/integration/v1/sites/{siteId}/networks/{networkId}

  • Status: ✅ Working
  • Description: Get detailed network configuration
  • Response: Network object with DHCP, IP configuration, etc.

Devices

• GET /proxy/network/integration/v1/sites/{siteId}/devices
  • Status: ✅ Working
  • Description: List all devices (gateways, switches, APs)
  • Response: Paginated list of devices

Clients

• GET /proxy/network/integration/v1/sites/{siteId}/clients
  • Status: ✅ Working
  • Description: List active clients/stations
  • Response: Paginated list of clients

---

Unavailable/Not Found Endpoints

❌ Firewall Rules

• GET /proxy/network/integration/v1/sites/{siteId}/firewall-rules

  • Status: ❌ 404 NOT_FOUND
  • Error: "No endpoint GET /integration/v1/sites/{siteId}/firewall-rules"
  • Note: Firewall rules may be available via Private API or different endpoint

• GET /proxy/network/integration/v1/sites/{siteId}/traffic-rules

  • Status: ❌ Tested but not confirmed
  • Note: May require different path or authentication

❌ Port Profiles

• GET /proxy/network/integration/v1/sites/{siteId}/port-profiles
  • Status: ❌ Tested but not confirmed
  • Note: Port configuration may be device-specific or require different endpoint

❌ DHCP Reservations

• GET /proxy/network/integration/v1/sites/{siteId}/dhcp-reservations
  • Status: ❌ Tested but not confirmed
  • Note: DHCP reservations may be network-scoped or require different endpoint

---

Network Configuration Details

Network Object Structure (Example: MGMT-LAN VLAN 11)

{
  "management": "GATEWAY",
  "id": "5797bd48-6955-4a7c-8cd0-72d8106d3ab2",
  "name": "MGMT-LAN",
  "enabled": true,
  "vlanId": 11,
  "metadata": {
    "origin": "USER_DEFINED"
  },
  "isolationEnabled": false,
  "cellularBackupEnabled": true,
  "internetAccessEnabled": true,
  "mdnsForwardingEnabled": true,
  "ipv4Configuration": {
    "autoScaleEnabled": true,
    "hostIpAddress": "192.168.11.1",
    "prefixLength": 24,
    "dhcpConfiguration": {
      "mode": "SERVER",
      "ipAddressRange": {},
      "leaseTimeSeconds": 86400,
      "domainName": "",
      "pingConflictDetectionEnabled": true
    },
    "natOutboundIpAddressConfiguration": []
  }
}

Observations

1. DHCP Configuration: Present in network object, but static reservations not visible in this endpoint
2. Network Isolation: isolationEnabled flag exists (can be queried, but modification endpoint unknown)
3. NAT Configuration: natOutboundIpAddressConfiguration array exists (empty in this example)

---

API Documentation Reference

For complete, version-specific API documentation:

1. Access UniFi Network Web UI: https://192.168.0.1
2. Navigate to: Settings → Control Plane → Integrations
3. View API Documentation: The console-specific documentation URL is available in the Integrations page
4. Console-Specific URL: https://unifi.ui.com/consoles/{consoleId}/unifi-api/network

Note: The console-specific documentation shows the exact endpoints available for your UDM Pro version and configuration.

---

Testing Script

A script has been created to test and verify available endpoints:

Script: scripts/unifi/check-current-config.sh

Usage:

cd /home/intlc/projects/proxmox
./scripts/unifi/check-current-config.sh

---

Next Steps

1. Review Console-Specific Documentation:

   • Access the web UI at https://192.168.0.1
   • Navigate to Settings → Control Plane → Integrations
   • Review the API documentation for available endpoints

2. Test Write Operations:

   • Many endpoints may support POST/PUT operations
   • Test with caution (read-only operations first)
   • Document successful write operations

3. Explore Device-Specific Endpoints:

   • Port configuration may be device-scoped
   • Test endpoints like /devices/{deviceId}/ports

4. Consider Private API:

   • Some operations may require Private API (cookie-based auth)
   • Private API has more endpoints but requires local admin account

---

Related Documentation

• UNIFI_ENDPOINTS_REFERENCE.md - Comprehensive API endpoints reference
• UDM_PRO_STATUS.md - Configuration status

---

Last Updated: 2025-01-20