Reference

HTTP API

Every endpoint, including the three SSE streams.

One FastAPI service, started by agentfast serve. The playground, the dashboard and the HITL queue are all clients of it — there is no private API behind them.

Everything it returns is already redacted; traces are stored post-guardrails.

Authentication

api_auth_token: ${AGENTFAST_API_TOKEN}

When set, every endpoint except /api/health requires a bearer token:

curl localhost:8321/api/runs -H "Authorization: Bearer $AGENTFAST_API_TOKEN"

CarefulKeyless mode is allowed and warns loudly

With no token configured the API is open to anyone who can reach it — including the approval endpoints. That's fine on localhost and wrong everywhere else. The server logs a startup warning so this can't happen quietly.

CORS defaults to the local playground and dashboard ports only:

cors_origins: ["http://localhost:3400", "http://localhost:3401"]

Running an agent

`POST /api/chat`

Blocking. Runs to completion (or to a pause) and returns one JSON object.

curl -X POST localhost:8321/api/chat \
  -H 'Content-Type: application/json' \
  -d '{"message": "I need a refund for ord_1001", "session_id": "sess_1"}'

{
  "session_id": "sess_1",
  "run_id": "run_b4110ebd…",
  "status": "paused",
  "output": "",
  "pending_approvals": ["appr_run_b4110ebd…_call_refund_1"]
}

| Field | | | |---|---|---| | message | required | The user's turn | | session_id | optional | Memory is scoped to it. Generated if omitted | | user_id | optional | Scopes long-term memory |

`POST /api/chat/stream`

The same run, streamed as SSE. Returns text/event-stream. See Streaming for the event list.

Client disconnect does not cancel the run.

`POST /api/runs/{run_id}/resume`

Resume a paused run. Blocking.

`POST /api/runs/{run_id}/resume/stream`

Resume, streamed. Pair with decide at auto_resume: false so the decision and the resumed run don't race.

Inspecting runs

`GET /api/runs?limit=50&offset=0`

Run list for the dashboard index.

`GET /api/runs/{run_id}`

One run plus its full step tree and approvals.

{
  "run": { "run_id": "run_…", "status": "completed", "total_cost_usd": 0.0059 },
  "steps": [ { "idx": 0, "type": "planning", "name": "complexity:medium" } ],
  "approvals": []
}

`GET /api/runs/{run_id}/stream`

Re-attach to a run in flight. Replays the step tree so far, then follows live. This is what a dropped connection should reconnect to — never a second POST /api/chat/stream.

`GET /api/runs/{run_id}/telemetry`

The canonical per-run record. 404 while the run is still going.

Approvals

`GET /api/approvals?status=pending`

The HITL queue.

`POST /api/approvals/{approval_id}/decide`

curl -X POST localhost:8321/api/approvals/appr_run_abc_call_1/decide \
  -H 'Content-Type: application/json' \
  -d '{"decision": "approved", "decided_by": "alice@ops", "auto_resume": true}'

| Field | Default | | |---|---|---| | decision | required | approved or rejected | | decided_by | dashboard | Recorded on the approval | | note | — | Rejection reason. Goes back into the agent's reasoning | | auto_resume | true | Resume the run if it was suspended |

409 if already decided — approvals are decided once.

Evals

`GET /api/evals?case_id=…`

Stored eval results.

MCP management

| | | |---|---| | GET /api/mcp/catalog | Known servers you can add | | GET /api/mcp/servers | Configured servers | | POST /api/mcp/servers | Add one — edits agentfast.yaml | | DELETE /api/mcp/servers/{name} | Remove one | | POST /api/mcp/servers/{name}/test | Connect for real and list its tools |

Health

`GET /api/health`

Always public — load balancers and Compose health checks need it.

{ "ok": true, "agent": "support", "sdk": "langgraph" }