142 lines
3.8 KiB
Markdown
142 lines
3.8 KiB
Markdown
# 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
|