API Reference
REST API versioned at /api/v2/. All endpoints require Bearer JWT unless noted. Base URL configured via NEXT_PUBLIC_API_URL.
Authentication
/api/v2/auth/tokenLogin. Body: { username, password, mfa_code? }. Returns access_token + refresh_token.
/api/v2/auth/refreshRefresh access token. Body: { refresh_token }.
/api/v2/auth/meCurrent user: user_id, role, email.
/api/v2/auth/mfa/setupGenerate TOTP secret + QR code URI.
/api/v2/auth/mfa/verifyConfirm TOTP setup with first code.
Sites & Devices
/api/v2/sitesList sites for authenticated tenant.
/api/v2/sites/{site_id}Site detail including active device count and alert summary.
/api/v2/sites/{site_id}/devicesAll devices for a site.
/api/v2/sites/{site_id}/devicesRegister a new device manually.
Alerts
/api/v2/sites/{site_id}/alertsList alerts. Query params: status, severity, limit, offset.
/api/v2/sites/{site_id}/alerts/{id}/acknowledgeMark OPEN alert as ACKNOWLEDGED.
/api/v2/sites/{site_id}/alerts/{id}/escalateEscalate to ESCALATED status. Dispatches to all notification channels.
/api/v2/sites/{site_id}/alerts/{id}/flag-retrainFlag alert event for model retraining. Body: { reason }.
Bollard Control
/api/v2/sites/{site_id}/bollardsList bollards and current state for a site.
/api/v2/sites/{site_id}/bollards/{id}/confirmGet 2-step confirmation token (5,000ms TTL). Requires supervisor role.
/api/v2/sites/{site_id}/bollards/{id}/raiseRaise bollard. Body: { confirmation_token, reason, operator_id }. QoS 2 MQTT.
/api/v2/sites/{site_id}/bollards/{id}/lowerLower bollard. No rate limit. All authenticated users.
/api/v2/sites/{site_id}/bollards/emergency-lowerEmergency lower all bollards on site. Supervisor + MFA required.
/api/v2/sites/{site_id}/panicPanic button: raises all bollards, triggers siren, creates CRITICAL alert.
/api/v2/sites/{site_id}/panic/cancelCancel panic: lowers siren. Bollards require manual rearm.
/api/v2/sites/{site_id}/siren/{on|off}Direct ESP32 siren control.
Device Discovery
/api/v2/sites/{site_id}/discovery/scanScan subnet for ONVIF cameras, RTSP, ESP32, RMADOR edge nodes. Query: subnet.
/api/v2/sites/{site_id}/discovery/resultsReturn last scan results cached in Redis.
/api/v2/sites/{site_id}/discovery/add/{ip}Register discovered device. Query: device_type.
AI Reasoning
/api/v2/reasoning/statusCheck Ollama availability and active model.
/api/v2/reasoning/analyse-alertPlain-language analysis of an alert event. Body: { alert_id, site_id }.
/api/v2/reasoning/analyse-alert/streamStreaming version of analyse-alert (Server-Sent Events).
/api/v2/reasoning/generate-reportGenerate law-enforcement-ready incident report.
/api/v2/reasoning/explain-driftExplain model drift metrics in plain language. Body: { metrics }.
Notifications
/api/v2/notifications/statusDelivery status of all notification channels.
/api/v2/notifications/configCurrent notification configuration (Telegram, Twilio, PagerDuty, SMTP, FCM).
/api/v2/notifications/configUpdate notification config. Persisted in Redis. Header: X-Internal-Service-Token.
/api/v2/notifications/testSend test notification to all enabled channels. Body: { severity }.
Model Registry
/api/v2/modelsList all model versions with status and metrics.
/api/v2/models/{id}Model version detail: dataset hash, metrics, approval chain, lineage.
/api/v2/models/{id}/promotePromote model (SHADOW → CANARY → PRODUCTION). Requires AI Admin + Security Admin dual approval.
Healthcheck
GET /healthz→ {"status": "healthy"} · No auth required