docs(api): document auth, request ids, errors, examples
This commit is contained in:
Abhimanyu Saharan
committed by
Abhimanyu Saharan
Abhimanyu Saharan
parent
a3a9a12a02
commit
32e8855404
@@ -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
|
||||
|
||||
Reference in New Issue
Block a user