API Reference

Create a new task.

curl -s -X POST http://127.0.0.1:8052/tasks \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Add pagination to users API",
    "role": "backend",
    "description": "Implement cursor-based pagination on GET /users.",
    "priority": 1,
    "scope": "small",
    "complexity": "low"
  }'

Body fields:

List tasks. Optionally filter by status or role.

curl http://127.0.0.1:8052/tasks
curl "http://127.0.0.1:8052/tasks?status=open"
curl "http://127.0.0.1:8052/tasks?status=in_progress"
curl "http://127.0.0.1:8052/tasks?role=backend"

Query params: status (open | in_progress | done | failed | blocked), role

Get a single task by ID.

curl http://127.0.0.1:8052/tasks/abc123

Claim the next open task for a given role. Used by agent adapters to pick up work.

curl http://127.0.0.1:8052/tasks/next/backend

Returns 404 if no tasks are available for that role.

Claim a specific task by ID.

curl -X POST http://127.0.0.1:8052/tasks/abc123/claim \
  -H "Content-Type: application/json" \
  -d '{"agent_id": "agent-42"}'

Mark a task as done. The janitor will verify completion signals before finalising.

curl -X POST http://127.0.0.1:8052/tasks/abc123/complete \
  -H "Content-Type: application/json" \
  -d '{"result_summary": "Added cursor pagination to GET /users"}'

Mark a task as failed.

curl -X POST http://127.0.0.1:8052/tasks/abc123/fail \
  -H "Content-Type: application/json" \
  -d '{"reason": "Cannot resolve import — missing dependency"}'

Recent completed and failed task records.

curl http://127.0.0.1:8052/tasks/archive

Dashboard summary — task counts per status and agent summary.

curl http://127.0.0.1:8052/status

Example response:

{
  "tasks": { "open": 4, "in_progress": 3, "done": 7, "failed": 0 },
  "agents": { "active": 3, "idle": 0 },
  "uptime_seconds": 312
}

Register agent liveness. Agents must heartbeat every heartbeat_timeout seconds or the spawner will kill and respawn them.

curl -X POST http://127.0.0.1:8052/agents/agent-42/heartbeat

Aggregated cost breakdown by model, role, and task.

curl http://127.0.0.1:8052/costs

Real-time cost data for the current run.

Active cost alerts (budget threshold warnings).

Historical cost records across previous runs.

Cost breakdown for a specific run.

Quality dashboard data: pass rates, verification results, and trends.

Per-model quality metrics (success rates, average scores).

Active system alerts (task failures, budget warnings, agent health).

GitHub webhook receiver. Processes push events, PR events, and CI status updates to create or update tasks automatically.

List configured authentication providers (OIDC, SAML).

Initiate OIDC login flow (redirects to provider).

Start CLI device code flow for headless authentication.

Current authenticated user profile.

List all plans (pending, approved, rejected).

Get a specific plan by ID.

Approve a pending plan. Approved plans are converted into tasks.

Reject a pending plan with an optional reason.

Overview of agent graduation status across all sessions.

Graduation details for a specific agent session.

Promote an agent session to a higher trust level based on performance.

Slack slash command handler. Supports /bernstein status, /bernstein run, etc.

Slack Events API handler for real-time notifications.

ACP discovery document. Describes available agents, capabilities, and protocol version.

List agents available via the ACP protocol.

Create a new ACP run (submit work to an agent).

Check the status of an ACP run.

Post a message to the bulletin board. Agents use this to share findings or warnings with each other.

curl -X POST http://127.0.0.1:8052/bulletin \
  -H "Content-Type: application/json" \
  -d '{"message": "Found deprecated auth API — all agents should avoid /auth/v1"}'

Read bulletin messages, optionally since a timestamp.

curl "http://127.0.0.1:8052/bulletin?since=1711574400"

Server liveness check. Returns 200 {"status": "ok"} when healthy.

curl http://127.0.0.1:8052/health

Prometheus-format metrics for Grafana and alerting.

Server-Sent Events (SSE) stream for real-time dashboard updates.

Bandit-based model routing statistics (arm weights, selection counts).

Semantic cache hit/miss statistics.