# Paginel API for agents

Everything below is checked against the server's routes by a test (`platform/crates/platform/tests/agent_skill.rs`):
a route missing here, or listed here and gone from the code, fails the build.

## Conventions

- **Base.** `PAGINEL_URL` is the platform's origin, e.g. `https://paginel.com`. `{doc}` is the document's
  id (`…/d/<id>`). Routes are the same on a platform and on a local server.
- **Authentication.** On a platform: `Authorization: Bearer pgn_…` on every call. You do **not** pass
  `?user=`; the platform sets it to `agent:<name of your token>` for you. On a local server (`text-server`,
  default `http://localhost:8787`): no header, but **every call that changes something, and
  `…/instructions`, needs `?user=agent:<name>`** (letters, digits, `-`, `_`).
  The desktop app's own server asks for a token too (`Authorization: Bearer <token>`): see "Local server".
- **Rights.** A token opens a document only through a **right** its owner gave it (see `rules.md`); with none
  that reaches the document, every call answers `404 Document inconnu.`. At most 300 requests a minute
  per token: `429` with `Retry-After` (seconds). What you read as "writes" below (including `POST …/edit`) needs `edit`; comments need `comment`; the rest, `…/instructions` included, needs `read`.
  The document's own rules apply on top (see `rules.md`).
- **Bodies** are JSON (`Content-Type: application/json`) unless said otherwise. **Errors** are
  `{"error": "…"}` with the status codes of `SKILL.md`; messages may be in French.
- **Sizes.** A body is at most 64 MB (documents, sections with images, `.docx`).

## The document

### `GET|DELETE /api/docs/{doc}`
`GET`: the outline and the content. `DELETE` puts the document in the wastebasket: **refused for a token**
(403, « Retirez le document depuis « Mes documents » »); it is for people.
```json
{ "doc": "3f9a…", "title": "Budget 2027",
  "sections": [ { "id": 3, "level": 1, "title": "Context", "parent": null,
                  "owner": "agent:redacteur", "effective_owner": "agent:redacteur" } ],
  "markdown": "---\n…\n---\n<!-- section id=3 owner=agent:redacteur -->\n# Context\n…" }
```
`title` is absent if the document has no name. `GET` on a document that does not exist answers 404.

### `GET|PUT /api/docs/{doc}/markdown`
`GET`: the whole document as Markdown (`text/markdown`), images embedded as base64 (`?images=reference`
for `image:<id>` references). `PUT`: the body (**raw Markdown, not JSON**) **replaces the whole document**;
refused where you may not write; answers with the same JSON as `GET /api/docs/{doc}`.
```sh
curl -sS -X PUT -H "$H" -H 'Content-Type: text/markdown' --data-binary @new.md "$D/markdown"
```
**A board** (Paginel Board: `##` columns, `###` cards): in every Markdown you read (this one, `GET /api/docs/{doc}`,
`GET …/sections/{id}`), each card **ends with its comments, read-only**:
```markdown
### Relire le contrat
Clauses 4 à 7.

> **Suivi** <!-- comments: read-only -->
> - 2026-10-17 12:02 UTC · Jérémy : Commentaire 1.
> - 2026-10-17 13:10 UTC · agent:ia (modifié) : Clause 4 relue.
```
One line per comment, oldest first: when (UTC), author, `(modifié)` if its author changed it, its text on one line.
The block (recognized by `<!-- comments: read-only -->`) is **left out whenever Markdown is written back** (`PUT` here,
`PUT …/sections/{id}`, `POST …/append`): keeping it, changing it or removing it changes no comment and never makes
text. To add a comment to a card: `POST …/comments` `{"text", "card": <its section id>}` (below).
**A card's attachments** (files) are paragraphs of one link each, `[report.pdf](attachment:<id>)`, at the end of the card: keep them
as they are when you write the card back (removing one removes the link only); never write one yourself, attach a file with
`POST /api/agent/files?board=&card=` (below), which writes it.
Every board has it: the platform marks a board when it is made (a new one also gets three empty columns), and a board
made before, the first time an agent reads it.

### `PUT /api/docs/{doc}/title`
`{"title": "New name"}` (or `null`). **People only** on a platform (the owner): a token is refused.

### `POST /api/docs/{doc}/board`
**Not for you**: the platform calls it itself, as the owner, to make a document a board (`{"columns"?: [...]}` →
`{"board": true, "marked", "seeded"}`). A token is refused (403 `document.board_platform_only`). To make a board,
create it with `kind: board` (`POST /api/agent/documents`, below).

### Moving and changing cards and columns
On a board only (400 otherwise), with `edit`; each change is one step of the board's history, signed with your name, and
undoable. A card or a column is its section id (`<!-- section id=… -->` before its heading). **To move a card, use the move**:
rewriting it in another column (`PUT …/sections/{id}`, `POST …/append`) makes a new card, and its comments stay behind.

