proxmox/docs/04-configuration/UDM_PRO_API_ACCESS_TEST_RESULTS.md

# UDM Pro API Access Test Results

**Last Updated:** 2025-01-20  
**Status:** Active Documentation
**API Key:** `_6WXEiH2tMDkrO3jKc54SKa53fHZE-Wg`  
**Site ID:** `88f7af54-98f8-306a-a1c7-c9349722b1f6`  
**Test Date:** 2025-01-20

---

## Overview

This document contains test results for the Official UniFi Network API (v1 integration endpoints) using the local API key. Tests were performed to identify available endpoints, access levels (read/write), and limitations.

**Important:** All API calls are made to the **local UDM Pro** at `192.168.0.1`. This is **not** the cloud-based Site Manager API. All limitations documented here are specific to the local Official UniFi Network API.

**Base URL:** `https://192.168.0.1/proxy/network/integration/v1/`

---

## Test Results Summary

### ✅ Available Endpoints (Read Access)

| Endpoint | Method | Status | Description |
|----------|--------|--------|-------------|
| `/sites` | GET | ✅ Working | List all sites |
| `/sites/{siteId}/networks` | GET | ✅ Working | List networks/VLANs |
| `/sites/{siteId}/networks/{networkId}` | GET | ✅ Working | Get network details |
| `/sites/{siteId}/devices` | GET | ✅ Working | List devices |
| `/sites/{siteId}/clients` | GET | ✅ Working | List clients |
| `/sites/{siteId}/acl-rules` | GET | ✅ Working | List ACL/firewall rules |
| `/sites/{siteId}/firewall/zones` | GET | ✅ Working | List firewall zones |
| `/sites/{siteId}/traffic-matching-lists` | GET | ✅ Working | List traffic matching lists |
| `/sites/{siteId}/wans` | GET | ✅ Working | List WAN interfaces |
| `/info` | GET | ✅ Working | Application information |

### ✅ Available Endpoints (Write Access - Confirmed)

| Endpoint | Method | Status | Description |
|----------|--------|--------|-------------|
| `/sites/{siteId}/acl-rules` | POST/PUT/DELETE | ✅ Working | Create/update/delete ACL rules |
| `/sites/{siteId}/firewall/zones` | POST/PUT/DELETE | ✅ Working | Create/update/delete firewall zones |
| `/sites/{siteId}/traffic-matching-lists` | POST/PUT/DELETE | ✅ Working | Create/update/delete traffic matching lists |

### ❌ Unavailable Endpoints

| Endpoint | Method | Status | Expected Error |
|----------|--------|--------|----------------|
| `/sites/{siteId}/dhcp-reservations` | GET | ❌ 404 NOT_FOUND | DHCP reservations not available |
| `/sites/{siteId}/port-profiles` | GET | ❌ 404 NOT_FOUND | Port profiles not available |
| `/sites/{siteId}/wans/{wanId}` | GET | ❌ 404 NOT_FOUND | Individual WAN details not available |

---

## Detailed Test Results

### 1. Sites Endpoint

**Endpoint:** `GET /proxy/network/integration/v1/sites`

**Result:** ✅ **Working**

**Response:**
```json
{
    "offset": 0,
    "limit": 25,
    "count": 1,
    "totalCount": 1,
    "data": [
        {
            "id": "88f7af54-98f8-306a-a1c7-c9349722b1f6",
            "internalReference": "default",
            "name": "Default"
        }
    ]
}
```

---

### 2. Networks Endpoint

**Endpoint:** `GET /proxy/network/integration/v1/sites/{siteId}/networks`

**Result:** ✅ **Working**

**Response:** Returns list of all networks/VLANs (19 networks - 18 VLANs + 1 default network)

**Access Level:** Read access confirmed

---

### 3. ACL Rules Endpoint

**Endpoint:** `GET /proxy/network/integration/v1/sites/{siteId}/acl-rules`

**Result:** ✅ **Working**

**Response:** Returns list of ACL/firewall rules (4 rules confirmed)

**Access Level:** Read and Write access confirmed (POST/PUT/DELETE available)

---

### 4. Devices Endpoint

**Endpoint:** `GET /proxy/network/integration/v1/sites/{siteId}/devices`

**Result:** ✅ **Working**

**Response:** Returns list of devices (1 device confirmed - UDM Pro)

**Access Level:** Read access confirmed

---

### 5. Clients Endpoint

**Endpoint:** `GET /proxy/network/integration/v1/sites/{siteId}/clients`

**Result:** ✅ **Working**

**Response:** Returns list of active clients

**Access Level:** Read access confirmed

---

### 6. WANs Endpoint

**Endpoint:** `GET /proxy/network/integration/v1/sites/{siteId}/wans`

**Result:** ✅ **Working**

**Response:** Returns list of WAN interfaces (2 WANs - Internet 1, Internet 2)

**Access Level:** Read access confirmed

