diff --git a/docs/reference/api.md b/docs/reference/api.md
index eab14351..77e83c13 100644
--- a/docs/reference/api.md
+++ b/docs/reference/api.md
@@ -1,10 +1,141 @@
-# API notes
+# API reference (notes + conventions)
 
-- Backend defaults to http://localhost:8000
+Mission Control exposes a JSON HTTP API (FastAPI) under `/api/v1/*`.
+
+- Default backend base URL (local): `http://localhost:8000`
 - Health endpoints:
-  - `/health`
-  - `/healthz`
-  - `/readyz`
+  - `GET /health` (liveness)
+  - `GET /healthz` (liveness alias)
+  - `GET /readyz` (readiness)
 
-> **Note**
-> Add canonical API docs strategy here (OpenAPI, versioning, examples).
+## 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