Agents

Create, manage, and control AI agents registered with Checkrd.

Agents

An agent represents a single AI service registered with Checkrd. Each agent has its own identity, policy configuration, kill switch, and telemetry stream.

The Agent Object

json

{
  "id": "01916a3e-7b2c-4d1f-8e3a-abc123def456",
  "org_id": "01916a3e-0000-0000-0000-000000000000",
  "name": "sales-agent",
  "slug": "sales-agent",
  "description": "Handles CRM API calls for the sales team",
  "status": "active",
  "public_key": "a1b2c3d4e5f6...",
  "kill_switch_active": false,
  "created_at": "2026-04-10T14:30:00Z"
}

Field	Type	Description
`id`	UUID	Unique identifier.
`org_id`	UUID	Owning organization.
`name`	string	Display name.
`slug`	string	URL-safe identifier, auto-generated from name.
`description`	string or null	Optional description.
`status`	string	`active` or `inactive`.
`public_key`	string or null	Hex-encoded Ed25519 public key, set by the SDK.
`kill_switch_active`	boolean	Whether the kill switch is engaged.
`created_at`	ISO 8601	Creation timestamp.

Create an Agent

POST /v1/agents

Auth: JWT (member+)

Parameter	Type	Required	Description
`name`	string	Yes	Agent name.
`description`	string	No	Optional description.

bash

curl -X POST https://api.checkrd.io/v1/agents \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "sales-agent", "description": "CRM API calls"}'

Response 201 Created

json

{
  "id": "01916a3e-7b2c-4d1f-8e3a-abc123def456",
  "org_id": "01916a3e-0000-0000-0000-000000000000",
  "name": "sales-agent",
  "slug": "sales-agent",
  "description": "CRM API calls",
  "status": "active",
  "public_key": null,
  "kill_switch_active": false,
  "created_at": "2026-04-10T14:30:00Z"
}

Subject to plan tier agent limits (Free: 5, Team: 50, Enterprise: unlimited).

List Agents

GET /v1/agents

Auth: JWT (viewer+)

Parameter	Type	Required	Description
`limit`	integer	No	Results per page (default 20, max 100).
`cursor`	UUID	No	Pagination cursor from previous response.

bash

curl https://api.checkrd.io/v1/agents?limit=10 \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

Response 200 OK

json

{
  "data": [
    { "id": "...", "name": "sales-agent", "status": "active", ... }
  ],
  "has_more": false,
  "next_cursor": null
}

Retrieve an Agent

GET /v1/agents/:agent_id

Auth: JWT (viewer+)

bash

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

Response 200 OK -- Returns the agent object.

Update an Agent

PUT /v1/agents/:agent_id

Auth: JWT (member+)

Parameter	Type	Required	Description
`name`	string	No	New name.
`description`	string	No	New description.

bash

curl -X PUT https://api.checkrd.io/v1/agents/01916a3e-7b2c-... \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"description": "Updated description"}'

Response 200 OK -- Returns the updated agent object.

Delete an Agent

DELETE /v1/agents/:agent_id

Auth: JWT (admin+)

bash

curl -X DELETE https://api.checkrd.io/v1/agents/01916a3e-7b2c-... \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

Response 200 OK

json

{ "success": true }

This is a soft delete. Telemetry data is retained.

Toggle Kill Switch

POST /v1/agents/:agent_id/kill-switch

Auth: JWT (admin+)

Parameter	Type	Required	Description
`active`	boolean	Yes	`true` to block all outbound calls, `false` to resume.

bash

curl -X POST https://api.checkrd.io/v1/agents/01916a3e-7b2c-.../kill-switch \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"active": true}'

Response 200 OK -- Returns the updated agent object with kill_switch_active: true.

The kill switch state is pushed to connected SDKs in real time via SSE. SDKs that poll will pick up the change on their next request.

Register Public Key

POST /v1/agents/:agent_id/public-key

Auth: API Key

Parameter	Type	Required	Description
`public_key`	string	Yes	Hex-encoded 32-byte Ed25519 public key (64 hex chars).

bash

curl -X POST https://api.checkrd.io/v1/agents/01916a3e-7b2c-.../public-key \
  -H "Authorization: Bearer ck_live_..." \
  -H "Content-Type: application/json" \
  -d '{"public_key": "a1b2c3d4e5f6..."}'

Response 200 OK

json

{
  "registered": true,
  "public_key": "a1b2c3d4e5f6..."
}

Idempotent: re-registering the same key returns registered: false. Attempting to register a different key for the same agent returns 409 Conflict.

Errors API Keys