**Note:** Individual WAN details endpoint (`/wans/{wanId}`) returns 404 NOT_FOUND

---

### 7. Firewall Zones Endpoint

**Endpoint:** `GET /proxy/network/integration/v1/sites/{siteId}/firewall/zones`

**Result:** ✅ **Working**

**Response:** Returns list of firewall zones

**Access Level:** Read and Write access confirmed (POST/PUT/DELETE available)

---

### 8. Traffic Matching Lists Endpoint

**Endpoint:** `GET /proxy/network/integration/v1/sites/{siteId}/traffic-matching-lists`

**Result:** ✅ **Working**

**Response:** Returns list of traffic matching lists

**Access Level:** Read and Write access confirmed (POST/PUT/DELETE available)

---

### 9. Application Info Endpoint

**Endpoint:** `GET /proxy/network/integration/v1/info`

**Result:** ✅ **Working**

**Response:**
```json
{
    "applicationVersion": "10.0.162"
}
```

---

### 10. DHCP Reservations Endpoint

**Endpoint:** `GET /proxy/network/integration/v1/sites/{siteId}/dhcp-reservations`

**Result:** ❌ **NOT AVAILABLE**

**Error:** 404 NOT_FOUND - "No endpoint GET /integration/v1/sites/{siteId}/dhcp-reservations"

**Conclusion:** DHCP static IP reservations are not available via the Official API

---

### 11. Port Profiles Endpoint

**Endpoint:** `GET /proxy/network/integration/v1/sites/{siteId}/port-profiles`

**Result:** ❌ **NOT AVAILABLE**

**Error:** 404 NOT_FOUND

**Conclusion:** Port profiles are not available via the Official API

---

## API Limitations Summary

### Read-Only Limitations

The following configuration items cannot be read or modified via the Official API:

1. **DHCP Static IP Reservations**
   - Not available via API
   - Requires manual configuration via web UI

2. **Port Profiles**
   - Not available via API
   - Requires manual configuration via web UI

3. **Individual WAN Details**
   - List endpoint works, but individual WAN details endpoint returns 404
   - WAN configuration may require web UI

### Write Access Limitations

While many endpoints support write operations (POST/PUT/DELETE), the following limitations apply:

1. **Network Creation/Modification**
   - Read access confirmed
   - Write access not tested (may require specific permissions)

2. **ACL Rules Limitations**
   - Write access confirmed
   - Known limitation: Cannot create rules blocking overlapping source/destination networks
   - See [UDM_PRO_FIREWALL_API_LIMITATIONS.md](./UDM_PRO_FIREWALL_API_LIMITATIONS.md) for details

3. **System Settings**
   - Not available via API (hostname, timezone, NTP, backups)
   - Requires manual configuration via web UI

---

## Access Level Summary

### Full Read/Write Access ✅

- ACL Rules (with limitations)
- Firewall Zones
- Traffic Matching Lists

### Read-Only Access ✅

- Sites
- Networks/VLANs
- Devices
- Clients
- WANs (list only)

### No Access ❌

- DHCP Reservations
- Port Profiles
- System Settings
- Individual WAN Details

---

## Comparison with Previous API Key

**Previous API Key:** `W01fuZ_tdN6NdpknSetrdcOAra2moezk` (sankofa)

**New API Key:** `_6WXEiH2tMDkrO3jKc54SKa53fHZE-Wg`

**Results:** ✅ Access levels appear identical - no changes in available endpoints or permissions detected.

---

## Recommendations

1. **Use API for:**
   - Reading network/VLAN configuration
   - Reading device and client information
   - Creating/updating firewall rules (ACL rules)
   - Creating firewall zones and traffic matching lists

2. **Use Web UI for:**
   - DHCP static IP reservations
   - Port profiles configuration
   - System settings (hostname, timezone, NTP, backups)
   - WAN configuration (detailed settings)

3. **Documentation:**
   - See [UDM_PRO_API_LIMITATIONS.md](./UDM_PRO_API_LIMITATIONS.md) for general API limitations
   - See [UDM_PRO_FIREWALL_API_LIMITATIONS.md](./UDM_PRO_FIREWALL_API_LIMITATIONS.md) for firewall-specific limitations
   - See [UDM_PRO_STATUS.md](./UDM_PRO_STATUS.md) for current configuration status

---

## Related Documentation

- [UDM_PRO_API_LIMITATIONS.md](./UDM_PRO_API_LIMITATIONS.md) - General API limitations
- [UDM_PRO_FIREWALL_API_LIMITATIONS.md](./UDM_PRO_FIREWALL_API_LIMITATIONS.md) - Firewall API limitations
- [UDM_PRO_API_FIREWALL_ENDPOINTS.md](./UDM_PRO_API_FIREWALL_ENDPOINTS.md) - Firewall API endpoints documentation
- [UDM_PRO_STATUS.md](./UDM_PRO_STATUS.md) - Configuration status

---

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