DOCUMENTATION

Sentinel Watch -- API reference

Audit = evaluate once. Watch = evaluate repeatedly and emit a signal only when something meaningful changed.

Search • Intelligence API • TrustOps • Reliability • Pricing • Claim/Manage

More: Methodology • About • Changelog • Status • Rankings • Gateway • Compare • Trust Index • Badges • Profiles • Security • MCP API • API Docs • Shortlists • Digests • RSS • RSS XML • Discovery sources • Scan my server • Submit repo • GitHub Action • Privacy

Lifecycle

target -> evaluator -> snapshot -> comparison -> signal -> policy -> notification/history. Each scheduled or manual run produces one snapshot; every new snapshot is compared against the watch's prior snapshot; a meaningful difference produces one or more signals; each signal is evaluated against the watch's policy (minimum severity, email/webhook delivery) before anything is delivered.

Pinned evaluators, versioned methodology

Each evaluator type runs against a pinned implementation build, and every snapshot records that build's evaluatorVersion. Where a scored methodology is involved (Agent Readiness), the methodology version used is recorded separately from the evaluator build -- evaluatorVersion and methodologyVersion are independent identifiers, and neither is guaranteed to change when the other does. See the Agent Readiness evaluator page for exactly where each field lives.

Targets, cadence, evaluators

A watch target is currently always a domain. cadence accepts exactly two values: daily or weekly -- there is no custom-interval or hourly option today. evaluator accepts exactly two values: api_exposure or agent_readiness (see their dedicated pages).

Status model

A watch is active immediately on creation, and can be moved to paused and back via PATCH. Deleting a watch archives it (soft delete) rather than removing the row -- an archived watch stops running and disappears from GET /v1/watch/{watch_id} (404) and from the list endpoint, but its run/snapshot/signal history is not destroyed.

Manual runs and idempotency

POST /v1/watch/{watch_id}/run accepts an optional Idempotency-Key header. Reusing the same key against the same watch returns the existing run (200) instead of enqueuing a duplicate one (which returns 202).

Retention, plan limits, notifications

How many watches an organization may create, run concurrency, and notification delivery (email/webhook) are entitlement- and plan-governed and enforced server-side; requests over an organization's limit fail with a 403 from the entitlement check, distinct from a scope-related 403. Ask Sentinel Signal for your organization's current limits.

Routes

All require an Intelligence API key with watch:read or watch:write (see Authentication). Full request/response fields are in the OpenAPI schema.

POST /v1/watch -- create a watch -- write scope -- 201
GET /v1/watch -- list watches -- read scope
GET /v1/watch/{watch_id} -- fetch one watch -- read scope
PATCH /v1/watch/{watch_id} -- update cadence/status/policy -- write scope
DELETE /v1/watch/{watch_id} -- archive a watch (soft delete) -- write scope -- 204
POST /v1/watch/{watch_id}/run -- trigger a manual run -- write scope -- 202 if a new run was created, 200 if the Idempotency-Key matched an existing one
GET /v1/watch/{watch_id}/runs -- list run history -- read scope
GET /v1/watch/{watch_id}/snapshots -- list evaluator snapshots -- read scope
GET /v1/watch/{watch_id}/signals -- list detected change signals -- read scope
POST /v1/watch/policies -- create an alert policy -- write scope -- 201
GET /v1/watch/policies -- list alert policies -- read scope
GET /v1/watch/policies/{policy_id} -- fetch one policy -- read scope
PATCH /v1/watch/policies/{policy_id} -- update a policy -- write scope
DELETE /v1/watch/policies/{policy_id} -- delete a policy -- write scope -- 204

Create + run example

curl -X POST https://verify.sentinelsignal.io/v1/watch \
  -H "Authorization: Bearer $WATCH_KEY" -H "Content-Type: application/json" \
  -d '{
  "target": {
    "type": "domain",
    "value": "example.com"
  },
  "evaluator": "agent_readiness",
  "cadence": "daily"
}'

curl -X POST https://verify.sentinelsignal.io/v1/watch/<watch_id>/run \
  -H "Authorization: Bearer $WATCH_KEY" -H "Idempotency-Key: run-2026-09-06-01"

Schema version

Every Watch response envelope carries "schemaVersion": "sentinel.watch.v1" -- a separate version namespace from the audits' "1.0" and the readiness audit's methodologyVersion.