API reference

The control room's HTTP API. All bodies are JSON. Errors return {"success": false, "error": "…"}. With KAAKA_ADMIN_TOKEN set, every endpoint except the public ones needs the token as the X-Kaaka-Token header, ?token=, or the dashboard cookie.

Public

Endpoint	Purpose
`GET /`, `/docs`	Landing page and this wiki.
`GET /api/health`	`{ok, version, uptime_seconds, gateway_online}`.
`GET /l/<token>`	The location-sharing page for a caller. 404 when unknown or expired.
`POST /api/location`	`{token, lat, lon, accuracy?}`. 400 malformed, 404 unknown or expired token, 429 more than one update per 10 s.

From the Kaaka number

Endpoint	Body
`POST /api/call-event`	`number` ("" if hidden), `state` (`rejected`, `allowed`, or `sms` for a help text), `sms` (`sent`, `failed`, `skipped`), `timestamp`, optional `token` and `message` (max 500).
`POST /api/telemetry`	`{report, sender}` for a forwarded "Kaaka Alert" SMS. Returns `dispatch: [{name, number, distance_km, eta_min, maps_url}]`, non-empty only the first time an open incident gets a location.
`POST /api/heartbeat`	`{timestamp, battery, charging, screeningRole, smsGranted, contactCalls}`. Returns `public_url`.
`POST /api/ack`	`{number, responder, timestamp}`.
`POST /api/resolve`	`{number, by, note, timestamp}`. 404 when there is no incident for the number.

Dashboard

Endpoint	Purpose
`GET /api/status`	Server status: last heartbeat, gateway stale flag, public URL, whether the token is on.
`GET /api/incidents`	Newest first, max 50. With `status`, `q`, `from`, `to`, `outcome`, `limit` (0–500), `offset`: a filtered page with `total` and `counts`.
`GET /api/incidents/<key>`	One incident (key = last 10 digits) with its full `timeline`.
`GET /api/incidents.csv`	CSV export with the same filters.
`GET /api/analytics?range=24h\|7d\|30d\|all`	KPIs, per-bucket contacts by channel, hours, outcomes, responders, hotspots.
`GET /api/responders`, `POST`, `PATCH /api/responders/<id>`, `DELETE`	The responder registry: `{name, number, lat, lon, available}`.
`GET /api/responders/activity`	Dispatches and ACKs per responder, newest first.

The WebSocket on port 8765 pushes the same events live (new calls, alerts, acknowledgements, resolutions, dispatches, gateway stale/back). It takes the token the same way during the handshake. The full table with every field is in the repository README.

Kaaka 1.0.0 · Edit this page · In immediate danger, call 112.