REST API Reference¶

Bernstein exposes a task-server HTTP API on http://127.0.0.1:8052 by default. The full OpenAPI 3.1 specification is available at /openapi.json when the server is running.

This page is the canonical hand-maintained reference. It covers ~196 HTTP/WebSocket endpoints across 49 route files, plus 8 MCP tools. Endpoints requiring authentication are marked with Y in the Auth column.

Generating the spec¶

Use the included script to regenerate docs/openapi.json from the FastAPI app definition without starting the server:

uv run python scripts/generate_openapi.py
# Written docs/reference/openapi.json  (216 paths, 72 schemas)

Run this after adding or modifying any API route, Pydantic model, or response schema, then commit the updated JSON. The hosted Redoc page reads the spec at load time, so the rendered reference updates automatically once the JSON is committed.

Alternative -- fetch from a running server:

bernstein run &
curl -s http://127.0.0.1:8052/openapi.json > docs/reference/openapi.json

The OpenAPI JSON declares each route at both its bare path (e.g. /tasks) and an /api/v1/-prefixed alias (e.g. /api/v1/tasks). Both are live; pick one prefix per client.

Authentication¶

When auth is enabled (BERNSTEIN_AUTH_ENABLED=true), endpoints marked Auth: Y require a Bearer token:

curl -H "Authorization: Bearer <token>" http://127.0.0.1:8052/tasks

Public endpoints (no auth required): /health, /health/ready, /health/live, /.well-known/agent.json, /.well-known/acp.json, /docs, /openapi.json, plus loopback connections from 127.0.0.1 (for local CLI use).

Bearer tokens are issued via /auth/cli/token (device flow) or /auth/token (programmatic), and rotated via /auth/refresh.

Health and lifecycle¶

Source: core/routes/status_lifecycle.py.

Status and dashboard¶

Source: core/routes/status_dashboard.py, core/routes/status_events.py.

Tasks¶

Source: core/routes/task_crud.py, core/routes/paginated_tasks.py, core/routes/batch_ops.py, core/routes/task_detail.py.

CRUD and search¶

Lifecycle operations¶

Batch operations¶

Streaming and dashboard views¶

Agents and team¶

Source: core/routes/agents.py, core/routes/team.py, core/routes/agent_comparison.py.

WebSocket¶

The /ws endpoint is the recommended subscription channel for live UI; use SSE endpoints (/events, /agents/{id}/stream) for unidirectional consumers.

Plans and graph¶

Source: core/routes/plans.py, core/routes/graph.py.

Quality¶

Source: core/routes/quality.py, core/routes/file_health.py.

Observability and costs¶

Source: core/routes/observability.py, core/routes/costs.py, core/routes/provider_latency.py, core/routes/predictive.py, core/routes/custom_metrics.py, core/routes/grafana.py, core/routes/slo.py.

Observability¶

Costs¶

Provider latency and predictions¶

Grafana and SLO¶

Webhooks and chat¶

Source: core/routes/webhooks.py, core/routes/notifications.py.

Workspace, GraphQL, hooks, identities¶

Source: core/routes/workspace.py, core/routes/graphql.py, core/routes/hooks.py, core/routes/identities.py.

ACP and A2A protocols¶

Source: core/routes/acp.py, core/routes/a2a.py.

ACP (Agent Client Protocol)¶

A2A (Agent-to-Agent)¶

Auth¶

Source: core/routes/auth.py.

Approvals¶

Source: core/routes/approvals.py.

Audit, drain, export, SBOM¶

Source: core/routes/audit_log.py, core/routes/drain.py, core/routes/export.py, core/routes/sbom.py.

Sandbox and cluster¶

Source: core/routes/sandbox.py, core/routes/task_cluster.py.

Sandbox sessions¶

Cluster¶

Note on legacy paths. Earlier versions of this reference listed POST /cluster/register, POST /cluster/heartbeat, and GET /cluster/topology. None of those exist in the current codebase. Use the paths above.

Bulletin and channel¶

Source: core/routes/bulletin.py, core/routes/channel.py.

MCP tools¶

The MCP tools below are exposed via Bernstein's MCP server (core/mcp/server.py), not over HTTP. They are callable from any MCP-aware client (Claude Desktop, Cursor, etc.) once the MCP server is registered.

These are MCP tools, not HTTP endpoints. They consume tool-call payloads matching each tool's MCP schema (see mcp/server.py for inputSchema definitions).

Request/response examples¶

Create a task¶

curl -X POST http://127.0.0.1:8052/tasks \
  -H "Content-Type: application/json" \
  -d '{
    "goal": "Implement user authentication",
    "role": "backend",
    "priority": 2,
    "scope": ["src/auth/"],
    "complexity": "medium"
  }'

Response:

{
  "id": "task-a1b2c3d4",
  "goal": "Implement user authentication",
  "role": "backend",
  "status": "open",
  "priority": 2,
  "created_at": 1712345678.0
}

List open tasks¶

curl 'http://127.0.0.1:8052/tasks?status=open'

Complete a task¶

curl -X POST http://127.0.0.1:8052/tasks/task-a1b2c3d4/complete \
  -H "Content-Type: application/json" \
  -d '{
    "summary": "Added JWT auth with refresh tokens",
    "files_changed": ["src/auth/jwt.py", "tests/test_jwt.py"]
  }'

Report progress¶

curl -X POST http://127.0.0.1:8052/tasks/task-a1b2c3d4/progress \
  -H "Content-Type: application/json" \
  -d '{
    "files_changed": 3,
    "tests_passing": true,
    "errors": []
  }'

Register a worker node (cluster)¶

curl -X POST http://127.0.0.1:8052/cluster/nodes \
  -H "Authorization: Bearer ${BERNSTEIN_AUTH_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "node_id": "worker-eu-1",
    "address": "10.0.0.4:8052",
    "labels": {"region": "eu", "tier": "spot"}
  }'

Error responses¶

All errors return JSON with a detail field:

{ "detail": "Task not found: task-xyz" }

Rendering full HTML docs¶

Use any OpenAPI renderer:

# Redoc
npx @redocly/cli build-docs docs/reference/openapi.json -o docs/api.html

# Swagger UI (Docker)
docker run -p 8080:8080 -e SWAGGER_JSON=/spec/openapi.json \
  -v "$(pwd)/docs/reference":/spec swaggerapi/swagger-ui

Webhooks (outbound)¶

Bernstein can send webhook notifications for task lifecycle events. Configure in bernstein.yaml:

webhooks:
  url: "https://your-app.example.com/bernstein-events"
  events:
    - task.created
    - task.completed
    - task.failed
    - agent.spawned
    - agent.completed
  secret: "your-hmac-secret"

Webhook payloads include an X-Bernstein-Signature header containing an HMAC-SHA256 signature of the request body, computed with the configured secret.