| Route | Body | Answer |
|---|---|---|
| `POST /api/docs/{doc}/board/cards/{card}/move` | `{"column": 2, "before"?: 7}`: to the end of the column, or before card 7 | `{"card", "column"}`: the card keeps its id, its text and its comments |
| `PATCH /api/docs/{doc}/board/cards/{card}` | `{"title"?, "labels"?: ["a", "b"], "due"?: "2026-11-10", "done"?: true}`: an absent field stays; `"due": null` and `"labels": []` remove; `"done"` marks the card done or not (`done: yes` in its metadata line) | the card: `{"section", "column", "title", "due", "labels", "done", "checks": {"done", "total"}, …}` |
| `POST /api/docs/{doc}/board/columns` | `{"title", "after"?: 2}`: at the end, or after column 2 | `{"column"}` |
| `POST /api/docs/{doc}/board/cards/{card}/attachments` | `{"id", "name"}`: the **link** of a file already on the platform, as the paragraph `[name](attachment:<id>)` at the end of the card. To attach a new file, use `POST /api/agent/files?board=&card=` (below): it keeps the file and writes this link | `{"card", "added", "attachments"}`; `added: false` if the card already links it (nothing written) |
| `DELETE /api/docs/{doc}/board/cards/{card}/attachments/{file}` | — : removes that link from the card (the file stays) | `{"card", "removed"}` |
| `PATCH /api/docs/{doc}/board/columns/{column}` | `{"title"}` | `{"column", "title"}` |

### `GET /api/docs/{doc}/pdf`
The paginated PDF, in the document's fonts. `?pdfa=1|2a|2b` asks for PDF/A; the level reached is in the
`X-Text-Pdfa` header; 422 and the reason if it cannot be reached.

### `GET /api/docs/{doc}/pages`
What each page carries, laid out as the PDF: `{"pages": 3, "paper": {"width_mm", "height_mm"}, "list": [{"n": 1,
"width_mm", "height_mm", "sections": [{"id", "title", "starts"}], "images": [{"id", "x_mm", "y_mm", "width_mm",
"height_mm", "floating", "story"}]}]}`. `sections`: the parts whose text is on the page, in its order (`starts`: the
heading is on this page). `images`: each image drawn, its box in millimetres from the page's top left corner,
`floating` when it is anchored (not in a line of text), `story`: `body`, `header`, `footer` or `footnote`.

### `GET /api/docs/{doc}/pages/{file}`
A page as a PNG image, drawn from the same layout as the PDF (same fonts, same images). `file` is the page number,
from 1, and `.png` (`…/pages/1.png` for the first page). `?width=` in pixels: 1200 by default, held between 200 and
2400. The `X-Text-Pages` header gives the number of pages; a page the document does not have: 404 (`pageNotFound`,
which says how many there are). **Look at the page after you change the layout** (images, page breaks, headings
left alone at the bottom of a page) before saying what you did.

### `GET|POST /api/docs/{doc}/layout`
**Layout by operations** (images, paragraphs, page, styles, template), in Word's own terms; the lexicon « what a
person says → operations » is in `references/markdown.md`, « Layout ».
`POST {"ops": [...], "dry_run"?: true, "images"?: "changed" | [n, n], "width"?: px}` applies the operations in order,
**all or none**: the first one refused stops everything and nothing is written; the answer says which (`op`, from 0,
`op_name`) and why (`error`, `code`). Otherwise one change signed with your name, one step the person can undo.
`dry_run` (in the body, or `?dry_run=1` in the address — with a reading right only, the address's: the body's alone is
refused) works on a copy: its report, nothing written; a refusal of
the rights is then told in `refused`. `images`: the pages touched (`"changed"`: the first two) as PNG in base64.
Answer: `{applied, dry_run, pages: [touched], report, images?: [{n, png}], refused?}`.

