Surface
HTTP & sockets
Versioned under /api/v1. Sockets share the same ingest, chat, and SOS services.
| Route | Auth | Loop | Demo vs production |
|---|---|---|---|
| POST/api/v1/telemetry Browser snapshot app/api/v1/telemetry/route.ts | public (session attached if present) | — | Writes last 200 snapshots to .data/telemetry.json. Same shape; store moves to Postgres. No card data, no GPS prompt. |
| GET/api/v1/listings/photos Listing JPEG app/api/v1/listings/photos/route.ts | public URL (UUID) | — | Reads .data/listings/{id}/{photoId}.jpg. Supabase Storage / R2 signed GET. |
| GET/api/v1/health Health app/api/v1/health/route.ts | public | — | Returns region + memory adapters. Same JSON; adapters flip to postgres/redis/amqp when env is set. |
| GET/api/v1/platform/status Go-live status app/api/v1/platform/status/route.ts | public (no secrets) | — | mode=demo, billsTodayUsd=0, checklist. blockers listed if GO_LIVE=true but gates fail. |
| GET/api/v1/metrics Prometheus app/api/v1/metrics/route.ts | public scrape | — | Counters from this process. Same text format for Grafana. |
| POST/api/v1/auth/token Issue access + refresh app/api/v1/auth/token/route.ts | signed-in session | — | HS256 with demo secret. Requires non-default JWT_SECRET. |
| POST/api/v1/auth/refresh Rotate refresh app/api/v1/auth/refresh/route.ts | refresh token | — | Reuse detection revokes the family. Same algorithm; store moves to Postgres later. |
| POST/api/v1/payments/holds Authorize hold app/api/v1/payments/holds/route.ts | signed-in | Escrow & ledger | Ledger only, processor=demo. Blocked unless go-live checklist is green + Stripe. |
| POST/api/v1/payments/payouts Instant cash-out app/api/v1/payments/payouts/route.ts | signed-in | Escrow & ledger | Journal to stripe_pending. Connect transfer after go-live. |
| POST/api/v1/uploads/sign Signed upload app/api/v1/uploads/sign/route.ts | signed-in | — | Memory PUT target. R2/S3 when UPLOAD_DRIVER=s3. |
| POST/api/v1/comms/chat Masked chat app/api/v1/comms/chat/route.ts | signed-in | — | Phones/emails redacted. Same + socket fan-out. |
| POST/api/v1/trust/webhooks Identity/verification webhook app/api/v1/trust/webhooks/route.ts | x-webhook-secret | — | Accepts status updates. Set TRUST_WEBHOOK_SECRET. |
| GET/docs This documentation app/docs/page.tsx | public | — | Live status + loops. Same site, mode badge flips. |
Auth is a Bearer access token or the existing session cookie. Dispatch and auth sit behind token buckets. Trip writes require Idempotency-Key.
driver:ping → LocationIngest (3–5s)
trip:subscribe → room trip:{id}
chat:message → MaskedChat (PII stripped)
sos:trigger → SafetyService + broadcast