Endpoint Reference

FreeSDN exposes a typed REST API under /api/v1. This page gives you the module-level summary: who owns what prefix and which key operations live there. For the exhaustive, always-current route list, use the live OpenAPI spec served by the running instance.

---

The canonical source: live OpenAPI

When ENABLE_DOCS=true is set and the environment is not production, two interactive UIs are served by the running instance:

UI	Path
Swagger UI	/api/v1/docs
ReDoc	/api/v1/redoc
OpenAPI 3.1 JSON	/api/v1/openapi.json

Start the development stack and open http://localhost:8000/api/v1/docs. Every endpoint, request schema, response schema, and permission requirement is documented there in machine-readable form.

Caution

Both UIs are always disabled when ENVIRONMENT=production, regardless of ENABLE_DOCS. The environment guard is a hard AND in code - setting ENABLE_DOCS=true cannot re-enable them in production. Do not change ENVIRONMENT to a non-production value on an internet-facing deployment just to expose the spec.

The OpenAPI document is authoritative. If anything on this page disagrees with the live spec, trust the spec.

---

Reading the tables

• Prefix - the URL prefix relative to /api/v1/. All routes are under /api/v1/.
• Key operations - representative routes, not a complete list. Consult the OpenAPI spec for the full surface.
• Min role - the lowest role tier that can call any route in that group. Individual routes may require higher roles or specific permissions.

---

Platform core

These routes are part of the base API and are independent of any specific module.

Health and root (no auth required)

Method	Path	Purpose
GET	/health	Container orchestration probe - {"status":"healthy"|"degraded"}
GET	/	Root info: {app, docs, api}
GET	/api/v1/health	Aggregated subsystem health
GET	/api/v1/health/live	Liveness probe
GET	/api/v1/health/ready	Readiness probe (gated by READINESS_STRICT_DEPS)
GET	/api/v1/health/db	Database connectivity

Identity and session management

Prefix	Key operations	Min role
/auth/	Login, MFA challenge/complete, refresh, logout, logout-all, password change, session list/revoke, TOTP setup/enable/disable	Public (login flows); authenticated (session ops)
/auth/sso/	OIDC authorize/callback, LDAP authenticate, provider CRUD	Public (login flows); org_admin (provider management)
/oauth2/	OAuth2 app registration, authorization-code flow, token exchange, revoke	Authenticated
/api-keys/	List own keys, create (secret returned once), revoke	Authenticated (own keys only)

Note

POST /auth/token (OAuth2 password grant) refuses accounts that have MFA enabled and returns 400. Use POST /auth/login + POST /auth/login/mfa for those accounts instead.

Caution