| `op` | Fields |
|---|---|
| `image` | `image`: `"image:<id>"` (from the report, or `GET /api/docs/{doc}`) or `{"section": N, "nth": 1}`; `place`: the words of an image title (`"right; width 40%"`, `"top"`, `"behind; page 0 0; width 100%"`, `"inline"`), it replaces the whole placement; or alone `width` (`"40%"` of the text width, `"6cm"`; proportions kept), `height`, `wrap` (`around`, `above-below`, `none`), `gap`, `rotate`, `flip`, which keep the rest; `to`: `{"section"?: N, "text": "exact passage"}` anchors the image at the start of that paragraph |
| `insert_image` | `data` (`data:image/png;base64,…`) or `url` (a public `https://` address), `to` (required), `place`… (`alt` is refused: not kept yet) |
| `paragraph` | `section`? and `text` (the paragraph holding that exact passage) or `all: true` (every paragraph of the part, or of the document, that is not a heading); `align` (`left`, `center`, `right`, `justify`), `space_before`, `space_after` (`null`: the style's), `line` (`1.15`, `"exactly 14pt"`, `"at-least 12pt"`), `indent_left`, `indent_right`, `first_line` (negative: hanging), `keep_with_next`, `keep_together`, `page_break_before` |
| `page` | the front matter's keys (`_` or `-`): `paper` (A4, A3, A5, Letter, Legal), `orientation`, `margins` (1, 2 or 4 lengths; a bare number is mm), `margin-top`…, `header`, `footer` (Markdown, `{PAGE}`, `{PAGES}`; `""` removes), `header-align`, `footer-align`, `first-page-header`, `first-page-footer`, `background` (an image: `![](data:…)` or `image:<id>`), `background-fit` (`stretch`, `contain`), `numbering-start`, `numbering-style` (`decimal`, `lower-roman`, `upper-roman`, `lower-letter`, `upper-letter`) |
| `styles` | `normal`, `title`, `heading1` … `heading6`: `{font, size, bold, italic, color: "#1F4E79", space_before, space_after}` |
| `template` | `name`: a built-in template (their names: `/api/templates`, read with GET) |

Lengths: `pt` (or a bare number), `mm`, `cm`, `in`. **Rights**: an image or a paragraph needs `edit` on its part;
the page, styles and template need, for an agent, the `document` scope (`agentLayoutScope` otherwise: ask the person
who registered you). Anything Word cannot write is refused with the reason, never approximated.
`GET` gives the **report** alone (a reading right): per page, the parts that start on it (`starts`), its images (`id`,
`place`, `x_mm`, `y_mm`, `width_mm`, `height_mm`, `width_pct`, `section`, `paragraph`, `story`), `filled` (0 to 1);
`paper`; and `alerts` `{kind, page, message, fix, hint}` — `image_too_big`, `image_far_from_paragraph`,
`heading_alone`, `blank_before_break`, `blank_before_image`, `table_too_wide`, `font_missing` — where `fix` is the
operation that corrects it, ready to send. **The loop**: translate the request into operations, apply them (or
`dry_run`), look at the pages, fix what looks wrong, then say what you did.

### `GET /api/docs/{doc}/docx`
The Word export, written into the original `.docx` when the document came from one. What could not be
written as it should is listed in the `X-Text-Warnings` header (URL-encoded, comma-separated).

### `PUT|DELETE /api/docs/{doc}/original`
The `.docx` the document was just opened from (`PUT`, body: the file), or forget it (`DELETE`).
Used by importers; you rarely need it.

## Sections

### `GET|PUT /api/docs/{doc}/sections/{id}`
`GET` returns one section: `{ id, level, title, parent, owner, effective_owner, markdown }` where
`markdown` is its body, without heading or sub-sections.

`GET …?context=outline|neighbors|all` returns the section **as a part**: its Markdown (heading, body,
sub-sections, annotated `<!-- section id=… -->`), its **path** (the enclosing headings, outermost first),
the **outline** of the document (each section marked `in_part` or not) and, with `neighbors`
(the default for `?context=`), the sections just before and after it under the same parent (cut at
4000 characters); `all` adds the whole document.

`PUT` writes it: `{"markdown": "…"}`. Without headings: its body only (sub-sections kept). With deeper
headings: its whole content (see `markdown.md`). Answers with the section as `GET` does; **403** with the
reason when you may not write it.
```sh
curl -sS -X PUT -H "$H" -H 'Content-Type: application/json' \
  -d '{"markdown":"New body."}' "$D/sections/12"
```

### `PUT /api/docs/{doc}/sections/{id}/owner`
`{"owner": "agent:x" | "Name" | null}` assigns a section. Refused (403) unless your rights allow it;
an agent normally cannot give itself sections.

### `PUT /api/docs/{doc}/sections/{id}/rights`
`{"others": "read"|"comment"|"edit", "people": {"name": "read"|"comment"|"edit"}}`, or `null` to clear.
Who may do what in a section. For people.

### `POST /api/docs/{doc}/append`
`{"markdown": "…", "section"?: 12, "key"?: "…"}`: adds the Markdown's blocks **at the end of the document**, or at the
end of section 12 (after its sub-sections, before the next heading of the same level or higher), **without rewriting
anything**: the way to add a line to a note, an entry to a journal, a task to a list. `key` is yours (the date and a
word, say): a call made again with the same key within 7 days writes nothing and answers the same, with
`appended: false` (retry safely after a network error). Same rules as `PUT …/sections/{id}`: needs `edit`, inside
your sections if you are bounded to some, refused while you are paused. Answers `{"section": 12 | null, "appended":
true | false}`; 400 (nothing to add, a bad key, headings not deeper than the section), 403 (where you may not write),
404 (document or section unknown).
```sh
curl -sS -X POST -H "$H" -H 'Content-Type: application/json' \
  -d '{"markdown":"- call Paul about the budget","key":"2026-10-17 paul"}' "$D/append"
```

## Comments and requests

### `GET|POST /api/docs/{doc}/comments`
`GET` lists every comment. A thread's first comment has `anchor` (the passage and where it is now),
`resolved`, and for requests: `agent` (the agent it is addressed to, without `agent:`), `validate`,
`approved`, `stopped`, `title`. Replies have `parent`. Each has `author`, `at` (ms), `text`, `deleted`.
A **card's comment** (Paginel Board) has `card`, the card's section id, and no `anchor`: it follows the card when it moves.
In a board, a card's comments are **follow-up traces** (no thread, no resolution; only their author changes or deletes
them): they are listed here, and shown read-only at the end of the card in the board's Markdown (above).

