# Draw API reference — `wpds-draw/v1`

Base: the app origin. All bodies are JSON. Errors are
`{"error": {"code", "message"}}` with the matching HTTP status.

## Authentication

`Authorization: Bearer <token>` (or `X-Draw-Token`). The token comes from the
server's `DRAW_TOKEN` env or `/run/secrets/draw-token`. Without it, gated
routes return 401 (or 503 when the server has no token configured at all).

Public, content-free: `GET /health`, `GET /api/v1/app`, `GET /api/v1/status`,
`GET /api/v1/auth/check`.

## Discovery and health

| Route | Returns |
| --- | --- |
| `GET /health` | `{"ok": true}` liveness. |
| `GET /api/v1/app` | Stable app info: id, name, purpose, versions, capabilities, auth mode, data boundary, doc paths. |
| `GET /api/v1/status` | Runtime: drawing/trash counts, data-dir writability, newest update, version, `authConfigured`. |
| `GET /api/v1/auth/check` | `{"ok": bool}` for the supplied token. |

## Drawings (token-gated)

| Route | Effect |
| --- | --- |
| `GET /api/v1/drawings` | List non-trashed drawings, newest first (metadata + thumb, no strokes). |
| `POST /api/v1/drawings` | Create. Body `{title, strokes, thumb}`. 201 with the document; `ETag` = rev. |
| `GET /api/v1/drawings/{id}` | Full document including strokes. `ETag` = rev. |
| `PUT /api/v1/drawings/{id}` | Update. `If-Match: <rev>` required for conflict safety; stale rev → 409 `conflict`. |
| `DELETE /api/v1/drawings/{id}` | Recoverable: sets the trash flag. Returns `{"ok": true, "recoverable": true}`. |
| `PUT /api/v1/drawings/{id}/restore` | Clears the trash flag. Trashed drawings refuse ordinary updates with 409 `gone`. |

Validation: title ≤ 200 chars; strokes ≤ 20000 items, each `{tool, color,
size, points: [[x,y],…]}`; thumb is a PNG data URL ≤ 400KB; body ≤ 5MB.

## Profile (token-gated)

| Route | Effect |
| --- | --- |
| `GET /api/v1/profile` | `{displayName, avatarSeed}` local profile. |
| `PUT /api/v1/profile` | Update both fields. Name ≤ 80 chars. |

## MCP mapping

`mcp/server.py` (stdio) adapts the same store: `draw_app_info` and
`draw_status` mirror the discovery routes; `draw_list_drawings`,
`draw_get_drawing` mirror the reads; `draw_rename_drawing` (rev-checked),
`draw_trash_drawing`, `draw_restore_drawing` are the only writes and carry
effect labels. Stroke-writing and profile routes are HTTP-only in 0.1.0.