# API

Everything the app does goes through one HTTP API, which connected agents use too. The complete reference for agents is [the skill](/skill.md); this page is the outline.

## Requests

JSON in and out under `/api/v1`, with a key as `Authorization: Bearer <key>`. A refusal is `{"error": "code", "message": "a sentence for a person"}`; pass the message on as it is.

| Request | What it does |
|---|---|
| `GET /api/v1/you` | your documents, requests, keys and limits |
| `POST /api/v1/documents` | make a document, with its first version |
| `GET /api/v1/s/{doc}` | open a document: its drafts, version, pages and comments |
| `GET /api/v1/s/{doc}/file?version=&name=` | one page or file, as stored |
| `GET /api/v1/s/{doc}/versions?draft=` | a draft's versions, newest first; `draft=all` for every draft's |
| `POST /api/v1/s/{doc}/save` | save the next version of a draft |
| `POST /api/v1/s/{doc}/drafts` | begin a draft |
| `POST /api/v1/s/{doc}/drafts/{draft}/merge` | merge a draft back where it began |
| `GET /api/v1/s/{doc}/compare?from=&to=` | what each page did between two versions |
| `GET`, `POST /api/v1/s/{doc}/comments` | read the comments, or write one |
| `POST /api/v1/s/{doc}/access` | ask somebody already on the document for feedback |
| `GET /api/v1/s/{doc}/events` | live updates, as server-sent events |
| `GET /api/v1/you/search?q=` | the documents you can read that say these words, best first |

## MCP

`POST /mcp` speaks the Model Context Protocol with the same key. Its tools are `find_documents`, `open_document`, `read_file`, `list_versions`, `list_comments`, `comment`, `resolve_comment`, `write_version`, `update_document`, `image_upload_link`, `compare_versions`, `merge_draft`, `ask_approval` and `ask_for_feedback`; each is one of the requests above.

## For agents

`/llms.txt` lists these pages as Markdown, and `/llms-full.txt` is all of them in one file.