`POST` creates a comment (201, `{"id": "…"}`), in one of these shapes:

| Body | What it does |
|---|---|
| `{"text", "parent": "<thread id>"}` | a reply |
| `{"text", "quote": "exact words", "section": 12}` | a new thread on the first occurrence of `quote` (in section 12 if given) |
| `{"text", "section": 12}` | a thread on the section's heading |
| `{"text", "from": 120, "to": 140}` | a thread on a range of characters |
| `{"text", "card": 12}` | a comment on the **card** of section 12 (a board: `###` card); it stays with the card when it moves; not a request, no `parent` |

Adding `"agent": "name"` makes it a **request** to that agent; `"validate": true` makes it wait for its
author to validate the zone. As an agent you normally reply and comment; requests are made by people.

### `PUT|DELETE /api/docs/{doc}/comments/{id}`
`PUT {"text"?, "resolved"?}` edits your own comment's text, or resolves (`true`) or reopens (`false`) a
thread. A request stopped by its owner stays over. `DELETE` removes **your own** comment (its replies stay).

## History

### `GET /api/docs/{doc}/history`
`{ "versions": [ { id, previous, start, end, authors, messages, changes, operations } ], "current": "<id>" }`,
oldest first. `start` and `end` are seconds since 1970. `messages` say what agents and imports did.

### `GET /api/docs/{doc}/history/compare`
`?from=<version id>&to=<version id>` (`to` left out: now): what changed between two versions.

### `GET /api/docs/{doc}/history/markdown`
`?version=<id>`: that version as Markdown.

### `POST /api/docs/{doc}/history/restore`
`{"version": "<id>"}` brings that version's content back (checked like any change: refused where you may
not write). **Usually a person's call.**

### `GET /api/docs/{doc}/authors`
`?from=<char>&to=<char>` (default: all): who wrote those characters, and when.

## Agents and people

### `GET /api/docs/{doc}/agents`
`{"agents": {"<name>": { owner, prompt, prompt_revision, active, excluded, last_action, scope }}, "activity": {…}}`:
for each agent its responsible person, its instructions, whether it may work (`active`, `excluded`), its
`scope` (`sections`, or `document`; absent means `sections`) and the recent activity. For your own entry,
prefer `GET …/instructions`; `prompt_revision` grows each time your instructions change.

### `PUT|DELETE /api/docs/{doc}/agents/{name}`
Create or change an agent (`{"prompt"?, "active"?, "excluded"?, "scope"?}`), or remove it. Any person can
pause (`active: false`) or exclude an agent; only its owner changes the prompt or scope. **Not for you to
call on yourself.**

### `GET /api/docs/{doc}/presence`
Who is connected right now, and the agents' activity.

### `GET /api/docs/{doc}/people`
Who is around the document: people connected, who wrote, who owns or is named in the rights of a section,
the agents (owner, scope, status, last request) and the sections.

## Images and fonts

### `GET|PUT /api/docs/{doc}/images/{id}`
The bytes of an image of the document (`GET`), or upload one under an id (`PUT`, body: the file).
Reading is enough for most work: images appear in Markdown as `image:<id>`.

### `GET|DELETE /api/docs/{doc}/images/unused`
`GET`: the images of the document that nothing cites any more (text, headers and footers, notes, page backgrounds, comments), with what
they weigh: `{"images": [{"id", "bytes", "width", "height", "mime"}], "bytes"}`. `DELETE` erases their bytes for good (the history and
undo then show a missing image): **people's call**, a token is refused (403).

### `GET|PUT /api/docs/{doc}/fonts`
`GET`: the fonts the document brings, `{"fonts": [...], "refused": [...]}`. `PUT` imports a face
(`?rights=1` confirms the person has the right to share it; body: the file). **People's call.**

### `GET|DELETE /api/docs/{doc}/fonts/{id}`
A face's file, or removal of an imported face.

## Your instructions and small corrections

### `GET /api/docs/{doc}/instructions`
Your instructions for this document, as the caller (`agent:<name>` of your token; on a local server, the
`?user=agent:<name>` you give). Needs `read` (a `comment` or `read` token may call it). **Read it first, and
again from time to time**: nothing is pushed to you; when `prompt_revision` grows, your owner changed your
prompt or scope.
```json
{ "agent": "agent:redacteur", "registered": true, "owner": "Marie", "prompt": "…",
  "prompt_revision": 3, "active": true, "excluded": false, "scope": "sections",
  "may_work": true, "writable_sections": [3, 7],
  "requests": [ { "id": "…", "text": "…", "quote": "…", "validate": true, "approved": null } ] }
```
`registered: false` means no person has registered you in this document yet (you may only read and
comment). `may_work` is false when you are paused or excluded. `writable_sections` are the ids you may
write (the sections entrusted to you and their sub-sections, or, with scope `document`, wherever your owner may
write). `requests` are the open requests addressed to you; `validate: true` with `approved: null` means the
zone is not validated yet (see `rules.md`).
```sh
curl -sS -H "$H" "$D/instructions"
```

