Agents API

The agents API is small on purpose: list, mint, delete. There is no separate revoke endpoint — deleting the agent row revokes the token (the next reconnect attempt fails with 401). There is no separate restart or detail endpoint either; worker control happens through the commands API (restart-worker, pool-resize, etc.).

List agents

GET /api/v1/projects/{slug}/agents

Role: viewer. Returns a list of AgentPublic:

[
  {
    "id": "...",
    "project_id": "...",
    "name": "web-01",
    "state": "online",
    "protocol_version": "2",
    "framework_adapter": "django",
    "engine_adapters": ["celery"],
    "scheduler_adapters": ["celery-beat"],
    "capabilities": {},
    "last_seen_at": "...",
    "last_connect_at": "...",
    "created_at": "...",
    "is_outdated": false
  }
]

is_outdated is true when the agent connected at least once and its last advertised protocol_version is older than the brain’s CURRENT_PROTOCOL. Never-connected agents report false.

Mint agent (returns token + HMAC secret)

POST /api/v1/projects/{slug}/agents

Role: admin. CSRF-protected.

{"name": "billing-worker-02"}

(project_id, name) is unique; a duplicate returns 409 with conflict_duplicate_name. Response (shown once — save both):

{
  "agent": { /* AgentPublic */ },
  "token": "z4j_agent_...",
  "hmac_secret": "<urlsafe-base64, 32 raw bytes>"
}

The hmac_secret is the per-project signing key. It’s HMAC-derived from the brain master secret, so the brain re-derives the same value on every frame and never stores it. Operators paste both token and hmac_secret into the agent’s configuration; the agent refuses to start without hmac_secret.

Delete agent

DELETE /api/v1/projects/{slug}/agents/{agent_id}

Role: admin. CSRF-protected. Removes the agent row and revokes the token. Past tasks and events that reference this agent_id keep the FK pointing at the deleted row for audit; the dashboard renders them as “agent deleted”.