API overview

The Claros web app talks to a FastAPI server. This reference is generated from it.

The API is not offered as a public API during preview. We issue scoped keys on request; endpoints may change.

Authentication

Every route except GET /healthz and device sign-in needs Authorization: Bearer <credential>: an API key (clr_…) or a browser session token (clt_…). /v1/account/* uses the web session cookie instead, plus X-CSRF-Token on writes. Scopes, limits and errors: Access control.

Conventions

JSON, snake_case field names.
Every timestamp on the wire is epoch milliseconds.

Main routes

Area	Routes
Checks	`POST /v1/check`, `POST /v1/check/page`, `POST /v1/check/screen`, `POST /v1/check/{id}/outcome`, `GET /v1/checks`, `GET /v1/checks.csv`
Asks & decisions	`GET /api/questions`, `POST /api/questions/{id}/decide`, `GET /v1/check/{id}/decision`, `GET`/`POST /q/{token}` (signed one-tap link), `GET`/`PUT /api/notify/me`, `GET /api/proposals`
Rules	`POST /api/rules` (Add a rule), `POST /api/rules/try`, `POST`/`DELETE /api/rules/{id}`, `POST /api/maps/from-policy`, `POST /api/maps/{id}/approve` (`{"enforce": true}` skips watch), `POST`/`DELETE /api/maps/{id}/guardrails/{gid}`, `GET /api/maps/{id}/rules/{rid}/versions`
Rule sets	`GET /api/workflows`, `GET /api/workflows/{id}`, `GET /v1/maps/{id}/export` (AGENTS.md, DESIGN.md, skill)
Connectors	`GET`/`POST /api/connectors`, `POST /api/connectors/{id}/sync`, `POST /api/connectors/import`, `GET /api/review`, `POST /api/review/{id}/confirm`
Agents	`POST /v1/agents/seen` (heartbeat), `GET /v1/me/agents`, `GET /api/me/timeline`, `GET /api/agents/fleet`
Evidence	`GET /v1/ledger`, `GET /v1/ledger/checkpoints`, `GET /api/evidence/verify`, `GET /api/evidence/stream`, `GET /api/evidence/aiuc1`, `GET /api/evidence/report`, `GET /api/workspace/summary`
Accounts	`POST /v1/device`, `POST /v1/device/token`, `GET /v1/whoami`, `/v1/account/*` (web session)
Voice sessions (optional)	`POST /api/sessions`, `POST /api/sessions/{id}/end`, `POST /api/sessions/{id}/publish`, `GET /api/workflows/{id}/walkthrough`, capture requests (`/api/requests`), media (`GET /api/keyframes/{id}.jpg`, redacted only)

Only for the optional voice path: record rules by voice.

Live session

WS /ws/session/{session_id} carries a voice recording session (optional): keyframes, activity, transcripts and controls from the browser; questions, interventions, nudges and map updates from the server. It isn’t part of the OpenAPI spec.

Agent surfaces

Surface	Scope	Use
`POST /v1/check`	`agent`	Check an action: `{app?, tool?, action?, state, arguments?, workflow_id?, actor?, fetched?}`
`POST /v1/check/page`, `POST /v1/check/screen`	`agent`	Browser hooks: a DOM record, or a screenshot
`GET /v1/check/example`	`agent`	A record that breaks a rule (`getclaros test`)
`POST /v1/tools`, `GET /v1/tools/kinds`	`agent`	The guard registers tools and asks which only read
`GET /v1/tools`, `POST /v1/tools/{id}/mapping`	`capture`	Review and confirm tool mappings
`GET /v1/checks`, `GET /v1/checks.csv`	`capture`	The check log
`GET /api/export/{workflow_id}.skill.md`	`agent`, `capture`	A loadable skill
`POST /mcp`, `GET /mcp/sse`	`agent`	MCP tools `check_action`, `get_decision`, `report_override`, `find_guardrails`, `get_workflow`, `quote`

See MCP guard, How a stop looks and MCP server.

# where your Claros server is (or your own URL, if you self-host)
export CLAROS_URL=$(curl -s https://claros.sh/.well-known/claros.json | jq -r .api)
curl -X POST $CLAROS_URL/v1/check \
  -H "Authorization: Bearer $CLAROS_KEY" -H "content-type: application/json" \
  -d '{"app": "helpdesk", "tool": "create_refund", "action": "create",
       "state": {"amount": 820, "method": "gift_card"}}'

Regenerating the spec

From the repo root:

CLAROS_DB=:memory: CLAROS_PII_MODEL=off uv run --project server python docs-site/api-reference/export_openapi.py

It imports the app without starting it and makes no outside calls. A new route fails until it has a title and group in that script.

Overview

Endpoints

Authentication

Conventions

Main routes

Live session

Agent surfaces

Regenerating the spec

​Authentication

​Conventions

​Main routes

​Live session

​Agent surfaces

​Regenerating the spec

Authentication

Conventions

Main routes

Live session

Agent surfaces

Regenerating the spec