SAML SSO (/auth/sso/saml/*) is present in routing but returns 501. Use OIDC or LDAP.

Tenancy administration

Prefix	Key operations	Min role
/users/	List, create, get, update, soft-delete. Role assignment enforces strict-lower-than hierarchy	admin
/organizations/	CRUD, dashboard, per-user site-access grant/bulk/revoke	admin / org_admin
/sites/	List (with device counts), create, get, update, soft-delete	org_admin (write); authenticated (read)
/roles/	Stored role row CRUD	admin
/credentials/	Fernet-encrypted device credential CRUD + connectivity test	settings:read / settings:write

Note

Role permissions are resolved from a static DEFAULT_ROLE_PERMISSIONS map keyed on user.role, not from the stored Role rows managed by /roles/. The /roles/ endpoints store display metadata; they do not affect authorization decisions in this release.

Devices, controllers, and discovery

Prefix	Key operations	Min role
/devices/	Managed device registry - list, get, update state, bulk ops	viewer (read); operator (write)
/controllers/	Per-vendor controller CRUD, multi-controller test/sync, sites under a controller	admin (write); viewer (read)
/discovery/	Start async 4-phase scan, progress, results, cancel, adopt, bulk-adopt, fingerprint, agent-dispatch	discovery:run / discovery:write
/ztp/	Zero-touch provisioning - templates, device queue, apply	operator

Active scan concurrency is capped per organisation. Exceeding it returns 429. Scan targets are validated and bounded server-side - unbounded CIDR ranges are rejected.

---

Module routes

Each of the 10 loaded modules mounts at /api/v1/{module-id}/. Browse the live OpenAPI docs at /api/v1/docs for the full surface on your running instance.

Module summary

Module	Prefix	Status	Key capabilities
Network Management	/network/	Available	VLAN alignment, multi-controller distribution; see also /switches/, /access-points/, /poe/
Video Surveillance	/cameras/	Available	Camera CRUD, live stream, snapshots, PTZ, recordings, NVR import, LPR, forensic export, legal hold
VoIP & Telephony	/voip/	Available	Phone fleet CRUD/provisioning/SIP-push, PBX extensions/trunks/ring-groups/queues/IVR/CDR
Firewall	/firewall/	Available	Rule CRUD + reorder, NAT, IDS/IPS, VPN, gateway orchestration (canonical VLANs, drift detection)
Access Control	/access_control/	BETA, off by default	Door/credential/cardholder/schedule CRUD
Configuration Backup	/backups/	Available	Portable config snapshot (.fsdn archive), schedule, restore, export
AI Assistant	/ai/	BETA	Multi-provider LLM, 11 tools, 3-layer governance, classify/extract/summarize
Observability	/collector/	Available	SNMP-trap, Syslog, NetFlow ingestion to TimescaleDB
Compute / Hypervisor	/hypervisor/	Available	Proxmox VE: cluster, nodes, VMs, LXC, snapshots, backups, storage, SDN
Storage	No HTTP routes	Available	Fabric participant only: TrueNAS ZFS health rollup, staged blob writes

Caution

Access Control is BETA and off by default. Door lock/unlock endpoints return 501 - no door adapter ships for any vendor yet. Do not build production workflows around door control.

AI Assistant is BETA.

Network Management sub-routes

Network Management shares its function with several dedicated core-platform prefixes. Together they cover the full switch, AP, and VLAN surface:

Prefix	Key operations
/switches/	Port enable/disable/PoE/cycle, VLAN port matrix (interactive U/T/empty), LAG CRUD, port mirroring, config history + diff viewer
/access-points/	AP list/get/update, WiFi/SSID config, RF health, rogue AP detection, radio settings
/network/	VLAN CRUD, VLAN alignment across controllers, multi-controller VLAN distribution
/poe/	PoE budget, per-port power control
/topology/	Network graph (React Flow rendered on the frontend)
/dpi/	Deep packet inspection / traffic analytics
/radius/	802.1X / RADIUS server management
/roaming/	Client roaming history

VPN (shared with Firewall module)

Prefix	Key operations
/vpn/	IPsec / OpenVPN / WireGuard CRUD, peer management, stats
/vpn/ (orchestration)	Multi-controller VPN orchestration

---

Vendor adapter gateway surface

The vendor adapter surface is the largest segment of the API. These endpoints handle staged reads and writes against real hardware. They use controller-and-site-scoped paths:

/api/v1/gateway-{area}/{controller_id}/sites/{site_id}/...

Danger

OMADA_READ_ONLY and ADAPTER_READ_ONLY both default to true. A write that returns 201 Created has only been staged to the database - it has not touched any live device. Pushing the change to hardware requires ADAPTER_READ_ONLY=false in the environment and {"force": true} in the apply call body. Missing either gate leaves the change staged indefinitely.

Adapter surface by vendor

Vendor	Prefixes	~Domain areas
Omada	/gateway-vpn/, /gateway-firewall/, /gateway-wifi/, /gateway-switch-advanced/, /gateway-firmware/, /gateway-routing/, /gateway-diagnostics/, /gateway-hotspot/, /gateway-raw/, /gateway-bulk/, /gateway-system/, /gateway-profiles/, /gateway-insights/, /gateway-openapi/	14
OPNsense	/gateway-opnsense-{area}/	firewall, nat, dhcp, dns, vpn, routing, services, ids, shaper, system, diagnostics, interfaces, cron (13)
pfSense	/gateway-pfsense-{area}/	firewall, nat, dhcp, dns, vpn, routing, services, system, diagnostics, interfaces (10)
MikroTik	Mounted per area	firewall, interfaces, ip, dhcp, dns, vpn, routing, queues, ppp, hotspot, capsman, security, system (13)
OpenWrt	Mounted per area	base, firewall, dhcp (3)
Proxmox	/gateway-proxmox-{area}/	vm, container, snapshot, storage, backup, cluster, ha, node, replication, sdn, ceph, firewall (12)
UniFi	adapter_unifi_* (gateway-style) + unifi_* at /unifi/	Two parallel families - clients, devices, wlans, networks, firewall, system

Note

The UniFi adapter has two coexisting route families (unifi_* and adapter_unifi_*) routed by distinct prefix. This is a known layering issue in the codebase, not a configuration option.

Staged-write URL pattern

Vendor write endpoints use one of two path shapes depending on whether the vendor uses FreeSDN sub-sites. Omada (the only vendor that exposes sub-site scoping) includes a sites/{site_id} segment. All other vendors (OPNsense, pfSense, MikroTik, OpenWrt, Proxmox, UniFi) are controller-scoped and omit it.

Omada (/gateway-{area}/ prefixes backed by the Omada controller):

Method	Path pattern	Purpose
POST	/gateway-{area}/{controller_id}/sites/{site_id}/changes/{feature}?operation=create|update|delete	Stage a change (returns 201)
GET	/gateway-{area}/{controller_id}/sites/{site_id}/changes	List pending changes

All other vendors (OPNsense, pfSense, MikroTik, OpenWrt, Proxmox, UniFi - no sub-site segment):

Method	Path pattern	Purpose
POST	/gateway-{area}/{controller_id}/changes/{feature}?operation=create|update|delete	Stage a change (returns 201)
GET	/gateway-{area}/{controller_id}/changes	List pending changes

Shared apply/discard surface (all vendors):

Method	Path pattern	Purpose
POST	/gateway-vpn/changes/{change_id}/apply	Apply (push to device) - requires {"force": true}
POST	/gateway-vpn/changes/{change_id}/discard	Discard without applying
GET	/gateway-vpn/changes/by-gateway/{gateway_id}?vendor=<mikrotik|pfsense|opnsense|openwrt|unifi>	Fanout query across vendors for a gateway (vendor is required; unknown value → 400)

The apply endpoint resolves the required permission from change.feature at runtime (for example, vpn.* features require vpn:write; proxmox.* require hypervisor:write).

Catastrophic operations (VM destroy, firmware flash, factory reset, config restore, and equivalents for each vendor) require at least site_admin role at both stage time and apply time. This closes the queue-poisoning window where a lower-tier operator stages a destructive change for a higher-tier operator to inadvertently apply.

---

Automation and integration routes

Prefix	Key operations
/automation/	Automation rules, schedules, enable/disable, run history
/fabric/	GET /fabric/catalog (tier-tagged operations + events + AI-tool projections); Connection CRUD; inbound /fabric/ingest (org API key auth); Negotiator status
/webhooks/	Outbound webhook subscriptions, delivery history, DLQ replay
/webhooks/templates	Reusable webhook templates
/events/	Event bus read and replay
/actions/	Ad-hoc action dispatch
/notifications/	Notification channel CRUD (email, Slack, PagerDuty, webhook, etc.)

---

Observability and enterprise routes

Prefix	Key operations
/analytics/	Traffic and usage analytics, aggregate queries
/enterprise/	Enterprise config management, config versions
/sla/	SLA policy CRUD, compliance reports, breach history
/alert-rules/	Alert rule CRUD, enable/disable, test
/correlation/	Event correlation rule management
/audit/	Audit log query (immutable, HMAC-chained)
/security/	Security event query
/logs/	Log query (TimescaleDB-backed)
/firmware/	Firmware lifecycle - check, schedule, apply, rollback

---

Agent, plugin, and marketplace routes

Prefix	Key operations
/agents/	Agent registration, heartbeat, approval, task dispatch, scan dispatch, fleet overview, download/release upload, schedules
/plugins/	Plugin install (ZIP, super_admin only), list, enable/disable per org, uninstall
/marketplace/plugins/	Browse Ed25519-signed catalog, install (signature + SHA-256 verified), ratings
/integrations/	Third-party integration config

Marketplace catalog syncs require a valid Ed25519 detached signature when a publisher key is pinned (MARKETPLACE_PUBLISHER_PUBLIC_KEY); with no key pinned, syncs are refused unless MARKETPLACE_ALLOW_UNSIGNED=1 is explicitly set (dev/trusted-registry opt-out). Direct-URL plugin installs (outside the marketplace) are disabled by default (PLUGIN_ENABLE_DIRECT_URL_INSTALLS=false).

---

WebSocket

Method	Path	Purpose
WS	/api/v1/ws	Real-time event stream - device state, alerts, job progress, scan results
WS	/api/v1/agents/ws/{agent_id}	Agent command channel - heartbeat, task dispatch, scan results (agent-to-server only)
WS	/<module-prefix>/{camera_id}/live/mse	MSE live-stream for a camera; registered by the Video Surveillance module loader at startup. Covered in the Video Surveillance module docs.
GET	/api/v1/ws/stats	Active connection count (plain HTTP, not a WebSocket upgrade)

Auth via auth-frame (preferred), freesdn_access cookie, or ?token= query param (deprecated). Per-user cap: 25 connections, 200 subscriptions each. Global cap: 5,000 connections.

---

Prometheus metrics

GET /metrics - only served when ENABLE_METRICS=true. Requires Authorization: Bearer <METRICS_AUTH_TOKEN> in production. The path is internal-only in the default Docker Compose configuration (no host port published).

Caution

/metrics is fail-closed in production without METRICS_AUTH_TOKEN. When no token is configured in a non-development environment the route is not registered at all (FastAPI returns 404). When a token is configured but the request omits or sends a wrong Authorization: Bearer header, the endpoint returns 401. Do not expect a 403; the code never produces one for this endpoint.

---

Security and honesty caveats

Caution

The following capabilities exist in the route surface but are not fully implemented in this release:

• SAML SSO (/auth/sso/saml/*) - returns 501. Use OIDC or LDAP.
• Access Control door operations - return 501. No door adapter ships for any vendor.
• MFA - returns 501 if the pyotp package is absent from the runtime image.
• Role permissions - the /roles/ endpoints manage stored Role rows, but the authorization layer uses a static DEFAULT_ROLE_PERMISSIONS map keyed on user.role. Stored rows and per-user overrides are not yet merged into the authorization decision.

Caution

Multi-tenancy is enforced in application code at the service layer. There is no PostgreSQL Row-Level Security. Routes rely on consistent service-layer org scoping.

Caution

FreeSDN has no SOC 2 certification or other compliance certification. This release includes automated tests and internal review, but no third-party security audit or certification is claimed.

---

Next steps

• API Overview - base URL, versioning, authentication, and request conventions
• Authentication - JWT flow, MFA, cookies, and API keys
• Using the API - worked examples including the staged-write flow
• Errors and Status Codes - error shapes and how to handle each code
• Adapters - per-vendor capability matrix and maturity tiers
• Roles and Permissions - full permission strings by role