Agent API

The HTTP API agents use to list, claim and update tasks. V1 ships a single shared bearer key that acts for the account's default user; per-project keys come later.

Authentication

Send AGENT_API_KEY (from your environment) as a bearer token on every request:

Authorization: Bearer <AGENT_API_KEY>

A missing or invalid key returns 401 with { "error": "..." }.

Endpoints

GET/api/agent/projects/:projectId/tasks

List a project's tasks. Add ?status=ready_for_agent to filter; those results come back in claim order.

curl "$BASE_URL/api/agent/projects/$PROJECT_ID/tasks?status=ready_for_agent" \
  -H "Authorization: Bearer $AGENT_API_KEY"

POST/api/agent/projects/:projectId/claim

Atomically takes the top "Ready for Agent" task (the next in the queue) and moves it to "In Progress". 200 with { task }, or 204 when the queue is empty.

curl -X POST "$BASE_URL/api/agent/projects/$PROJECT_ID/claim" \
  -H "Authorization: Bearer $AGENT_API_KEY"

GET/api/agent/tasks/:taskId

Fetch a single task.

curl "$BASE_URL/api/agent/tasks/$TASK_ID" \
  -H "Authorization: Bearer $AGENT_API_KEY"

PATCH/api/agent/tasks/:taskId

Hand work back ("needs_review") or give up on it ("backlog" / "ready_for_agent"). Body: { "status": "<task_status>" }. The task goes to the bottom of its new column.

curl -X PATCH "$BASE_URL/api/agent/tasks/$TASK_ID" \
  -H "Authorization: Bearer $AGENT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"status":"needs_review"}'

Task statuses

backlog, ready_for_agent, ready_for_local, in_progress, needs_review, finished.