openclaw-mission-control/docs/reference/api.md

# API reference (notes + conventions)

Mission Control exposes a JSON HTTP API (FastAPI) under `/api/v1/*`.

- Default backend base URL (local): `http://localhost:8000`
- Health endpoints:
  - `GET /health` (liveness)
  - `GET /healthz` (liveness alias)
  - `GET /readyz` (readiness)

## OpenAPI / Swagger

- OpenAPI schema: `GET /openapi.json`
- Swagger UI (FastAPI default): `GET /docs`

> If you are building clients, prefer generating from `openapi.json`.

## API versioning

- Current prefix: `/api/v1`
- Backwards compatibility is **best-effort** while the project is under active development.

## Authentication

All protected endpoints expect a bearer token:

```http
Authorization: Bearer <token>
```

Auth mode is controlled by `AUTH_MODE`:

- `local`: shared bearer token auth (token is `LOCAL_AUTH_TOKEN`)
- `clerk`: Clerk JWT auth

Notes:
- The frontend uses the same bearer token scheme in local mode (users paste the token into the UI).
- Many “agent” endpoints use an agent token header instead (see below).

### Agent auth (Mission Control agents)

Some endpoints are designed for autonomous agents and use an agent token header:

```http
X-Agent-Token: <agent-token>
```

In the backend, these are enforced via the “agent auth” context. When in doubt, consult the route’s dependencies (e.g., `require_admin_or_agent`).

## Authorization / permissions model (high level)

The backend distinguishes between:

- **users** (humans) authenticated via `AUTH_MODE`
- **agents** authenticated via agent tokens

Common patterns:

- **Admin-only** user endpoints: require an authenticated user with admin privileges.
- **Admin or agent** endpoints: allow either an admin user or an authenticated agent.
- **Board-scoped access**: user/agent access may be restricted to a specific board.

> SOC2 note: the API produces an audit-friendly request id (see below), but role/permission policy should be documented per endpoint as we stabilize.

## Request IDs

Every response includes an `X-Request-Id` header.

- Clients may supply their own `X-Request-Id`; otherwise the server generates one.
- Use this id to correlate client reports with server logs.

## Errors

Errors are returned as JSON with a stable top-level shape:

```json
{
  "detail": "...",
  "request_id": "..."
}
```

Common status codes:

- `401 Unauthorized`: missing/invalid credentials
- `403 Forbidden`: authenticated but not allowed
- `404 Not Found`: resource missing (or not visible)
- `422 Unprocessable Entity`: request validation error
- `500 Internal Server Error`: unhandled server errors

Validation errors (`422`) typically return `detail` as a list of structured field errors (FastAPI/Pydantic style).

## Pagination

List endpoints commonly return an `items` array with paging fields (varies by endpoint). If you’re implementing new list endpoints, prefer consistent parameters:

- `limit`
- `offset`

…and return:

- `items: []`
- `total`
- `limit`
- `offset`

## Examples (curl)

### Health

```bash
curl -f http://localhost:8000/healthz
```

### Agent heartbeat check-in

```bash
curl -s -X POST http://localhost:8000/api/v1/agent/heartbeat \
  -H "X-Agent-Token: $AUTH_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name":"Tessa","board_id":"<board-id>","status":"online"}'
```

### List tasks for a board

```bash
curl -s "http://localhost:8000/api/v1/agent/boards/<board-id>/tasks?status=inbox&limit=10" \
  -H "X-Agent-Token: $AUTH_TOKEN"
```

## Gaps / follow-ups

- Per-endpoint documentation of:
  - required auth header (`Authorization` vs `X-Agent-Token`)
  - required role (admin vs member vs agent)
  - common error responses per endpoint
- Rate limits are not currently specified in the docs; if enforced, document them here and in OpenAPI.
- Add canonical examples for:
  - creating/updating tasks + comments
  - board memory streaming
  - approvals workflow