Policies

Version and activate YAML policies for agent behavior control.

Policies

Policies are YAML-defined rule sets that control what an agent is allowed to do. Each agent has a version history of policies, with one active version at a time.

The Policy Object

json

{
  "id": "01916c00-aaaa-bbbb-cccc-dddddddddddd",
  "agent_id": "01916a3e-7b2c-4d1f-8e3a-abc123def456",
  "version": 3,
  "yaml_content": "agent: sales-agent\ndefault: deny\nrules:\n  ...",
  "hash": "sha256:a1b2c3d4...",
  "description": "Added rate limiting for Stripe endpoints",
  "is_active": true,
  "created_by": "01916a3e-0000-0000-0000-000000000001",
  "created_at": "2026-04-11T10:00:00Z"
}

Field	Type	Description
`version`	integer	Auto-incrementing version number.
`yaml_content`	string	The full YAML policy definition.
`hash`	string	SHA-256 hash of the YAML content.
`is_active`	boolean	Whether this version is currently enforced.

Create a Policy Version

POST /v1/agents/:agent_id/policies

Auth: JWT (admin+)

Parameter	Type	Required	Description
`yaml_content`	string	Yes	Valid YAML policy definition (max 256 KB).
`description`	string	No	Description of what changed.

The YAML is validated against the policy schema: agent name is required, rules must have unique names, URL patterns are limited to 1024 characters, and a maximum of 200 rules.

bash

curl -X POST https://api.checkrd.io/v1/agents/01916a3e-.../policies \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "yaml_content": "agent: sales-agent\ndefault: deny\nrules:\n  - name: allow-salesforce\n    allow:\n      method: [GET, POST]\n      url: \"api.salesforce.com/*\"",
    "description": "Initial policy"
  }'

Response 201 Created -- Returns the new policy version.

List Policy Versions

GET /v1/agents/:agent_id/policies

Auth: JWT (viewer+)

bash

curl https://api.checkrd.io/v1/agents/01916a3e-.../policies \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

Response 200 OK -- Paginated list ordered by created_at descending (newest first).

Get Active Policy

GET /v1/agents/:agent_id/policies/active

Auth: JWT (viewer+)

bash

curl https://api.checkrd.io/v1/agents/01916a3e-.../policies/active \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

Response 200 OK -- Returns the currently active policy version, or 404 if no policy has been activated.

Activate a Policy Version

POST /v1/agents/:agent_id/policies/:version/activate

Auth: JWT (admin+)

bash

curl -X POST https://api.checkrd.io/v1/agents/01916a3e-.../policies/3/activate \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

Response 200 OK -- Returns the activated policy version.

The activated policy is immediately pushed to connected SDKs via SSE as a DSSE-signed envelope. SDKs verify the signature before applying the new policy.

API Keys Telemetry