API reference

# v0.39 read-only Event API

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.](https://watch.tensordynamics.org/developers/quickstart?lang=en)

## 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](https://watch.tensordynamics.org/developers/events?lang=en)

## Connection and local documentation

```
GET /healthz
GET /readyz
GET /v1/openapi.json
GET /v1/docs
```

A 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.

Your Watch node URL

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.

Connection check ↗Swagger UI ↗OpenAPI JSON ↗

## 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.

[Download OpenAPI JSON](https://watch.tensordynamics.org/api/v1/openapi.json)

## Request headers

```
Authorization: Bearer <event-read-api-key>
X-Request-ID: req_optional_correlation
```

The public Event API does not change settings, create events, acknowledge events, or perform other writes. Configure desktop event delivery in Watch; it is not a public API write operation.

---
Source: https://watch.tensordynamics.org/developers/api-reference
More Watch guides: https://watch.tensordynamics.org/llms.txt