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](https://unifi.ui.com/consoles/70A74178A0F2000000000673F1400000000006C1406100000000629EBD6D:568528603/unifi-api/network)

---

## 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)

```json
{
  "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:**
```bash
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](./UNIFI_ENDPOINTS_REFERENCE.md) - Comprehensive API endpoints reference
- [UDM_PRO_STATUS.md](./UDM_PRO_STATUS.md) - Configuration status

---

**Last Updated:** 2025-01-20