API reference
Base path /api/v1 (Phase 2+). OpenAPI renders at /docs once the backend runs.
Phase 0
Section titled “Phase 0”GET /health— liveness + Postgres reachability.200 {"status":"ok","db":"ok"}when the DB answers;503 {"status":"degraded","db":"error"}when it does not.
Device-facing (API key) — Phase 2
Section titled “Device-facing (API key) — Phase 2”POST /devices/register, POST /telemetry, GET /commands?device_id=,
POST /commands/{id}/result, GET /config/{device_id}, GET /ota/latest.
Demo readout — Phase 3 (throwaway, unauthenticated, mounted at root)
Section titled “Demo readout — Phase 3 (throwaway, unauthenticated, mounted at root)”GET /demo (HTML page), GET /demo/state?device_id= (latest telemetry), POST /demo/command
(operator command-enqueue stand-in). Replaced by the real operator API in Phase 5.
Operator-facing (JWT bearer) — Phase 5
Section titled “Operator-facing (JWT bearer) — Phase 5”All under /api/v1, JWT bearer auth, org-scoped (404 cross-org, 403 on insufficient role).
- Auth:
POST /auth/signup,/auth/login,/auth/refresh,/auth/logout,/auth/verify-email,/auth/password-reset/request,/auth/password-reset/confirm,/auth/mfa/enroll,/auth/mfa/verify,GET /auth/me. - Orgs/members:
GET /orgs,GET/POST /orgs/{id}/members,PATCH/DELETE /orgs/{id}/members/{uid}. - Assets:
POST/GET /buildings,GET/PATCH/DELETE /buildings/{id};GET /devices?org_id=,GET /devices/{id},POST /devices/{id}/link. - Alerts:
POST/GET /alert-rules,DELETE /alert-rules/{id},GET /alerts?org_id=,POST /alerts/{id}/acknowledge. - Reports:
GET /reports/telemetry.csv?device_id=,GET /reports/alerts.csv?org_id=,GET /reports/compliance.pdf?org_id=.
Roles: viewer < operator < org_admin; super_admin is cross-org.
Public — Phase 7 (marketing)
Section titled “Public — Phase 7 (marketing)”POST /api/v1/leads— public lead capture from the marketing site contact form (stores the lead- emails sales).
GET /api/v1/leadslists leads (super-admin only).
- emails sales).
Billing (JWT) — Phase 8
Section titled “Billing (JWT) — Phase 8”GET /api/v1/billing/plans, GET /api/v1/billing/subscription?org_id= (entitlement),
POST /api/v1/billing/subscribe (org_admin), GET /api/v1/billing/invoices?org_id= (org_admin),
POST /api/v1/billing/webhook (Stripe events — reconciles subscription/invoice state + dunning).
Plan entitlements (per-plan building cap) are enforced in the data layer.
Integrations (JWT) — Phase 9
Section titled “Integrations (JWT) — Phase 9”- SIM fleet:
POST /api/v1/integrations/sims/sync?org_id=,GET /integrations/sims?org_id=,POST /integrations/sims/{id}/suspend|activate(failover). - Weather-reset:
POST /integrations/weather/refresh?org_id=→ writes a weather-reset setpoint into located buildings’ device config. - Phone escalation:
POST /integrations/alerts/{id}/escalate(bilingual Telnyx agent). - Outbound webhooks:
POST/GET /integrations/webhooks,DELETE /integrations/webhooks/{id},GET /integrations/webhooks/{id}/deliveries. Alerts fan out as signedalert.createdevents.
Scale / OTA — Phase 11
Section titled “Scale / OTA — Phase 11”- Staged OTA (super-admin):
POST/GET /api/v1/ota/versions,POST/GET /api/v1/ota/rollouts,PATCH /api/v1/ota/rollouts/{id}(advancestage_percent/ pause). Devices pull their target from the device-facingGET /api/v1/ota/latest(served per the active staged rollout). - Telemetry pipeline: hourly downsampling →
telemetry_aggregates+ raw retention run on the worker (services/aggregation.py). Partitioning/SLOs indocs/scaling.md;docs/loadtest-report.mdis the load-test SLO report.