API reference
v0.39 read-only Event API
Use with AI
This page lists the customer Event API for queries, streams, and evidence reads. Use the API address shown by Watch and an events:read key. Manage settings and missions in the Watch interface.
First time? Check the connection with the event viewer.
Complete event endpoints
GET /v1/events
GET /v1/events/stream
GET /v1/events/{event_id}
GET /v1/events/{event_id}/image
GET /v1/events/{event_id}/clip- /events: query and paginate history. HTTP 200 with an empty data array means no records match the query.
- /events/stream: receive new events over SSE as text/event-stream. Historical replay is off by default.
- /events/{event_id}: get one event using an ID returned by the list. An unknown event returns 404.
- /image: download the retained JPEG snapshot. If no image is available, the response is 404 event_image_not_found.
- /clip: the path exists in v0.39 but does not provide event video. An authenticated request returns 404 event_clip_not_available, and clip_url is null.
Event list parameters
| Parameter | Use |
|---|---|
| limit / after | 1–500 records per page, default 100. Use the previous next_cursor as after. |
| type / severity / state | Filter by event type, severity, and state. Each parameter can be repeated. |
| source_id / monitor_id | Filter by IDs already associated with an event. Desktop events may not have these associations. |
| nvr_id / camera_uid / camera_ip | Filter by existing camera identifiers. Filters do not populate missing metadata. |
| ai_tag | Filter by analysis tags; can be repeated. |
| acknowledged | Filter by existing acknowledgement state. The public API cannot write that state. |
| created_after / created_before | RFC 3339 time range, inclusive start and exclusive end. |
| q | Text search, 1–200 characters. |
severity accepts safe, suspicious, and critical; state accepts raised, updated, and cleared. Accepted filters do not mean every monitoring mode emits every state. See the events guide for v0.39 live-alert behavior.
Event formats and streaming steps
Connection and local documentation
GET /healthz
GET /readyz
GET /v1/openapi.json
GET /v1/docsA 200 from /healthz confirms that the service responds. /readyz is reachable over LAN but may return 503 on desktop. Verify desktop integration with /healthz and an authenticated event read rather than /readyz alone. Desktop LAN also provides /viewer/, but does not expose ReDoc.
Used only to generate the links below. This public page never asks for, sends, or stores an API key.
Enter an http:// or https:// URL without embedded credentials.
Download public OpenAPI
This schema describes the public read-only Event API. After generating a client, set its server address to the actual URL supplied by Watch. Do not send your API key to this documentation website.
Request headers
Authorization: Bearer <event-read-api-key>
X-Request-ID: req_optional_correlation