Control

The control endpoint delivers real-time signals to connected SDKs. Kill switch toggles and policy activations are pushed immediately without the SDK needing to poll.

SSE Stream

GET /v1/agents/:agent_id/control

Auth: API Key

Opens a persistent Server-Sent Events (SSE) connection. The first event delivers the current state; subsequent events are pushed when changes occur.

curl -N https://api.checkrd.io/v1/agents/01916a3e-.../control \
  -H "X-API-Key: ck_live_..." \
  -H "Accept: text/event-stream"

Event Types

init: sent immediately on connection. Carries the current state plus the active policy bundle so the SDK can sync without a separate fetch:

event: init
data: {
  "kill_switch_active": false,
  "active_policy_hash": "sha256:a1b2c3...",
  "policy_envelope": {
    "payloadType": "application/vnd.checkrd.policy-bundle+json",
    "payload": "...",
    "signatures": [{ "keyid": "...", "sig": "..." }]
  }
}

The SDK verifies the DSSE signature on policy_envelope before applying the policy.

kill_switch -- Sent when the kill switch is toggled:

event: kill_switch
data: {"active": true}

policy_updated -- Sent when a new policy version is activated:

event: policy_updated
data: {"version": 3, "hash": "sha256:d4e5f6...", "policy_envelope": {...}}

The policy_envelope is a DSSE-signed envelope. SDKs verify the Ed25519 signature before applying the new policy.

Heartbeat

A keep-alive comment is sent every 15 seconds to prevent connection timeouts:

: heartbeat

Polling Fallback

GET /v1/agents/:agent_id/control/state

Auth: API Key

For environments where SSE is not available (firewalls, proxies), poll this endpoint for the current state.

curl https://api.checkrd.io/v1/agents/01916a3e-.../control/state \
  -H "X-API-Key: ck_live_..."

Response 200 OK

{
  "kill_switch_active": false,
  "policy_envelope": {
    "payloadType": "application/vnd.checkrd.policy-bundle+json",
    "payload": "...",
    "signatures": [{ "keyid": "...", "sig": "..." }]
  }
}

The policy_envelope is signed on each request. If no active policy exists, the field is null.

Dashboard Stream

GET /v1/agents/:agent_id/control/dashboard-stream

Auth: JWT (cookie session)

A second SSE endpoint that authenticates via the dashboard's session cookie instead of an API key. Used by the dashboard UI to render the live decision feed without exposing an API key in the browser. Same event shape as /control.