REST and WebSocket API

REST & WebSocket API

The backend (server/app.py) exposes about 75 REST endpoints plus a WebSocket and media relays. All are local. Paths below are grouped by purpose. Path parameters use {...}.

Streaming & media

Method	Path	Purpose
WS	/ws	Live stream: frame metadata, detections, alerts, system, cameras, conn, events, metrics, ooi (see below). Also the command channel.
GET	/stream/{source_id}	MJPEG relay of the analysed feed.
GET	/thumb/{source_id}	Warm map-preview thumbnail.
GET	/snap/{source_id}	Single snapshot from a camera.
GET	/rec/{rec_id}	Play back a recording.

Cameras & sources

GET/POST /api/sources, PUT /api/sources/{id}, DELETE /api/sources/{id}, POST /api/sources/{id}/coords, POST /api/discover, POST /api/connect/{id}, POST /api/disconnect, POST /api/ptz/{id}, POST /api/inspect/{id}, GET /api/cameras/dna, POST /api/shutdown.

AI Operator & vision

Method	Path	Purpose
GET	/api/ai/status	Whether an LLM provider is configured.
POST	/api/ai/config	Set the provider + key.
POST	/api/ai/test	Test the provider.
POST	/api/ai/operate	Plan a natural-language command into a step chain.
POST	/api/ai/chat	Free-form chat / how-to answers.
POST	/api/ai/query	Structured query over live data.
POST	/api/ai/vqa/{source_id}	Vision Q&A about the frame.
POST	/api/ai/describe/{source_id}	Describe the scene (narration).
POST	/api/ai/summarize	Summarize.
POST	/api/ai/explain	Explain an alert.
POST	/api/ai/advise	Recommend an operator action.
POST	/api/ai/correlate	Correlate alerts.
POST	/api/ai/rule	Draft an alert rule from language.
POST	/api/ai/searchevents	Natural-language event search.
POST	/api/stt	Offline speech-to-text (send a 16 kHz mono WAV).
GET	/api/tts	Speak text (WAV).
POST	/api/enhance/{source_id}	Enhance a boxed region.

Roster, subjects & identity

GET /api/roster, GET /api/roster/{det_id}, POST /api/roster/{det_id}/watch, GET /api/roster/merge-candidates, POST /api/roster/merge, POST /api/roster/merge-reject, POST /api/roster/{det_id}/find, GET /api/roster/{det_id}/relationships, GET /api/roster/{det_id}/graph, GET /api/roster/{det_id}/supercut, GET /api/roster/{det_id}/cutout, GET /api/roster/{det_id}/face, GET /api/subjects, GET /api/subjects/{sid}/dossier, GET /api/subjects/{sid}/reconstruct, GET /api/reconstruct/plate/{det_id}, GET /api/relationships.

Search & matching

GET /api/search (attribute / text), POST /api/visualmatch (search by image), POST /api/platematch (search by plate), GET /api/plates, POST /api/plates.

Detection filters & spatial

GET/POST /api/detection/filters (per-class gating), GET /api/spatial/{sid} (the 3D build).

Alerts, events, threat & suggestions

GET /api/alerts, GET /api/events, POST /api/alerts/rules, POST /api/ai/rule, GET /api/suggestions, GET /api/stats.

Cases

GET/POST /api/cases, POST /api/cases/from-alert, GET /api/cases/{id}, PUT /api/cases/{id}, DELETE /api/cases/{id}, POST /api/cases/{id}/status.

Storage & recordings

GET /api/storage, POST /api/storage/cleanup, GET /api/recordings, DELETE /api/recordings/{id}.

---

WebSocket messages (/ws)

Each message is { t: <type>, d: <payload> }. Types and payload shapes are defined in web/src/lib/types.ts:

t	Payload	Meaning
frame	fps, resolution, inference ms, brightness, motion %, moving-cam flag	Per-frame metadata for the active camera.
detections	array of detections	Boxes (normalised), class, confidence, severity, attributes, intent, subtype / body type, plate, make, speed, occluded / coasting flags.
alert	alert	An incident: severity, type, summary, camera, snapshot, clip, threat id, incident marker.
system	cpu, gpu, ram, storageGB, recording mode / active	Host stats.
cameras	array of cameras	Camera list, health, coords, download progress for looped sources.
conn	connection state	connecting / online / reconnecting / offline.
event	timeline event	ts, type, label, confidence, camera, snapshot.
metrics	label:value rows	Analytics rail metrics.
ooi	object-of-interest targets	Tracked arbitrary objects: id, name, bbox, lost, confidence.

This page is a map, not an exhaustive schema. The authoritative request / response shapes are the handlers in server/app.py and the types in web/src/lib/types.ts.