### `POST /api/docs/{doc}/edit`
`{"old_text": "…", "new_text": "…", "section"?: 12}`: replaces **one exact passage**. `old_text` must appear
**exactly once** (in section 12 and its sub-sections if `section` is given, else in the document), inside a
single paragraph; `new_text` is plain text on one line and takes the formatting of the passage. Allowed where you may
write, and inside the passage of an open request addressed to you (validated first if it asks for it; never
after it is resolved or stopped). Needs the `edit` right of a token. Answers with the modified section, as
`PUT …/sections/{id}` does. **403** when you may not write there, 404 for an unknown section, **400** when
`old_text` is missing or appears several times (the message says which).
```sh
curl -sS -X POST -H "$H" -H 'Content-Type: application/json' \
  -d '{"old_text":"grew by 30%","new_text":"grew by 40%"}' "$D/edit"
```

## Notes and folders

A token's right may be a **folder**: it opens the documents that are in that folder **at the time of each call** (one
moved out is no longer open). **Folders nest** (five levels at most) and **what is given on a folder holds for everything
inside it**, now and later: the documents in its sub-folders, the sub-folders made or moved in afterwards; a right on a
child folder is not seen from its parent. `edit` on a folder also lets you **create** documents and **folders** in it and
**rename** documents; deleting and moving documents and folders stay with people. These routes show only what your token opens; with a person's
session, everything of the account. Dates are UTC, `2026-10-17T08:30:00Z`.

### `GET /api/agent/me`
**In which account do you write?** A person may have several Paginel accounts under the same address (a work account and a
personal one, made by two ways of signing in), and your token belongs to one of them: the documents you make are in that
one, and a link to them opens a request for access in the other. → `{"account": {"name", "email_masked", "ways":
[{"kind", "provider", "organization", "label"}], "organization"}, "agent": {"name", "connector", "via"}, "visible":
{"documents", "folders"}, "say"}`. `email_masked` is the address with its start hidden (`ma***@example.org`) and **never
whole**; `ways[].kind` is `microsoft_work`, `microsoft_personal`, `google`, `github`, `organization`, `email` or
`password`; `organization: true` when an organization holds one of those sign-ins (a work or school account); `visible`
counts what your token opens; `say` is a sentence you can pass on. **Call it** when your user asks where you wrote, when a
link you gave does not open for them, and before you create documents when it is not clear which account is meant: tell
them the account's name and kind. It needs no right.

### `GET|PUT /api/agent/favorites`
**Start here** when your user names a usual document ("my shopping list", "the to-do"): the folders, boards and
documents they marked as **favorites**, those your token opens, in the order they were marked.
`GET [?text=1]` → `{"favorites": [{"type": "folder", "id", "name", "rights", "agent", "url", "documents": [...]},
{"type": "document", "id", "title", "kind", "folder_id", "updated", "rights", "favorite", "url"}]}`: a folder comes
with the documents of it you see (`rights: null` when only some of its documents are open to you); a document as
`/api/agent/documents` gives it. With `text=1`, each favorite document also has its `markdown` (sections marked as in
`GET /api/docs/{doc}`; `null` when it could not be read now) and `complete` is `false` when not all could be read in
time.

`PUT {"document_id" | "folder_id", "favorite": true|false}` → `{"type", "id", "favorite"}`: marks or unmarks one,
**only when your user asks** (favorites are their own list). Needs `edit` on it (403 `favorite.refused`); one of the
two ids (400 `favorite.target`); 100 favorites at most (409 `favorite.quota`). The mark carries your name.

### `GET|POST /api/agent/folders`
`GET [?limit=&cursor=]` → `{"all": false, "all_rights": null, "folders": [{"id", "name", "rights", "documents", "agent", "favorite", "encrypted",
"accessible", "parent_id", "depth", "path", "subfolders"}], "total", "next"}`: the folders your token opens **at every level, in one flat
list**, your rights in each and how many documents it holds **directly**; `total` counts them all. With `limit` (500 at most), a page:
`next` is the cursor of the following page (give it as `cursor`), `null` at the end; without `limit`, the whole list; `all: true` (and its `all_rights`) when a right
opens all the account's documents. Each folder says where it is: `parent_id` (the folder it is in, `null` at the top of what
your token opens: a token whose right is on a folder sees that folder as the top), `depth` (1 at the top), `path` (the folders
above it that you see, from the top down to its parent: `[{"id", "name"}]`) and `subfolders` (those you see directly below
it). **A right on a folder is your right in the folders below it** (so a token with `edit` on « Projects » may create in
« Projects/Budget »). **A folder with `encrypted: true, accessible: false`
is end-to-end encrypted** (the root of an encrypted subtree: its `name` is neutral, `rights` and `documents` are `null`, `parent_id`
is the folder it is in): Paginel cannot read it, so
neither can you, no grant opens it and « all documents » leaves it out; it is listed (to you, if your token opens all the
documents or the folder it is in) only so that you can tell your user it exists. Every call on it or on what it holds is refused, said: 403
`e2e.agent_refused`. `agent: true` marks the folder of the **agent mode**, if its owner turned it
on: it holds the notes **Inbox** (one line per idea, unsorted), **Projets** / Projects (a project per heading: status,
next action) and **Tâches** / Tasks (`- [ ] …` boxes). `favorite: true`: one of the person's favorites.

