Internal API (
/api/v1), dashboard JWT (Authorization: Bearer ...). kurnl staff only:
provider logins get 403, because the response names kurnl’s switches, ports and DHCP
addresses. An admin may pass service_provider_id to narrow the list to one provider;
without it, every provider’s ports are returned.Endpoint
Query parameters
Returns one row per switch port with an active subscription for the provider — only
subscriptions whose location has both a switch host and an interface produce a row. Link
status is read live over SSH, the learned MAC comes from the switch SNMP FDB, the IP from
the DHCP lease table, and the manufacturer from the MAC OUI.
Response — 200 OK
interface is the port’s name as its switch’s CLI spells it — ethernet1/12 on a
Waystream, GigabitEthernet 0/12 or TenGigabitEthernet 0/3 on an FS.com switch. It
may contain a space; treat it as an opaque string and URL-encode it when you pass it on.
match_status compares the learned MAC against the subscriber’s registered MAC:
match | mismatch | unregistered (device seen, no MAC registered) | no_device.
has_active_device is true when the link is up and a device is learned on the port.
subscriber_name comes from the contract contact (null when absent);
room/unit are parsed from canonical 4-segment location identifiers (null for legacy
identifiers); expected_*_mbps derive from the plan version’s wholesale product and are
null when unavailable. Enrichment is best-effort — fields degrade to null when
SSH/SNMP/DHCP data is unavailable.
Sandbox callers get a reduced per-port shape: link state comes from the sandbox
model,
seen_mac/seen_ip/manufacturer are always null, and the row carries
device_active and matches_expected instead of ip_address, hostname,
seen_mac_count, match_status, and has_active_device (sandbox ports never have
real devices, so no FDB/DHCP probing happens).