Reference

API Reference

A local REST API plus a WebSocket stream.

Authentication

Overseer runs as a local, single-operator service and ships with no authentication by default, it binds to localhost and never calls out to the internet. For multi-user or networked deployments, front the API with a reverse proxy that enforces auth (bearer token, mTLS or your SSO). All examples below assume the local base URL.

Base URL

http://127.0.0.1:8787

Endpoints

Sources & Streams

Method	Path	Description
GET	`/api/sources`	List registered camera / video sources.
POST	`/api/sources` body: `{ "name": "North Gate", "url": "rtsp://…" }`	Register a source.
POST	`/api/discover` body: `{ "timeout": 3.0 }`	Discover ONVIF cameras on the LAN.
GET	`/stream/{source_id}`	MJPEG stream for a source (live feed).
GET	`/snap/{source_id}`	Latest JPEG snapshot for a source.

Detection & Filters

Method	Path	Description
GET	`/api/detection/filters`	Current per-class DETECTION toggles (person / vehicle / animal / weapon / motion / track).
POST	`/api/detection/filters` body: `{ "vehicle": false, "motion": false }`	Update toggles; persisted and applied live.

Spatial & Reconstruction

Method	Path	Description
GET	`/api/spatial/{source_id}?grid=320`	Lift a frame into a 3D scene: depth grid, point cloud entities, FOV, background layer.
GET	`/api/subjects/{id}/reconstruct`	Super-resolved reconstruction of a subject from its sightings.
GET	`/api/reconstruct/plate/{det_id}`	Reconstruct a clearer licence plate for a detection.

Identity & Roster

Method	Path	Description
GET	`/api/roster`	List roster entries (tracked subjects).
GET	`/api/roster/{id}`	A single subject with attributes, trail and flags.
POST	`/api/roster/{id}/watch` body: `{ "on": true }`	Flag / unflag a subject as watched (BOLO).
GET	`/api/subjects/{id}/dossier`	Long-term dossier: sightings, histogram, biometrics.
GET	`/api/roster/{id}/graph`	Ego relationship graph (who-was-with-whom).

Analytics & Alerts

Method	Path	Description
GET	`/api/suggestions`	Smart alert-coverage and camera-health suggestions.
POST	`/api/alerts/rules` body: `{ "name": "Loitering", "event_type": "LOITERING", "source_id": 1, "severity": "warning" }`	Add an alert rule.
GET	`/api/cameras/dna`	Per-camera learned DNA / reputation signals.

WebSocket

Method	Path	Description
WS	`/ws`	Live stream: frame meta, detections, metrics, alerts, events. Send { t: 'command', d: 'connect:North Gate' } to drive it.

Errors

Endpoints return standard HTTP status codes; the body carries an { "error": "..." } message on failure.

Code	Name	When
`200`	OK	Request succeeded.
`400`	Bad Request	Malformed body or parameters.
`404`	Not Found	Unknown source, subject or detection id.
`409`	Conflict	Concurrent modification of the same resource.
`503`	Backend Down	The analysis backend is not ready (starting, no source, model unavailable).

Examples

Request · update detection filters

shell

curl -X POST http://127.0.0.1:8787/api/detection/filters \
  -H "content-type: application/json" \
  -d '{"vehicle": false, "motion": false}'

Response

json

{
  "person": true,
  "vehicle": false,
  "animal": true,
  "weapon": true,
  "motion": false,
  "track": true
}

WebSocket · drive the live stream

javascript

const ws = new WebSocket("ws://127.0.0.1:8787/ws");
ws.onmessage = (e) => {
  const msg = JSON.parse(e.data);   // { t: "detections" | "metrics" | "alert" | ... , d: ... }
  if (msg.t === "detections") render(msg.d);
};
ws.onopen = () => ws.send(JSON.stringify({ t: "command", d: "connect:North Gate" }));