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 "Authorization: Bearer ck_live_..." \
  -H "Accept: text/event-stream"

Event Types

init -- Sent immediately on connection:

event: init
data: {"kill_switch_active": false, "active_policy_hash": "sha256:a1b2c3..."}

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 "Authorization: Bearer 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.