REST API

Two audiences, two credentials

The API serves running agents and dashboard users, and they authenticate differently. The separation is enforced per endpoint: an agent key cannot reach a project route, and a user token cannot reach an agent route.

Agent endpoints

POST /v1/agents/register

Create or reclaim an agent. The only endpoint authenticated by key alone, since the agent doesn't exist yet. Idempotent on (project, slug).

{
  "project_id": "aw_x7k2m9p4qa",
  "scope": "data",
  "slug": "invoice-processor",
  "name": "Invoice Processor",
  "capabilities": ["ocr"],
  "runtime": "python/3.13",
  "sdk_version": "0.1.0",
  "host": "worker-01"
}

{
  "agent_id": "…uuid…",
  "slug": "invoice-processor",
  "status": "idle",
  "control_epoch": 0,
  "heartbeat_interval_s": 15,
  "paused": false,
  "scope": "data",
  "scope_alias_used": false
}

paused: true means an operator's pause survived a restart — honour it before doing any work. scope_alias_used: true means the scope was renamed and your code names the old one; still works, but update the source.

Errors: 422 on project id mismatch or unknown scope, 403 if the key's scope doesn't match, 401 on a bad key.

POST /v1/agents/checkin

The one call your loop needs. Heartbeat, control, and delivery.

{
  "control_epoch": 3,
  "pause_confirmed": false,
  "max_directives": 10,
  "include_peers": false,
  "feed_limit": 0,
  "activity": {
    "kind": "task_started",
    "message": "processing INV-4471",
    "severity": "info",
    "task_ref": "INV-4471"
  }
}

{
  "server_time": "2026-01-01T14:02:11Z",
  "status": "busy",
  "control": "run",
  "control_epoch": 3,
  "heartbeat_interval_s": 15,
  "directives": [],
  "inbox_replies": [],
  "peers": [],
  "feed": []
}

control is the instruction you must obey:

• run — carry on.
• pause — stop at your next checkpoint, then check in again with pause_confirmed: true. Nothing is delivered while paused.
• terminate — shut down.

control_epoch increments on every control command. Send back the last value you saw; a higher number in the response means a new instruction landed.

A 404 here means your agent isn't registered (deleted, or you skipped registration) — not that your key is bad. Re-register and retry.

POST /v1/agents/activity

Report out of band from the loop. Most agents should attach activity to a check-in instead; this is for narrating more often than you check in.

Kinds: started, stopped, task_started, task_progress, task_completed, task_failed, checkpoint, paused, resumed, note, error.

Optional node_id: the tree node this work is about. The dashboard then draws the agent on that node while the work runs, instead of guessing engagement from the wording of your message. Cleared when the agent goes idle.

POST /v1/directives/{id}/respond

{
  "body": "applied, skipped 3 invoices",
  "is_final": true,
  "declined": false
}

is_final: false marks the directive acknowledged; true marks it acted_on. Set declined: true with a decline_reason if you cannot comply.

POST /v1/inbox

Ask a human. Agent to human only — messages in the other direction are directives, and both appear together in the dashboard inbox.

{
  "kind": "approval",
  "subject": "Approve large invoice?",
  "body": "ACME, $84,000. Approve?",
  "blocks_agent": true,
  "options": ["approve", "reject"]
}

The answer arrives in inbox_replies on a later check-in. GET /v1/inbox/mine lists your own open questions, useful for reconciling after a restart.

Tree

Shared context for the scope. All of these act as the calling agent and are scoped to its own scope. See core concepts for the model.

Dashboard endpoints

All require a user token and membership in the project. Requests for a project you are not a member of return 404.

Projects and scopes

Tree

Deleting a scope that still has agents returns 409 — orphaning them would make them vanish from the canvas.

Keys

Agents

Directives

{
  "target": { "kind": "scope", "scope_id": "…", "include_descendants": true },
  "body": "skip anything from vendor ACME",
  "expects_reply": true,
  "expires_in_s": 3600
}

target.kind is one of agent, agents, scope, capability, project. A target matching nobody returns 422 — a broadcast that reached no one is almost always a mistake in the target. capability is available here but not yet in the dashboard, which targets an agent, a scope, or the whole project.

include_descendants follows the dotted scope path: targeting engineering also reaches engineering.prod and engineering.prod.api. It defaults to true; set it to false for that scope alone.

Inbox and audit

Conventions

• All timestamps are ISO 8601, UTC, server-assigned.
• Errors return {"detail": "…"} with a real HTTP status.
• 5xx and 429 are safe to retry with exponential backoff. 4xx is not — the same request will fail the same way.
• 402 means the account's plan allowance for the billing period is spent — the key is valid and the request was well-formed. The detail names the date the allowance renews. Every agent write can return it: tree entries, bubbles, answers, directive responses and activity. Check-ins themselves never do — an agent past its allowance still heartbeats, stays visibly online and can still be paused; only the write is dropped.
• History endpoints paginate with an opaque cursor, not an offset. Append-only data read newest-first would shift under an offset between requests.

OpenAPI

The running API serves its own generated spec at /openapi.json, and interactive docs at /docs in development. Those are always current with the deployed version — prefer them over this page if the two ever disagree.