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

{
  "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"
}

Create a Policy Version

POST /v1/agents/:agent_id/policies

Auth: JWT (admin+)

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.

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 200 OK -- Returns the new policy version.

List Policy Versions

GET /v1/agents/:agent_id/policies

Auth: JWT (viewer+)

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+)

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+)

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.

Get a Specific Version

GET /v1/agents/:agent_id/policies/:version

Auth: JWT (viewer+)

Returns the full policy at the given version, including its YAML, status, and signature metadata. Useful for diffing against the active version or inspecting historical drafts.

Update a Draft

PATCH /v1/agents/:agent_id/policies/:version

Auth: JWT (admin+)

Updates the YAML or description of a draft policy version. Only draft versions accept updates; published versions are immutable.

Response 200 OK: returns the updated draft.

Diff Two Versions

POST /v1/agents/:agent_id/policies/diff

Auth: JWT (viewer+)

Compares two policy versions and returns a Terraform-plan-style diff describing rules added, removed, or modified.

Response 200 OK: structured diff. Use this to preview the effect of activating a new version before flipping the switch.

Test a Policy

POST /v1/agents/:agent_id/policies/test

Auth: JWT (admin+)

Runs the embedded tests: block against a draft or published policy YAML, without activating. Each test case has an expected outcome (allow / deny / rate_limit) and the engine returns pass/fail per case.

Response 200 OK: array of test results.

Replay Production Traffic

POST /v1/agents/:agent_id/policies/replay

Auth: JWT (admin+)

Replays a sample of recent telemetry events against a candidate policy YAML and reports how many would have been allowed, denied, or throttled. Useful for regression-checking a draft before activating.

Response 200 OK: counts plus a per-event decision array.

Analyze a Policy

POST /v1/agents/:agent_id/policies/analyze

Auth: JWT (viewer+)

Runs the static analyzer over a policy YAML and returns warnings: contradictory rules, redundant rules, overly broad allows, redundant rate limits, and unreachable configurations. See Policy warnings for the catalog.

Response 200 OK: array of warnings with line numbers and severity.

Get Merged Effective Policy

GET /v1/agents/:agent_id/policies/merged-effective

Auth: JWT (viewer+)

Returns the agent's active policy merged with the org-level guardrails (the "IAM SCP" model). Org-level deny rules cannot be overridden by an agent's allow rules; this endpoint shows the resulting effective policy after merging.