`POST {"name", "parent_id"?}` → `201 {"id", "name", "parent_id", "depth", "rights": "edit", "path"}`: a new folder **inside
`parent_id`**, a folder you may `edit` (it is the rights you have there that you have in the new one), or at the top of the list when
`parent_id` is left out and you may `edit` all documents (403 `agent.folder_required`; 403 `agent.create_refused` below `edit`; 404
`folder.unknown`; 403 `e2e.agent_refused` for an encrypted parent). At most **five levels deep** (409 `folder.too_deep`),
**500 sub-folders** in one folder (409 `folder.children_quota`) and **5 000 folders** in an account (409 `folder.quota`); the name is
80 characters at most (400 `folder.name_invalid`). Deleting, renaming and moving folders stay with people.

### `GET|POST /api/agent/documents`
`GET ?folder=<id>&limit=&cursor=` (all optional): `{"documents": [{"id", "title", "kind", "folder_id", "folder_name", "updated",
"rights", "favorite", "url"}], "total", "next"}`, the most recently changed first; `kind` is `text` or `board` (a board of Paginel
Board: level-2 headings are its columns, level-3 its cards); `folder_name` is the name of its folder (`null` outside any, and for a folder your token does not open: a document
given to you alone does not tell you its folder's name).
`total` counts them all. With `limit` (200 at most), a page: `next` is the cursor of the following page (give it as `cursor`;
400 `agent.cursor_invalid` for anything else), `null` at the end; a document changed meanwhile may move from one page to
another. Without `limit`, the whole list.

`POST {"title", "folder_id"?, "kind"?, "template"?, "markdown"?}` → `201 {"id", "title", "kind", "folder_id", "url",
"updated", "rights", "content"}`: a new document in a folder you may `edit` (`folder_id` may be left out only with `edit`
on all documents: 403 `agent.folder_required`), within its owner's plan (`409 quota.personal`, `quota.bytes`). `kind`:
`text` (default) or `board` (a kanban board: `##` columns, `###` cards; without `markdown` it gets three empty columns
in the account's language; 400 `document.kind_unknown` otherwise). `template`: `note`, `inbox`, `projects` or `tasks`
(in the account's language); `markdown`: its first content, written under your name (after the template's). You are registered in it for the whole document. `content`: `none`, `written`, or
`error` with `content_error` (the document exists: write it with its id, do not create it again).

### `PUT /api/agent/documents/{id}/title`
`{"title": "…"}` → `{"id", "title"}`. Needs `edit`. Links `[[Old title]]` in other documents are **not** updated.

### `GET|POST /api/agent/files`
A **file** is anything a person stored that is not a text of Paginel: a PDF, an image, a spreadsheet, an archive. It has
**no text and no editor**: it is listed apart (never in `/api/agent/documents`), it is **downloaded**, and the document routes
refuse it (`GET /api/docs/{id}` → 400 `file.not_openable`; reading, writing or renaming it through
`/api/agent/…` → 400 `file.no_text`, « Fichier sans texte »). It is shared for **reading only**, whatever your token's right.

`GET ?folder=<id>` (optional) → `{"files": [{"id", "name", "kind": "file", "size", "mime", "folder_id", "updated",
"rights": "read", "url"}]}`, the most recently changed first: the files your token opens (all the documents, the folder
they are in **now**, or the file itself); `size` in bytes, `mime` from the extension only, `url` downloads it. A folder
you do not see: 404 `folder.unknown`.

`POST ?name=<file name>[&folder=<id>]`, the **raw bytes as the body** (`Content-Type: application/octet-stream`) → `201 {"id", "kind", "name", "size", "mime", "folder_id", "created", "url"}`:
a new file in a folder you may `edit` (`folder` may be left out only with `edit` on all documents: 403 `agent.folder_required`,
403 `agent.create_refused` below `edit`, 404 `folder.unknown`), as for creating a document. **25 MB at most**, checked while
the body is read (413 `file.too_big`), within the owner's plan (507 `quota.bytes_upload`; a file takes bytes, no place of
documents); three uploads at once per account (429 `file.parallel`), 60 files per ten minutes (429 `file.rate`,
`Retry-After`), 1 000 files per account (409 `file.count`). The name is cleaned (no `/`, no control or direction-changing
character, 255 bytes at most, no `CON`/`NUL`…: 400 `file.name`); one already taken in the folder gets « (2) ». **`.md`, `.markdown`
and `.txt` become a document** (`"kind": "text"`, `url` opens it): UTF-8 or UTF-16 with a byte order mark, 5 MB at most (413
`file.text_too_big`, 400 `file.encoding` for another coding), the original kept. Everything is sealed on the server's disk.
```sh
curl -sS -X POST -H "$H" -H 'Content-Type: application/octet-stream' --data-binary @report.pdf \
  "$PAGINEL_URL/api/agent/files?name=report.pdf&folder=$FOLDER"
```

**To attach a file to a card of a board**: `POST ?name=<file name>&board=<board id>&card=<card's section id>` (no `folder`), the raw bytes
as the body. You need `edit` on the board (403 `attachment.rights`; 400 `attachment.not_a_board`, `attachment.card` without a card,
`attachment.card_unknown` for a section that is not a card of it: all checked before a byte is read). The file is **never imported as
a document**, whatever its name; it is kept in the account's **`uploadedFiles`** folder (made at the root the first time), counted in
its plan, with the limits above; then a paragraph `[name](attachment:<id>)` is added at the end of the card, signed with your name
(if that fails, nothing is kept). **The same content again** (a live file of the account with the same bytes) is not stored twice: the
card gets the file the account has (`"deduplicated": true`, its id, its name). → `201 {"id", "kind": "file", "name", "size", "mime",
"folder_id", "created", "board", "card", "deduplicated", "url", "download", "linked": true}`: `url` is the file's page (`<PAGINEL_URL>/f/<id>`), `download` its bytes. Everyone who reads the board
downloads it (not by the board's link open to anyone).
```sh
curl -sS -X POST -H "$H" -H 'Content-Type: application/octet-stream' --data-binary @draft.pdf \
  "$PAGINEL_URL/api/agent/files?name=draft.pdf&board=$BOARD&card=12"
```

### `GET /api/boards/{board}/attachments`
The files attached to the cards of a board you read, the first attached first: `[{"id", "name", "size", "mime", "card", "added_by",
"created", "gone", "url", "download", "open"}]` (`open`: the address that shows it in a browser, `null` for a type that is only
downloaded); `gone: true`: the file is at the trash (an erased one is no longer listed, its link stays in
the card). 404 `document.unknown` for a board your token does not open, 400 `attachment.not_a_board`. Download one with
`GET /api/agent/files/{id}/content` (a board you read opens its attachments, whoever sent them).

### `DELETE /api/boards/{board}/attachments/{file}`
`?card=<section>` (optional: without it, every card of the board that holds it). For each card, **the link is taken out of the card**
(by the board itself: a card entrusted to another, or outside the section your token is bounded to, is refused there, 403), then the
board no longer holds the file (nor opens it to its readers): 204. **The file stays** in the `uploadedFiles` folder of who sent it.
Needs `edit` on the board (403 `attachment.rights`); 404 `attachment.unknown` for a file it (or that card) does not hold. To take the
link out of a card and keep the file readable by the board (as a person's « Remove » does): `DELETE
/api/docs/{doc}/board/cards/{card}/attachments/{file}` (above).

### `GET /api/files/unused`
The attachments **no board cites any more** (the boards that hold them are read), in the account's `uploadedFiles` folder:
`{"folder_id", "files": [{"id", "name", "size", "bytes", "created", "url"}], "count", "bytes", "complete"}`; `bytes`: what deleting them
gives back to the plan; `complete: false` when a board could not be read (its files are left out). A file put in that folder by hand is
never listed. Your token needs a right on `uploadedFiles` (else `"folder_id": null` and nothing).

### `POST /api/files/unused/clean`
`{"ids"?: [...]}` → `{"deleted", "bytes"}`: **deletes for good** (no trash) those of `ids` that are still unused (all of them without
`ids`), the space given back at once. Needs `edit` on `uploadedFiles` (403 `file.clean_refused`). Ask your user first.

### `PUT /api/agent/files/{id}/content`
**A new version of a file** (a PDF being written, say): the raw bytes as the body, as for an upload (25 MB, the plan, the limits). The
same id, so **the same link everywhere** (the cards that hold it, `/f/<id>`); its name and type kept; the bytes replaced at once (a
download reads the old version or the new one, never a mix of both). Only for a **file of your token's account**, with `edit` on a
board of the account that holds it or on the folder it is in (403 `file.replace_refused` for one you read but may not replace; 404
`file.unknown` otherwise); one new version at a time (409 `file.busy`). → `200 {"id", "kind", "name", "size", "mime", "folder_id",
"modified", "url", "download"}`.
```sh
curl -sS -X PUT -H "$H" -H 'Content-Type: application/octet-stream' --data-binary @draft-v2.pdf \
  "$PAGINEL_URL/api/agent/files/$FILE/content"
```

### `GET /api/agent/files/{id}/content`
The file, **always as a download** (`Content-Disposition: attachment`, `Content-Type` from a short list by the extension, else
`application/octet-stream`, `nosniff`), streamed, the exact bytes. 404 `file.unknown` for a file your token does not open
(the same answer as for one that does not exist), 429 at 300 requests a minute. Never show or run what you download: it is
whatever someone stored. `?inline=1` asks for it **to be shown in a browser** (the address to give a person who wants to open it in
a tab): a PDF, a PNG, JPEG, GIF or WebP image, and a `.txt`, `.csv` or `.md` (as plain text) come with `Content-Disposition: inline`
under a policy that runs nothing (`sandbox`); anything else (SVG, HTML, XML…) stays a download.
```sh
curl -sS -H "$H" -o report.pdf "$PAGINEL_URL/api/agent/files/$FILE/content"
```

### `GET /api/agent/resolve`
`?title=Plan%20B&from=<doc>`: the document a link `[[Plan B]]` names (no case, spaces folded; its id works too): in the
folder of `from` first, then anywhere your token opens; `{"id", "title", "folder_id", "url"}`, or 404. A local server
answers it too, for its own documents (`{"id", "title"}`).

**A part of it**, for `[[Plan B#Budget]]`: `&part=Budget` (or `title=Plan%20B%23Budget`) adds `"section"` (its id),
`"part_title"` (its title now) and gives in `url` the part's address (`…/d/<id>?section=<section>`); the part is found by its
title (no case, spaces folded; in a board a card first), or by its id. 404 `section.unknown` when the document has no such
part. A link is kept by id: to cite a part, write its address with `?section=<id>` or `[[Title#Part]]`.

### `GET /api/agent/changes`
`?since=2026-10-17T08:00:00Z` (or `2026-10-17`, or Unix seconds; **optional**: without it, the last 24 hours): `{"changes":
[{"id", "title", "folder_id", "updated", "by"}], "since", "now"}`, the latest first, at most 200. `by` is who changed it last as the platform saw
it: `agent:<name>` or a person's id for a change made through this API, the people who had the document open for a
change made in the editor; it may be `null`. Keep `now` for your next call.

### `GET /api/docs/{doc}/backlinks`
The documents that cite this one: `[[Its title]]`, `[[Its title|text]]`, a link to `wiki:<title>`, or its address
`/d/<id>`: `[{"id", "title", "excerpt", "url"}]`. On a platform: among the documents your token opens, the 40 most
recently changed at most (header `Paginel-Complete: false` when not all could be read). A local server answers it for
its own documents. Needs `read` on `{doc}`.

On a platform, each document also says its `kind` (`text` or `board`) and **`links`**, one per place that cites it (30 at
most): `{"from", "to", "excerpt"}`. `from` is where the link is: in a board, **the card** (`{"card": 12, "title"}`, its
comments included), elsewhere the section (`{"section": 4, "title"}`); `to` is what it aims at in `{doc}`: the section of
the address (`…/d/<id>?section=7`, `#section=7`, `&section=7`) or the card of **`[[Board title#Card title]]`** (`{"card": 7,
"title"}`; `{"title", "found": false}` when the board has no card of that title); both absent for the whole document.
`?card=7` (or `?section=7`, the same): only the links to that card (or section) of `{doc}`. To cite a card of another board,
or a part of another document, write one of these two forms.

### `GET /api/docs/{doc}/outline`
The parts of `{doc}` to link to, in the order of the text: `[{"section", "level", "title"}]` (`[]` for a document never
written). Needs `read`.

### `GET /api/docs/{doc}/preview`
What a link to `{doc}` shows: `{"id", "title", "kind", "excerpt", "present", "updated", "updated_by", "url"}`; with
`?section=<id>`, the part: `"section"`, `"part_title"`, its excerpt and its address (404 `section.unknown` for a part it does
not have). `title` is the title now; `excerpt` the first lines as plain text (300 characters at most); `present` who has it
open in the editor now (their ids in the document); `updated` and `updated_by` its last change, as `changes` says it. Needs
`read`: a document your token does not open is 404, as one that does not exist, and nothing of it is said.

## Local server

`text-server` (the one you start yourself) has no account and no token. The routes above are the same, at `http://localhost:8787`
(or the address you are given). Name yourself with `?user=agent:<name>` on every call that changes something. The server also has
routes for people and tools (`/api/docs` lists the documents, `/api/trash`, `/ws/{doc}` is the editors' WebSocket); they are not
part of an agent's work.

**The desktop app's own server** (Paginel Text on this computer, after its user clicked « Brancher un agent… ») listens on
`127.0.0.1` at the address you are given, and asks for a token on every call, the files of this skill included:
`Authorization: Bearer <token>`. That token was made for **one document** (its id, `fichier-…` for a file of the computer, is given
with it and lives as long as the app runs). With it:

- the routes of that document, the skill's files (`/agent/SKILL.md`, `/agent/references/…`) and the list `/api/docs`, which holds that
  document only (its id and the name its user knows it by) are open; everything else answers 403: any other document, the
  WebSocket, the wastebasket, deleting or renaming the document;
- you are `agent:<name>` on **every** call, reads included (`?user=agent:<name>`); a person's name is refused (403);
- `401` means the user cut your access, or the app closed: stop, tell them, do not look for another way in;
- never read or write the document's file on the disk: what you write goes through the document, with its history and its undo, signed
  with your name, and reaches the file when the user saves.

## Not available to a token

On the platform, everything else under `/api/` needs a person's session: accounts, renaming, moving, deleting or
sharing folders (making one is `POST /api/agent/folders`), moving and deleting documents, invitations, access requests, the agent mode, and creating tokens
(`/api/me/tokens`). You get a refusal; ask your user.
