Watchby Tensor Dynamics

Sentinel API v1

From your first API call to production

Events & images

Structured events, separate binary evidence

An Event is dependable machine output: stable ID, type, lifecycle, severity, confidence, Source/Monitor references, and structured attributes. The summary is for people.

Lifecycle

monitor.alert.raised → monitor.alert.updated → monitor.alert.cleared

One real-world occurrence retains stable Event identity and monotonic sequence. Consumers should not create a new Incident for each update or auto-close human work on cleared.

Event shape

{
  "id": "evt_01...",
  "type": "monitor.alert.raised",
  "state": "raised",
  "severity": "critical",
  "confidence": 0.93,
  "source_id": "src_01...",
  "monitor_id": "mon_01...",
  "created_at": "2026-08-29T23:41:08Z",
  "summary": "A person entered the loading area after hours.",
  "attributes": [],
  "evidence": {
    "image_url": "/v1/events/evt_01.../image",
    "clip_url": null,
    "content_type": "image/jpeg",
    "sha256": "..."
  }
}

This is the conceptual shape; use the current /v1/openapi.json for exact fields. Regardless of minor shape details, normal Events and webhooks use image_url rather than inline Base64.

Query and stream

GET /v1/events?limit=50
GET /v1/events/{event_id}
GET /v1/events/stream

GET /v1/analyses?monitor_id=mon_01...&limit=100
GET /v1/analyses/stream?source_id=src_01...

GET /v1/events is the persistent Event/alert database, with stable cursors for querying lifecycle Events. GET /v1/events/stream is the live SSE output for alerts and errors; signed Webhooks are the reliable cross-system output for the same alert/error lane. Ordinary inference text is not written to the Event ledger: GET /v1/analyses returns the latest result per Monitor, while /v1/analyses/stream emits every result over SSE; both require events:read.

Download the image

curl --fail http://localhost:8000/v1/events/$EVENT_ID/image \
  -H "Authorization: Bearer $SENTINEL_API_KEY" \
  --output event.jpg
  • Content-Type: image/jpeg
  • Cache-Control: private, no-cache · Vary: Authorization
  • Strong SHA-256 ETag; matching If-None-Match returns 304 with no body.
  • Uses the same events:read Bearer authorization as Event JSON.
  • Private caches must revalidate, so key revocation and scope changes take effect before cached bytes are reused.
A Source image is a no-store current frame. Event evidence has immutable bytes but revalidated authorization. Do not interchange their caching, audit, or retention semantics.

Next: receive Webhooks reliably →