74 lines
2.7 KiB
Markdown
74 lines
2.7 KiB
Markdown
# UniFi Local Network API Port Troubleshooting
|
|
|
|
Use this reference when troubleshooting customer UniFi switch-port/client issues where Site Manager data is too shallow.
|
|
|
|
## Key distinction
|
|
|
|
- **Site Manager API** (`https://api.ui.com/v1` / `/ea` with `X-API-KEY`) gives high-level site/host/device inventory and WAN issue summaries.
|
|
- **Local Network API** is required for clients, events, detailed switch port stats, CRC/drop counters, PoE state/actions, and port power cycling.
|
|
|
|
Create local key per console:
|
|
|
|
```text
|
|
UniFi Network → Integrations → Network API → Create API Key
|
|
```
|
|
|
|
Store per-site keys securely and label them by customer/console.
|
|
|
|
## Liberty Tire identifiers found Jul 14, 2026
|
|
|
|
```text
|
|
Host: Liberty-UDM-Pro
|
|
Host ID: D8B3702867A1000000000770A2860000000007CBEC34000000006437A55B:1003909054
|
|
Site ID: 66cfc43699ec0d7200188ed3
|
|
WAN/IP shown by Site Manager: 108.175.202.88
|
|
Gateway MAC: d8:b3:70:28:67:a1
|
|
Switch: USW-24-PoE
|
|
Switch MAC: E4:38:83:94:66:E3
|
|
Switch IP: 10.1.0.5
|
|
Phone issue: Yealink W70 cordless base on switch port 1 periodically develops static/packet-loss symptoms; user's manual fix is power-cycle port 1.
|
|
```
|
|
|
|
## GLC identifiers found Jul 14, 2026
|
|
|
|
```text
|
|
Host: GLC UDM Pro
|
|
Host ID: AC8BA96EDB4F0000000007153E2D00000000076AA09A0000000063974676:10670668
|
|
Site ID: 66770d7ed634742ade16b848
|
|
WAN/IP shown by Site Manager: 75.62.181.131
|
|
```
|
|
|
|
## Troubleshooting workflow
|
|
|
|
1. **Read-only first**
|
|
- Identify switch and target port.
|
|
- Identify client MAC/IP/hostname (Yealink W70 base).
|
|
- Pull recent client history and switch port metrics.
|
|
- Check port link flaps, speed/duplex, PoE draw/state, RX/TX drops, CRC/FCS errors.
|
|
- Correlate with report time.
|
|
2. **Check WAN separately**
|
|
- Site Manager may show high-latency WAN events; do not confuse those with port-level packet loss unless phone RTP paths confirm WAN jitter.
|
|
3. **Only after approval**
|
|
- Execute PoE/port cycle on the specific port.
|
|
- Verify client returns and counters reset/stabilize.
|
|
4. **Long-term watchdog**
|
|
- No-agent script checks port/client health periodically.
|
|
- Alert on flaps/errors/phone offline.
|
|
- Approval-gated action can power-cycle the known port.
|
|
|
|
## Port action endpoint shape
|
|
|
|
UniFi docs show:
|
|
|
|
```text
|
|
POST /v1/sites/{siteId}/devices/{deviceId}/interfaces/ports/{portIdx}/actions
|
|
```
|
|
|
|
The exact action name/body depends on Network version; inspect the local Network app's Integrations docs for that console before writing automation.
|
|
|
|
## Guardrails
|
|
|
|
- Do not cycle ports without explicit user approval.
|
|
- Confirm port numbering in API is the same as UI label before action; some APIs use zero-based `portIdx`, while UI labels are one-based.
|
|
- Record before/after counters for any power cycle action.
|