{
  "components": {
    "securitySchemes": {
      "bearerAuth": {
        "description": "A personal API token, `pgn_…`: made in Paginel (« Agents et API », or « Brancher un agent » in a document).",
        "scheme": "bearer",
        "type": "http"
      }
    }
  },
  "info": {
    "description": "What an agent calls to work on a document hosted on Paginel. Send your personal API token as `Authorization: Bearer pgn_…` (never in an address, a document or a comment). The token opens nothing until its owner gave it a right (a document, a section, a folder or all documents, `read`, `comment` or `edit`). You write only where a person let you: the document itself enforces it. Same text as the skill, `references/api.md`.",
    "title": "Paginel: the REST API of the agents",
    "version": "1"
  },
  "openapi": "3.1.0",
  "paths": {
    "/api/agent/changes": {
      "get": {
        "description": "`{changes: [{id, title, folder_id, updated, by}], since, now}`, the latest first, at most 200. Without `since`, the last 24 hours. Keep `now` for your next call.",
        "operationId": "listChanges",
        "parameters": [
          {
            "description": "`2026-10-17T08:00:00Z`, `2026-10-17` or Unix seconds (optional: the last 24 hours).",
            "in": "query",
            "name": "since",
            "required": false,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "additionalProperties": true,
                  "type": "object"
                }
              }
            },
            "description": "The changes."
          },
          "400": {
            "description": "A date it does not read (`agent.date_invalid`)."
          },
          "401": {
            "description": "No token, or a wrong, revoked or expired one."
          },
          "429": {
            "description": "Too many requests for this token (300 a minute): wait `Retry-After` seconds."
          }
        },
        "summary": "Documents changed since a date, or in the last 24 hours"
      }
    },
    "/api/agent/documents": {
      "get": {
        "description": "`{documents: [{id, title, kind, folder_id, folder_name, updated, rights, favorite, url}], total, next}`, the most recently changed first; `folder_name` is null outside any folder and for a folder the token does not open. `total` counts them all; with `limit`, a page, and `next` is the cursor of the following one (`null` at the end); without `limit`, the whole list.",
        "operationId": "listDocuments",
        "parameters": [
          {
            "description": "A folder's id: its documents only.",
            "in": "query",
            "name": "folder",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "How many documents in this page (200 at most). Without it, all of them.",
            "in": "query",
            "name": "limit",
            "required": false,
            "schema": {
              "type": "integer"
            }
          },
          {
            "description": "`next` of the answer before: the following page.",
            "in": "query",
            "name": "cursor",
            "required": false,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "additionalProperties": true,
                  "type": "object"
                }
              }
            },
            "description": "The documents."
          },
          "400": {
            "description": "A cursor that is not one (`agent.cursor_invalid`)."
          },
          "401": {
            "description": "No token, or a wrong, revoked or expired one."
          },
          "404": {
            "description": "A folder your token does not open."
          },
          "429": {
            "description": "Too many requests for this token (300 a minute): wait `Retry-After` seconds."
          }
        },
        "summary": "The documents your token opens"
      },
      "post": {
        "description": "In a folder your token opens with `edit` (`folder_id` may be left out only with `edit` on all documents), within the owner's plan. `template`: `note`, `inbox`, `projects` or `tasks`. `markdown` is written under your name. `kind`: `text` (default) or `board` (Paginel Board: `##` columns, `###` cards); a board without `markdown` gets three empty columns in the account's language. `content`: `none`, `written`, or `error` with `content_error` (the document exists: do not create it again).",
        "operationId": "createDocument",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "properties": {
                  "folder_id": {
                    "type": "string"
                  },
                  "kind": {
                    "enum": [
                      "text",
                      "board"
                    ],
                    "type": "string"
                  },
                  "markdown": {
                    "type": "string"
                  },
                  "template": {
                    "enum": [
                      "note",
                      "inbox",
                      "projects",
                      "tasks"
                    ],
                    "type": "string"
                  },
                  "title": {
                    "type": "string"
                  }
                },
                "required": [
                  "title"
                ],
                "type": "object"
              }
            }
          },
          "required": true
        },
        "responses": {
          "201": {
            "content": {
              "application/json": {
                "schema": {
                  "additionalProperties": true,
                  "type": "object"
                }
              }
            },
            "description": "`{id, title, kind, folder_id, url, updated, rights, content}`."
          },
          "400": {
            "description": "No title, an unknown template, or an unknown kind (`document.kind_unknown`)."
          },
          "401": {
            "description": "No token, or a wrong, revoked or expired one."
          },
          "403": {
            "description": "Not `edit` on that folder (`agent.create_refused`), or no folder given (`agent.folder_required`)."
          },
          "404": {
            "description": "A folder your token does not open."
          },
          "409": {
            "description": "The owner's free plan is full (`quota.personal`, `quota.bytes`)."
          },
          "429": {
            "description": "Too many requests for this token (300 a minute): wait `Retry-After` seconds."
          }
        },
        "summary": "Create a document in a folder"
      }
    },
    "/api/agent/documents/{id}/title": {
      "put": {
        "description": "Needs `edit`. Links `[[Old title]]` elsewhere are not updated.",
        "operationId": "renameDocument",
        "parameters": [
          {
            "description": "The document's id.",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "properties": {
                  "title": {
                    "type": "string"
                  }
                },
                "required": [
                  "title"
                ],
                "type": "object"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "additionalProperties": true,
                  "type": "object"
                }
              }
            },
            "description": "`{id, title}`."
          },
          "401": {
            "description": "No token, or a wrong, revoked or expired one."
          },
          "403": {
            "description": "Not `edit` on it."
          },
          "404": {
            "description": "Unknown document, or not open to your token."
          },
          "429": {
            "description": "Too many requests for this token (300 a minute): wait `Retry-After` seconds."
          }
        },
        "summary": "Rename a document"
      }
    },
    "/api/agent/favorites": {
      "get": {
        "description": "Start here when your user names a usual document. `{favorites: [{type: \"folder\", id, name, rights, agent, url, documents: [...]}, {type: \"document\", id, title, kind, folder_id, updated, rights, favorite, url}]}`, in the order they were marked. With `text=1`, each favorite document has its `markdown` (`null` when it could not be read now), and `complete`.",
        "operationId": "listFavorites",
        "parameters": [
          {
            "description": "`1`: also the Markdown of each favorite document.",
            "in": "query",
            "name": "text",
            "required": false,
            "schema": {
              "enum": [
                "1",
                "true"
              ],
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "additionalProperties": true,
                  "type": "object"
                }
              }
            },
            "description": "The favorites."
          },
          "401": {
            "description": "No token, or a wrong, revoked or expired one."
          },
          "429": {
            "description": "Too many requests for this token (300 a minute): wait `Retry-After` seconds."
          }
        },
        "summary": "The person's favorites your token opens"
      },
      "put": {
        "description": "Only when your user asks. One of `document_id`, `folder_id`; needs `edit` on it; the mark carries your name.",
        "operationId": "setFavorite",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "properties": {
                  "document_id": {
                    "description": "A document or board: its id or its address.",
                    "type": "string"
                  },
                  "favorite": {
                    "type": "boolean"
                  },
                  "folder_id": {
                    "type": "string"
                  }
                },
                "required": [
                  "favorite"
                ],
                "type": "object"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "additionalProperties": true,
                  "type": "object"
                }
              }
            },
            "description": "`{type, id, favorite}`."
          },
          "400": {
            "description": "Neither or both of `document_id` and `folder_id` (`favorite.target`)."
          },
          "401": {
            "description": "No token, or a wrong, revoked or expired one."
          },
          "403": {
            "description": "Not `edit` on it (`favorite.refused`)."
          },
          "404": {
            "description": "Unknown document or folder, or not open to your token."
          },
          "409": {
            "description": "100 favorites already (`favorite.quota`)."
          },
          "429": {
            "description": "Too many requests for this token (300 a minute): wait `Retry-After` seconds."
          }
        },
        "summary": "Mark or unmark a favorite"
      }
    },
    "/api/agent/files": {
      "get": {
        "description": "A file is anything a person stored that is not a text of Paginel (a PDF, an image…): no text, no editor, shared for reading only. `{files: [{id, name, kind: \"file\", size, mime, folder_id, updated, rights: \"read\", url}]}`, the most recently changed first; `url` downloads it. Never in `listDocuments`.",
        "operationId": "listFiles",
        "parameters": [
          {
            "description": "A folder's id: its files only.",
            "in": "query",
            "name": "folder",
            "required": false,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "additionalProperties": true,
                  "type": "object"
                }
              }
            },
            "description": "The files."
          },
          "401": {
            "description": "No token, or a wrong, revoked or expired one."
          },
          "404": {
            "description": "A folder your token does not open."
          },
          "429": {
            "description": "Too many requests for this token (300 a minute): wait `Retry-After` seconds."
          }
        },
        "summary": "The files your token opens"
      },
      "post": {
        "description": "The raw bytes are the body. In a folder your token opens with `edit` (`folder` may be left out only with `edit` on all documents). 25 MB at most, checked while the body is read; within the owner's plan (a file takes bytes, no place of documents). The name is cleaned (no `/`, no control or direction-changing character, 255 bytes at most, no reserved name: `file.name`); a name already taken in the folder gets « (2) ». `.md`, `.markdown` and `.txt` become a document (`kind: text`, UTF-8 or UTF-16 with a byte order mark, 5 MB at most, the original kept). Everything is sealed on the server's disk. **With `board` and `card`**: the file is attached to that card of a board you may `edit` (never imported as a document, whatever its name): it is kept in the account's `uploadedFiles` folder (made at the root the first time) and a link `[name](attachment:<id>)` is added at the end of the card, signed with your name; the answer adds `board`, `card`, `download` and `url` is the file's page. 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`).",
        "operationId": "uploadFile",
        "parameters": [
          {
            "description": "The file's name, with its extension.",
            "in": "query",
            "name": "name",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "The folder's id.",
            "in": "query",
            "name": "folder",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "Attach the file to a card of this board (its id).",
            "in": "query",
            "name": "board",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "With `board`: the card's section id (a level-3 heading).",
            "in": "query",
            "name": "card",
            "required": false,
            "schema": {
              "type": "integer"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/octet-stream": {
              "schema": {
                "format": "binary",
                "type": "string"
              }
            }
          },
          "required": true
        },
        "responses": {
          "201": {
            "content": {
              "application/json": {
                "schema": {
                  "additionalProperties": true,
                  "type": "object"
                }
              }
            },
            "description": "`{id, kind, name, size, mime, folder_id, created, url}`: `kind` is `file` (`url` downloads it) or `text` (a document: `url` opens it)."
          },
          "400": {
            "description": "A name that will not do (`file.name`), a text in another coding (`file.encoding`), an upload cut off (`file.interrupted`). With `board`: not a board (`attachment.not_a_board`), no card (`attachment.card`), not a card of the board (`attachment.card_unknown`)."
          },
          "401": {
            "description": "No token, or a wrong, revoked or expired one."
          },
          "403": {
            "description": "Not `edit` on that folder (`agent.create_refused`), or no folder given (`agent.folder_required`). With `board`: not `edit` on the board (`attachment.rights`)."
          },
          "404": {
            "description": "A folder or a board your token does not open (`folder.unknown`, `document.unknown`)."
          },
          "409": {
            "description": "1 000 files already (`file.count`), or the owner's free plan has no room for a document (`quota.personal`)."
          },
          "413": {
            "description": "Over 25 MB (`file.too_big`), or a text over 5 MB (`file.text_too_big`)."
          },
          "429": {
            "description": "Three uploads already running (`file.parallel`), too many in a short time (`file.rate`), or too many requests for this token."
          },
          "503": {
            "description": "Files need the server's sealed storage (`file.unavailable`), or it is locked (`file.locked`)."
          },
          "507": {
            "description": "The owner's free plan is full (`quota.bytes_upload`)."
          }
        },
        "summary": "Send a file into a folder, or attach it to a card of a board"
      }
    },
    "/api/agent/files/{id}/content": {
      "get": {
        "description": "The exact bytes, always as a download: `Content-Disposition: attachment`, a `Content-Type` from a short list by the extension (else `application/octet-stream`), `nosniff`, `Content-Security-Policy: sandbox`, no cache; streamed. Never show or run what you download.",
        "operationId": "downloadFile",
        "parameters": [
          {
            "description": "The file's id.",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "`1`: shown in a browser when its type allows it (PDF, PNG, JPEG, GIF, WebP; `.txt`, `.csv`, `.md` as plain text), `Content-Disposition: inline` under a policy that runs nothing; any other type stays a download.",
            "in": "query",
            "name": "inline",
            "required": false,
            "schema": {
              "enum": [
                "1"
              ],
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/octet-stream": {
                "schema": {
                  "format": "binary",
                  "type": "string"
                }
              }
            },
            "description": "The file."
          },
          "401": {
            "description": "No token, or a wrong, revoked or expired one."
          },
          "404": {
            "description": "A file your token does not open (the same answer as for one that does not exist): `file.unknown`."
          },
          "429": {
            "description": "Too many requests for this token (300 a minute): wait `Retry-After` seconds."
          },
          "500": {
            "description": "The file is damaged on the server's disk (`file.damaged`)."
          },
          "503": {
            "description": "The sealed storage is locked (`file.locked`)."
          }
        },
        "summary": "Download a file"
      },
      "put": {
        "description": "The raw bytes of the new version are the body. The same id, so the same link everywhere (the attachments of the cards); its name and type kept; the bytes replaced at once (a download reads the old version or the new one, never a mix); the owner's plan counted again. 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. 25 MB at most, checked while the body is read.",
        "operationId": "replaceFile",
        "parameters": [
          {
            "description": "The file's id.",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/octet-stream": {
              "schema": {
                "format": "binary",
                "type": "string"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "additionalProperties": true,
                  "type": "object"
                }
              }
            },
            "description": "`{id, kind, name, size, mime, folder_id, modified, url, download}`."
          },
          "400": {
            "description": "An upload cut off (`file.interrupted`)."
          },
          "401": {
            "description": "No token, or a wrong, revoked or expired one."
          },
          "403": {
            "description": "A file you read but may not replace (`file.replace_refused`)."
          },
          "404": {
            "description": "A file your token does not open (`file.unknown`)."
          },
          "409": {
            "description": "A new version of this file is already being sent (`file.busy`)."
          },
          "413": {
            "description": "Over 25 MB (`file.too_big`)."
          },
          "429": {
            "description": "Three uploads already running (`file.parallel`), too many in a short time (`file.rate`), or too many requests for this token."
          },
          "503": {
            "description": "Files need the server's sealed storage (`file.unavailable`), or it is locked (`file.locked`)."
          },
          "507": {
            "description": "The owner's free plan is full (`quota.bytes_upload`)."
          }
        },
        "summary": "Send a new version of a file"
      }
    },
    "/api/agent/folders": {
      "get": {
        "description": "`{all, all_rights, folders: [{id, name, rights, documents, agent, favorite, encrypted, accessible, parent_id, depth, path, subfolders}], total, next}`. `total` counts them all; with `limit`, a page, and `next` is the cursor of the following one (`null` at the end); without `limit`, the whole list. **Folders nest** (five levels at most): the list is flat, every level, and each folder says its `parent_id` (`null` at the top of what your token opens), its `depth`, its `path` (the folders above it that you see, from the top down to its parent) and its `subfolders`; **what is given on a folder holds for everything inside it**, so a right on a folder is your right in the folders below it. `agent: true` marks the agent mode's folder (Inbox, Projects, Tasks). A folder with `encrypted: true, accessible: false` is end-to-end encrypted (the root of an encrypted subtree, with its `parent_id`): neither Paginel nor you can read it, no grant opens it, `all documents` leaves it out, and every call on it or inside it answers 403 `e2e.agent_refused`; it is listed only so that you can say it exists.",
        "operationId": "listFolders",
        "parameters": [
          {
            "description": "How many folders in this page (500 at most). Without it, all of them.",
            "in": "query",
            "name": "limit",
            "required": false,
            "schema": {
              "type": "integer"
            }
          },
          {
            "description": "`next` of the answer before: the following page.",
            "in": "query",
            "name": "cursor",
            "required": false,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "additionalProperties": true,
                  "type": "object"
                }
              }
            },
            "description": "The folders."
          },
          "400": {
            "description": "A cursor that is not one (`agent.cursor_invalid`)."
          },
          "401": {
            "description": "No token, or a wrong, revoked or expired one."
          },
          "429": {
            "description": "Too many requests for this token (300 a minute): wait `Retry-After` seconds."
          }
        },
        "summary": "The folders your token opens"
      },
      "post": {
        "description": "A folder inside `parent_id` (a folder your token opens with `edit`), or at the top of the list when `parent_id` is left out and the token has `edit` on all documents. Folders go five levels deep at most, 500 sub-folders in one folder, 5 000 folders in an account. **You have in the new folder the rights you have in its parent** (rights come down the tree). Deleting and moving folders stay with people.",
        "operationId": "createFolder",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "properties": {
                  "name": {
                    "type": "string"
                  },
                  "parent_id": {
                    "type": "string"
                  }
                },
                "required": [
                  "name"
                ],
                "type": "object"
              }
            }
          },
          "required": true
        },
        "responses": {
          "201": {
            "content": {
              "application/json": {
                "schema": {
                  "additionalProperties": true,
                  "type": "object"
                }
              }
            },
            "description": "`{id, name, parent_id, depth, rights, path}`."
          },
          "400": {
            "description": "No name, or a name that is not one (`folder.name_invalid`)."
          },
          "401": {
            "description": "No token, or a wrong, revoked or expired one."
          },
          "403": {
            "description": "Not `edit` on that folder (`agent.create_refused`), no parent given without `edit` on all documents (`agent.folder_required`), or an end-to-end encrypted parent (`e2e.agent_refused`)."
          },
          "404": {
            "description": "A folder your token does not open."
          },
          "409": {
            "description": "Too deep (`folder.too_deep`), too many sub-folders (`folder.children_quota`) or folders (`folder.quota`)."
          },
          "429": {
            "description": "Too many requests for this token (300 a minute): wait `Retry-After` seconds."
          }
        },
        "summary": "Create a folder inside a folder"
      }
    },
    "/api/agent/me": {
      "get": {
        "description": "`{account: {name, email_masked, ways, organization}, agent: {name, connector, via}, visible: {documents, folders}, say}`. **Call it when your user asks where you wrote**, when a link you gave does not open for them, or before you create documents without being told which account is meant: 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 a token belongs to one of them. `email_masked` is the address with its start hidden (`ma***@example.org`), never whole; `ways` says how one signs in to the account (`microsoft_work`, `microsoft_personal`, `google`, `github`, `organization`, `email`, `password`, each with an English `label`), `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. It needs no right.",
        "operationId": "whoami",
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "additionalProperties": true,
                  "type": "object"
                }
              }
            },
            "description": "The account and your own name."
          },
          "401": {
            "description": "No token, or a wrong, revoked or expired one."
          },
          "429": {
            "description": "Too many requests for this token (300 a minute): wait `Retry-After` seconds."
          }
        },
        "summary": "Which account you write in"
      }
    },
    "/api/agent/resolve": {
      "get": {
        "description": "By its title (no case, spaces folded) or its id: in the folder of `from` first, then anywhere your token opens. With `part` (or `title=Title%23Part`), the part of the document found: by its title (no case, spaces folded; in a board a card first) or its id.",
        "operationId": "resolveTitle",
        "parameters": [
          {
            "description": "The title inside the link.",
            "in": "query",
            "name": "title",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "The part inside the link, after `#`: its title (or its id).",
            "in": "query",
            "name": "part",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "The document the link is in.",
            "in": "query",
            "name": "from",
            "required": false,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "additionalProperties": true,
                  "type": "object"
                }
              }
            },
            "description": "`{id, title, folder_id, url}`; with a part, also `section` and `part_title`, and `url` is the part's address (`?section=`)."
          },
          "401": {
            "description": "No token, or a wrong, revoked or expired one."
          },
          "404": {
            "description": "No such document open to your token (`document.unknown`), or no such part in it (`section.unknown`)."
          },
          "429": {
            "description": "Too many requests for this token (300 a minute): wait `Retry-After` seconds."
          }
        },
        "summary": "The document a [[link]] names"
      }
    },
    "/api/boards/{board}/attachments": {
      "get": {
        "description": "Each file attached to a card of the board, the first attached first: `[{id, name, size, mime, card, added_by, created, gone, url, download}]`. `gone`: the file is at the trash (an erased one is no longer listed). Whoever reads the board reads its attachments (download them with `GET /api/agent/files/{id}/content`).",
        "operationId": "listAttachments",
        "parameters": [
          {
            "description": "The board's id.",
            "in": "path",
            "name": "board",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "items": {
                    "additionalProperties": true,
                    "type": "object"
                  },
                  "type": "array"
                }
              }
            },
            "description": "The list."
          },
          "400": {
            "description": "Not a board (`attachment.not_a_board`)."
          },
          "401": {
            "description": "No token, or a wrong, revoked or expired one."
          },
          "404": {
            "description": "A board your token does not open (`document.unknown`)."
          },
          "429": {
            "description": "Too many requests for this token (300 a minute): wait `Retry-After` seconds."
          }
        },
        "summary": "The attachments of a board"
      }
    },
    "/api/boards/{board}/attachments/{file}": {
      "delete": {
        "description": "For each card of the board that holds the file (`card`: that one only), 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), then the board no longer holds the file. The file itself stays in the `uploadedFiles` folder of who sent it. Needs `edit` on the board.",
        "operationId": "removeAttachment",
        "parameters": [
          {
            "description": "The board's id.",
            "in": "path",
            "name": "board",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "The file's id.",
            "in": "path",
            "name": "file",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "Only this card (its section id).",
            "in": "query",
            "name": "card",
            "required": false,
            "schema": {
              "type": "integer"
            }
          }
        ],
        "responses": {
          "204": {
            "description": "Removed."
          },
          "400": {
            "description": "Not a board (`attachment.not_a_board`)."
          },
          "401": {
            "description": "No token, or a wrong, revoked or expired one."
          },
          "403": {
            "description": "Not `edit` on the board (`attachment.rights`), or the board refused to take the link out of that card (`docserver.refused`)."
          },
          "404": {
            "description": "A board your token does not open (`document.unknown`), or a file it does not hold (`attachment.unknown`)."
          },
          "429": {
            "description": "Too many requests for this token (300 a minute): wait `Retry-After` seconds."
          }
        },
        "summary": "Remove an attachment from a board"
      }
    },
    "/api/docs/{doc}": {
      "delete": {
        "description": "Always refused with a token (403): it is for people, from « Mes documents ».",
        "operationId": "deleteDocument",
        "parameters": [
          {
            "description": "The document's id (the end of .../d/<id>).",
            "in": "path",
            "name": "doc",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Never for a token."
          },
          "403": {
            "description": "Refused: outside your part, a read-only section, you are paused or excluded, or the token's rights are too low. Read the `error` field."
          },
          "404": {
            "description": "Unknown document or section. A wrong, revoked or expired token also gives `Document inconnu.`"
          },
          "429": {
            "description": "Too many requests for this token (300 a minute): wait `Retry-After` seconds."
          }
        },
        "summary": "Put the document in the wastebasket (refused for a token)"
      },
      "get": {
        "description": "The sections (id, level, title, parent, owner, effective_owner) and the whole document as Markdown annotated with section ids.",
        "operationId": "getDocument",
        "parameters": [
          {
            "description": "The document's id (the end of .../d/<id>).",
            "in": "path",
            "name": "doc",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "additionalProperties": true,
                  "type": "object"
                }
              }
            },
            "description": "The document: `doc`, `title`, `sections`, `markdown`."
          },
          "403": {
            "description": "Refused: outside your part, a read-only section, you are paused or excluded, or the token's rights are too low. Read the `error` field."
          },
          "404": {
            "description": "Unknown document or section. A wrong, revoked or expired token also gives `Document inconnu.`"
          },
          "429": {
            "description": "Too many requests for this token (300 a minute): wait `Retry-After` seconds."
          }
        },
        "summary": "Read the outline and the content"
      }
    },
    "/api/docs/{doc}/agents": {
      "get": {
        "description": "For each: owner, prompt, `prompt_revision`, `active`, `excluded`, `last_action`, `scope`; and the recent activity. For your own entry prefer `getInstructions`.",
        "operationId": "listAgents",
        "parameters": [
          {
            "description": "The document's id (the end of .../d/<id>).",
            "in": "path",
            "name": "doc",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "additionalProperties": true,
                  "type": "object"
                }
              }
            },
            "description": "JSON object"
          },
          "403": {
            "description": "Refused: outside your part, a read-only section, you are paused or excluded, or the token's rights are too low. Read the `error` field."
          },
          "404": {
            "description": "Unknown document or section. A wrong, revoked or expired token also gives `Document inconnu.`"
          },
          "429": {
            "description": "Too many requests for this token (300 a minute): wait `Retry-After` seconds."
          }
        },
        "summary": "The agents of the document"
      }
    },
    "/api/docs/{doc}/agents/{name}": {
      "delete": {
        "operationId": "deleteAgent",
        "parameters": [
          {
            "description": "The document's id (the end of .../d/<id>).",
            "in": "path",
            "name": "doc",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "The agent's name (letters, digits, - and _).",
            "in": "path",
            "name": "name",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Removed."
          },
          "403": {
            "description": "Refused: outside your part, a read-only section, you are paused or excluded, or the token's rights are too low. Read the `error` field."
          },
          "404": {
            "description": "Unknown document or section. A wrong, revoked or expired token also gives `Document inconnu.`"
          },
          "429": {
            "description": "Too many requests for this token (300 a minute): wait `Retry-After` seconds."
          }
        },
        "summary": "Remove an agent (people)"
      },
      "put": {
        "description": "`{prompt?, active?, excluded?, scope?}`. Any person can pause or exclude; only the owner changes the prompt or scope.",
        "operationId": "putAgent",
        "parameters": [
          {
            "description": "The document's id (the end of .../d/<id>).",
            "in": "path",
            "name": "doc",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "The agent's name (letters, digits, - and _).",
            "in": "path",
            "name": "name",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "properties": {
                  "active": {
                    "type": "boolean"
                  },
                  "excluded": {
                    "type": "boolean"
                  },
                  "prompt": {
                    "type": "string"
                  },
                  "scope": {
                    "enum": [
                      "sections",
                      "document"
                    ],
                    "type": "string"
                  }
                },
                "required": [],
                "type": "object"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "additionalProperties": true,
                  "type": "object"
                }
              }
            },
            "description": "JSON object"
          },
          "403": {
            "description": "Refused: outside your part, a read-only section, you are paused or excluded, or the token's rights are too low. Read the `error` field."
          },
          "404": {
            "description": "Unknown document or section. A wrong, revoked or expired token also gives `Document inconnu.`"
          },
          "429": {
            "description": "Too many requests for this token (300 a minute): wait `Retry-After` seconds."
          }
        },
        "summary": "Create or change an agent (not for you to call on yourself)"
      }
    },
    "/api/docs/{doc}/append": {
      "post": {
        "description": "Adds the Markdown's blocks at the end of the document, or at the end of `section` (after its sub-sections). With `key`, a call made again with the same key within 7 days writes nothing and answers `appended: false`. Same rules as `putSection`. Needs `edit`.",
        "operationId": "appendToDocument",
        "parameters": [
          {
            "description": "The document's id (the end of .../d/<id>).",
            "in": "path",
            "name": "doc",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "properties": {
                  "key": {
                    "description": "Your own idempotency key (the date and a word).",
                    "type": "string"
                  },
                  "markdown": {
                    "type": "string"
                  },
                  "section": {
                    "type": "integer"
                  }
                },
                "required": [
                  "markdown"
                ],
                "type": "object"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "additionalProperties": true,
                  "type": "object"
                }
              }
            },
            "description": "`{section, appended}`."
          },
          "400": {
            "description": "Nothing to add, a bad key, or headings not deeper than the section."
          },
          "403": {
            "description": "Refused where you may not write (read the `error` field)."
          },
          "404": {
            "description": "Unknown document or section. A wrong, revoked or expired token also gives `Document inconnu.`"
          },
          "429": {
            "description": "Too many requests for this token (300 a minute): wait `Retry-After` seconds."
          }
        },
        "summary": "Add at the end, without rewriting"
      }
    },
    "/api/docs/{doc}/authors": {
      "get": {
        "operationId": "getAuthors",
        "parameters": [
          {
            "description": "The document's id (the end of .../d/<id>).",
            "in": "path",
            "name": "doc",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "First character.",
            "in": "query",
            "name": "from",
            "required": false,
            "schema": {
              "type": "integer"
            }
          },
          {
            "description": "End character.",
            "in": "query",
            "name": "to",
            "required": false,
            "schema": {
              "type": "integer"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "additionalProperties": true,
                  "type": "object"
                }
              }
            },
            "description": "JSON object"
          },
          "403": {
            "description": "Refused: outside your part, a read-only section, you are paused or excluded, or the token's rights are too low. Read the `error` field."
          },
          "404": {
            "description": "Unknown document or section. A wrong, revoked or expired token also gives `Document inconnu.`"
          },
          "429": {
            "description": "Too many requests for this token (300 a minute): wait `Retry-After` seconds."
          }
        },
        "summary": "Who wrote a range of characters, and when"
      }
    },
    "/api/docs/{doc}/backlinks": {
      "get": {
        "description": "Documents that cite it by `[[Its title]]`, `[[Its title#Card title]]` (`[[Its title#Part title]]`), a link to `wiki:<title>` or its address `/d/<id>` (with `?section=<id>` for a card or a section), among those your token opens (40 read at most: header `Paginel-Complete: false` when not all could be). Each one with its `links`: where the link is (`from`: the card, or the section) and what it aims at (`to`).",
        "operationId": "getBacklinks",
        "parameters": [
          {
            "description": "The document's id (the end of .../d/<id>).",
            "in": "path",
            "name": "doc",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "Only the links to this card (or section) of the document: its section id.",
            "in": "query",
            "name": "card",
            "required": false,
            "schema": {
              "type": "integer"
            }
          },
          {
            "description": "The same as `card`: only the links to this part of the document.",
            "in": "query",
            "name": "section",
            "required": false,
            "schema": {
              "type": "integer"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "items": {
                    "additionalProperties": true,
                    "type": "object"
                  },
                  "type": "array"
                }
              }
            },
            "description": "`[{id, title, kind, excerpt, url, links: [{from?, to?, excerpt}]}]`; `from` and `to` are `{card, title}` or `{section, title}` (`to` may be `{title, found: false}`)."
          },
          "404": {
            "description": "Unknown document, or not open to your token."
          },
          "429": {
            "description": "Too many requests for this token (300 a minute): wait `Retry-After` seconds."
          }
        },
        "summary": "The documents that cite this one"
      }
    },
    "/api/docs/{doc}/board": {
      "post": {
        "description": "Not for agents: the platform calls it itself, as the document's owner, when a board is created (and the first time an agent reads a board made before). A token is refused (403 `document.board_platform_only`). To make a board, create it with `kind: board` (`POST /api/agent/documents`).",
        "operationId": "postBoard",
        "parameters": [
          {
            "description": "The document's id (the end of .../d/<id>).",
            "in": "path",
            "name": "doc",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "properties": {
                  "columns": {
                    "items": {
                      "type": "string"
                    },
                    "type": "array"
                  }
                },
                "type": "object"
              }
            }
          },
          "required": false
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "additionalProperties": true,
                  "type": "object"
                }
              }
            },
            "description": "`{board: true, marked, seeded}`."
          },
          "403": {
            "description": "Always for a token: the platform does it (`document.board_platform_only`)."
          },
          "404": {
            "description": "Unknown document or section. A wrong, revoked or expired token also gives `Document inconnu.`"
          },
          "429": {
            "description": "Too many requests for this token (300 a minute): wait `Retry-After` seconds."
          }
        },
        "summary": "Make a document a board (the platform only)"
      }
    },
    "/api/docs/{doc}/board/cards/{card}": {
      "patch": {
        "description": "Changes the title and the metadata line of a card (`due: … · labels: … · done: yes`), in one step, without touching its text. An absent field stays; `due: null` and `labels: []` remove; `done: true` marks the card done, `false` not. Needs `edit`.",
        "operationId": "updateCard",
        "parameters": [
          {
            "description": "The document's id (the end of .../d/<id>).",
            "in": "path",
            "name": "doc",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "The card's section id.",
            "in": "path",
            "name": "card",
            "required": true,
            "schema": {
              "type": "integer"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "properties": {
                  "done": {
                    "description": "The card marked done (its box on the board).",
                    "type": "boolean"
                  },
                  "due": {
                    "description": "YYYY-MM-DD.",
                    "type": [
                      "string",
                      "null"
                    ]
                  },
                  "labels": {
                    "items": {
                      "type": "string"
                    },
                    "type": "array"
                  },
                  "title": {
                    "type": "string"
                  }
                },
                "required": [],
                "type": "object"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "additionalProperties": true,
                  "type": "object"
                }
              }
            },
            "description": "The card: `{section, column, title, due, labels, done, checks: {done, total}, …}`."
          },
          "400": {
            "description": "Not a board, or a section that is not a card (a column)."
          },
          "403": {
            "description": "Your token cannot change this board (`rights.read_only`), or the core refused (a section given to another, you paused)."
          },
          "404": {
            "description": "Unknown document, card or column. A wrong, revoked or expired token also gives `Document inconnu.`"
          },
          "429": {
            "description": "Too many requests for this token (300 a minute): wait `Retry-After` seconds."
          }
        },
        "summary": "Change a card's title, labels or due date"
      }
    },
    "/api/docs/{doc}/board/cards/{card}/attachments": {
      "post": {
        "description": "Writes the link of a file already on the platform at the end of the card: the paragraph `[name](attachment:<id>)`, one step of the history, signed with your name. To attach a new file, use `POST /api/agent/files?board=&card=`: it keeps the file and writes this link. Needs `edit`.",
        "operationId": "linkCardAttachment",
        "parameters": [
          {
            "description": "The document's id (the end of .../d/<id>).",
            "in": "path",
            "name": "doc",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "The card's section id.",
            "in": "path",
            "name": "card",
            "required": true,
            "schema": {
              "type": "integer"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "properties": {
                  "id": {
                    "type": "string"
                  },
                  "name": {
                    "type": "string"
                  }
                },
                "required": [
                  "id",
                  "name"
                ],
                "type": "object"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "additionalProperties": true,
                  "type": "object"
                }
              }
            },
            "description": "`{card, added, attachments}`: `added: false` if the card already links it."
          },
          "400": {
            "description": "Not a board, a section that is not a card, an id or a name that will not do."
          },
          "403": {
            "description": "Your token cannot change this board (`rights.read_only`), or the core refused (a section given to another, you paused)."
          },
          "404": {
            "description": "Unknown document or card. A wrong, revoked or expired token also gives `Document inconnu.`"
          },
          "429": {
            "description": "Too many requests for this token (300 a minute): wait `Retry-After` seconds."
          }
        },
        "summary": "Link a file to a card"
      }
    },
    "/api/docs/{doc}/board/cards/{card}/attachments/{file}": {
      "delete": {
        "description": "Removes the paragraph `[name](attachment:<file>)` from the card (the file itself stays). Needs `edit`.",
        "operationId": "unlinkCardAttachment",
        "parameters": [
          {
            "description": "The document's id (the end of .../d/<id>).",
            "in": "path",
            "name": "doc",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "The card's section id.",
            "in": "path",
            "name": "card",
            "required": true,
            "schema": {
              "type": "integer"
            }
          },
          {
            "description": "The file's id.",
            "in": "path",
            "name": "file",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "additionalProperties": true,
                  "type": "object"
                }
              }
            },
            "description": "`{card, removed}`: `removed: false` if the card did not link it."
          },
          "400": {
            "description": "Not a board, or a section that is not a card."
          },
          "403": {
            "description": "Your token cannot change this board (`rights.read_only`), or the core refused (a section given to another, you paused)."
          },
          "404": {
            "description": "Unknown document or card. A wrong, revoked or expired token also gives `Document inconnu.`"
          },
          "429": {
            "description": "Too many requests for this token (300 a minute): wait `Retry-After` seconds."
          }
        },
        "summary": "Remove a file's link from a card"
      }
    },
    "/api/docs/{doc}/board/cards/{card}/move": {
      "post": {
        "description": "Moves a card (a `###` section) to the end of a column, or before another card; it keeps its id, its text and its comments. Use it rather than rewriting the card elsewhere, which makes a new card. Needs `edit`.",
        "operationId": "moveCard",
        "parameters": [
          {
            "description": "The document's id (the end of .../d/<id>).",
            "in": "path",
            "name": "doc",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "The card's section id.",
            "in": "path",
            "name": "card",
            "required": true,
            "schema": {
              "type": "integer"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "properties": {
                  "before": {
                    "description": "The card it goes before.",
                    "type": "integer"
                  },
                  "column": {
                    "description": "The column's section id.",
                    "type": "integer"
                  }
                },
                "required": [
                  "column"
                ],
                "type": "object"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "additionalProperties": true,
                  "type": "object"
                }
              }
            },
            "description": "`{card, column}`."
          },
          "400": {
            "description": "Not a board, or a section that is not a card (a column)."
          },
          "403": {
            "description": "Your token cannot change this board (`rights.read_only`), or the core refused (a section given to another, you paused)."
          },
          "404": {
            "description": "Unknown document, card or column. A wrong, revoked or expired token also gives `Document inconnu.`"
          },
          "429": {
            "description": "Too many requests for this token (300 a minute): wait `Retry-After` seconds."
          }
        },
        "summary": "Move a card to a column"
      }
    },
    "/api/docs/{doc}/board/columns": {
      "post": {
        "description": "Adds a column (a `##` section) at the end of the board, or after another. Needs `edit`.",
        "operationId": "addColumn",
        "parameters": [
          {
            "description": "The document's id (the end of .../d/<id>).",
            "in": "path",
            "name": "doc",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "properties": {
                  "after": {
                    "description": "The column it goes after.",
                    "type": "integer"
                  },
                  "title": {
                    "type": "string"
                  }
                },
                "required": [
                  "title"
                ],
                "type": "object"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "additionalProperties": true,
                  "type": "object"
                }
              }
            },
            "description": "`{column}`: its section id."
          },
          "400": {
            "description": "Not a board, or a section that is not a card (a column)."
          },
          "403": {
            "description": "Your token cannot change this board (`rights.read_only`), or the core refused (a section given to another, you paused)."
          },
          "404": {
            "description": "Unknown document, card or column. A wrong, revoked or expired token also gives `Document inconnu.`"
          },
          "429": {
            "description": "Too many requests for this token (300 a minute): wait `Retry-After` seconds."
          }
        },
        "summary": "Add a column"
      }
    },
    "/api/docs/{doc}/board/columns/{column}": {
      "patch": {
        "description": "Renames a column. Needs `edit`.",
        "operationId": "renameColumn",
        "parameters": [
          {
            "description": "The document's id (the end of .../d/<id>).",
            "in": "path",
            "name": "doc",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "The column's section id.",
            "in": "path",
            "name": "column",
            "required": true,
            "schema": {
              "type": "integer"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "properties": {
                  "title": {
                    "type": "string"
                  }
                },
                "required": [
                  "title"
                ],
                "type": "object"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "additionalProperties": true,
                  "type": "object"
                }
              }
            },
            "description": "`{column, title}`."
          },
          "400": {
            "description": "Not a board, or a section that is not a card (a column)."
          },
          "403": {
            "description": "Your token cannot change this board (`rights.read_only`), or the core refused (a section given to another, you paused)."
          },
          "404": {
            "description": "Unknown document, card or column. A wrong, revoked or expired token also gives `Document inconnu.`"
          },
          "429": {
            "description": "Too many requests for this token (300 a minute): wait `Retry-After` seconds."
          }
        },
        "summary": "Rename a column"
      }
    },
    "/api/docs/{doc}/comments": {
      "get": {
        "description": "A thread's first comment has `anchor`, `resolved` and, for requests, `agent`, `validate`, `approved`, `stopped`, `title`; replies have `parent`; a card's comment (Paginel Board) has `card`, its section id, and no `anchor`. A card's comments are also shown read-only at the end of the card in the board's Markdown.",
        "operationId": "listComments",
        "parameters": [
          {
            "description": "The document's id (the end of .../d/<id>).",
            "in": "path",
            "name": "doc",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "additionalProperties": true,
                  "type": "object"
                }
              }
            },
            "description": "The comments."
          },
          "403": {
            "description": "Refused: outside your part, a read-only section, you are paused or excluded, or the token's rights are too low. Read the `error` field."
          },
          "404": {
            "description": "Unknown document or section. A wrong, revoked or expired token also gives `Document inconnu.`"
          },
          "429": {
            "description": "Too many requests for this token (300 a minute): wait `Retry-After` seconds."
          }
        },
        "summary": "List every comment and request"
      },
      "post": {
        "description": "Shapes: `{text, parent}` (a reply); `{text, quote, section?}`; `{text, section}`; `{text, from, to}`; `{text, card}` (a board card's comment, it follows the card). Needs `comment`.",
        "operationId": "createComment",
        "parameters": [
          {
            "description": "The document's id (the end of .../d/<id>).",
            "in": "path",
            "name": "doc",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "properties": {
                  "agent": {
                    "type": "string"
                  },
                  "card": {
                    "description": "A board card's section id: the comment is attached to the card (Paginel Board).",
                    "type": "integer"
                  },
                  "from": {
                    "type": "integer"
                  },
                  "parent": {
                    "type": "string"
                  },
                  "quote": {
                    "type": "string"
                  },
                  "section": {
                    "type": "integer"
                  },
                  "text": {
                    "type": "string"
                  },
                  "to": {
                    "type": "integer"
                  },
                  "validate": {
                    "type": "boolean"
                  }
                },
                "required": [
                  "text"
                ],
                "type": "object"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "properties": {
                    "id": {
                      "type": "string"
                    }
                  },
                  "type": "object"
                }
              }
            },
            "description": "Created: `{\"id\": \"…\"}`."
          },
          "403": {
            "description": "Refused: outside your part, a read-only section, you are paused or excluded, or the token's rights are too low. Read the `error` field."
          },
          "404": {
            "description": "Unknown document or section. A wrong, revoked or expired token also gives `Document inconnu.`"
          },
          "429": {
            "description": "Too many requests for this token (300 a minute): wait `Retry-After` seconds."
          }
        },
        "summary": "Reply, or comment a passage or a section"
      }
    },
    "/api/docs/{doc}/comments/{id}": {
      "delete": {
        "description": "Its replies stay.",
        "operationId": "deleteComment",
        "parameters": [
          {
            "description": "The document's id (the end of .../d/<id>).",
            "in": "path",
            "name": "doc",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "The comment's id.",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Removed."
          },
          "403": {
            "description": "Refused: outside your part, a read-only section, you are paused or excluded, or the token's rights are too low. Read the `error` field."
          },
          "404": {
            "description": "Unknown document or section. A wrong, revoked or expired token also gives `Document inconnu.`"
          },
          "429": {
            "description": "Too many requests for this token (300 a minute): wait `Retry-After` seconds."
          }
        },
        "summary": "Remove your own comment"
      },
      "put": {
        "description": "`{text?, resolved?}`.",
        "operationId": "updateComment",
        "parameters": [
          {
            "description": "The document's id (the end of .../d/<id>).",
            "in": "path",
            "name": "doc",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "The comment's id.",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "properties": {
                  "resolved": {
                    "type": "boolean"
                  },
                  "text": {
                    "type": "string"
                  }
                },
                "required": [],
                "type": "object"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "additionalProperties": true,
                  "type": "object"
                }
              }
            },
            "description": "JSON object"
          },
          "403": {
            "description": "Refused: outside your part, a read-only section, you are paused or excluded, or the token's rights are too low. Read the `error` field."
          },
          "404": {
            "description": "Unknown document or section. A wrong, revoked or expired token also gives `Document inconnu.`"
          },
          "429": {
            "description": "Too many requests for this token (300 a minute): wait `Retry-After` seconds."
          }
        },
        "summary": "Edit your comment, or resolve or reopen a thread"
      }
    },
    "/api/docs/{doc}/docx": {
      "get": {
        "description": "What could not be written is listed in the `X-Text-Warnings` header.",
        "operationId": "getDocx",
        "parameters": [
          {
            "description": "The document's id (the end of .../d/<id>).",
            "in": "path",
            "name": "doc",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/vnd.openxmlformats-officedocument.wordprocessingml.document": {
                "schema": {
                  "format": "binary",
                  "type": "string"
                }
              }
            },
            "description": "The .docx file."
          },
          "403": {
            "description": "Refused: outside your part, a read-only section, you are paused or excluded, or the token's rights are too low. Read the `error` field."
          },
          "404": {
            "description": "Unknown document or section. A wrong, revoked or expired token also gives `Document inconnu.`"
          },
          "429": {
            "description": "Too many requests for this token (300 a minute): wait `Retry-After` seconds."
          }
        },
        "summary": "The Word export"
      }
    },
    "/api/docs/{doc}/edit": {
      "post": {
        "description": "`old_text` must appear exactly once (in `section` and its sub-sections if given), inside one paragraph; `new_text` is plain text on one line and takes the passage's formatting. Needs `edit`.",
        "operationId": "editText",
        "parameters": [
          {
            "description": "The document's id (the end of .../d/<id>).",
            "in": "path",
            "name": "doc",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "properties": {
                  "new_text": {
                    "type": "string"
                  },
                  "old_text": {
                    "type": "string"
                  },
                  "section": {
                    "type": "integer"
                  }
                },
                "required": [
                  "old_text",
                  "new_text"
                ],
                "type": "object"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "additionalProperties": true,
                  "type": "object"
                }
              }
            },
            "description": "The modified section."
          },
          "403": {
            "description": "Refused: outside your part, a read-only section, you are paused or excluded, or the token's rights are too low. Read the `error` field."
          },
          "404": {
            "description": "Unknown document or section. A wrong, revoked or expired token also gives `Document inconnu.`"
          },
          "429": {
            "description": "Too many requests for this token (300 a minute): wait `Retry-After` seconds."
          }
        },
        "summary": "Replace one exact passage"
      }
    },
    "/api/docs/{doc}/fonts": {
      "get": {
        "description": "`{fonts: [...], refused: [...]}`.",
        "operationId": "listFonts",
        "parameters": [
          {
            "description": "The document's id (the end of .../d/<id>).",
            "in": "path",
            "name": "doc",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "additionalProperties": true,
                  "type": "object"
                }
              }
            },
            "description": "JSON object"
          },
          "403": {
            "description": "Refused: outside your part, a read-only section, you are paused or excluded, or the token's rights are too low. Read the `error` field."
          },
          "404": {
            "description": "Unknown document or section. A wrong, revoked or expired token also gives `Document inconnu.`"
          },
          "429": {
            "description": "Too many requests for this token (300 a minute): wait `Retry-After` seconds."
          }
        },
        "summary": "The fonts the document brings"
      },
      "put": {
        "description": "`?rights=1` confirms the person has the right to share it; body: the file.",
        "operationId": "putFont",
        "parameters": [
          {
            "description": "The document's id (the end of .../d/<id>).",
            "in": "path",
            "name": "doc",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "`1`.",
            "in": "query",
            "name": "rights",
            "required": false,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/octet-stream": {
              "schema": {
                "format": "binary",
                "type": "string"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "additionalProperties": true,
                  "type": "object"
                }
              }
            },
            "description": "JSON object"
          },
          "403": {
            "description": "Refused: outside your part, a read-only section, you are paused or excluded, or the token's rights are too low. Read the `error` field."
          },
          "404": {
            "description": "Unknown document or section. A wrong, revoked or expired token also gives `Document inconnu.`"
          },
          "429": {
            "description": "Too many requests for this token (300 a minute): wait `Retry-After` seconds."
          }
        },
        "summary": "Import a font face (people's call)"
      }
    },
    "/api/docs/{doc}/fonts/{id}": {
      "delete": {
        "operationId": "deleteFont",
        "parameters": [
          {
            "description": "The document's id (the end of .../d/<id>).",
            "in": "path",
            "name": "doc",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "The face's id.",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Removed."
          },
          "403": {
            "description": "Refused: outside your part, a read-only section, you are paused or excluded, or the token's rights are too low. Read the `error` field."
          },
          "404": {
            "description": "Unknown document or section. A wrong, revoked or expired token also gives `Document inconnu.`"
          },
          "429": {
            "description": "Too many requests for this token (300 a minute): wait `Retry-After` seconds."
          }
        },
        "summary": "Remove an imported face"
      },
      "get": {
        "operationId": "getFont",
        "parameters": [
          {
            "description": "The document's id (the end of .../d/<id>).",
            "in": "path",
            "name": "doc",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "The face's id.",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/octet-stream": {
                "schema": {
                  "format": "binary",
                  "type": "string"
                }
              }
            },
            "description": "The font file."
          },
          "403": {
            "description": "Refused: outside your part, a read-only section, you are paused or excluded, or the token's rights are too low. Read the `error` field."
          },
          "404": {
            "description": "Unknown document or section. A wrong, revoked or expired token also gives `Document inconnu.`"
          },
          "429": {
            "description": "Too many requests for this token (300 a minute): wait `Retry-After` seconds."
          }
        },
        "summary": "A face's file"
      }
    },
    "/api/docs/{doc}/history": {
      "get": {
        "description": "`{versions: [{id, previous, start, end, authors, messages, changes, operations}], current}`.",
        "operationId": "getHistory",
        "parameters": [
          {
            "description": "The document's id (the end of .../d/<id>).",
            "in": "path",
            "name": "doc",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "additionalProperties": true,
                  "type": "object"
                }
              }
            },
            "description": "The versions."
          },
          "403": {
            "description": "Refused: outside your part, a read-only section, you are paused or excluded, or the token's rights are too low. Read the `error` field."
          },
          "404": {
            "description": "Unknown document or section. A wrong, revoked or expired token also gives `Document inconnu.`"
          },
          "429": {
            "description": "Too many requests for this token (300 a minute): wait `Retry-After` seconds."
          }
        },
        "summary": "The versions, oldest first"
      }
    },
    "/api/docs/{doc}/history/compare": {
      "get": {
        "operationId": "compareVersions",
        "parameters": [
          {
            "description": "The document's id (the end of .../d/<id>).",
            "in": "path",
            "name": "doc",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "A version id.",
            "in": "query",
            "name": "from",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "A version id (left out: now).",
            "in": "query",
            "name": "to",
            "required": false,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "additionalProperties": true,
                  "type": "object"
                }
              }
            },
            "description": "JSON object"
          },
          "403": {
            "description": "Refused: outside your part, a read-only section, you are paused or excluded, or the token's rights are too low. Read the `error` field."
          },
          "404": {
            "description": "Unknown document or section. A wrong, revoked or expired token also gives `Document inconnu.`"
          },
          "429": {
            "description": "Too many requests for this token (300 a minute): wait `Retry-After` seconds."
          }
        },
        "summary": "What changed between two versions"
      }
    },
    "/api/docs/{doc}/history/markdown": {
      "get": {
        "operationId": "getVersionMarkdown",
        "parameters": [
          {
            "description": "The document's id (the end of .../d/<id>).",
            "in": "path",
            "name": "doc",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "A version id.",
            "in": "query",
            "name": "version",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "text/markdown": {
                "schema": {
                  "format": "binary",
                  "type": "string"
                }
              }
            },
            "description": "Markdown."
          },
          "403": {
            "description": "Refused: outside your part, a read-only section, you are paused or excluded, or the token's rights are too low. Read the `error` field."
          },
          "404": {
            "description": "Unknown document or section. A wrong, revoked or expired token also gives `Document inconnu.`"
          },
          "429": {
            "description": "Too many requests for this token (300 a minute): wait `Retry-After` seconds."
          }
        },
        "summary": "A version as Markdown"
      }
    },
    "/api/docs/{doc}/history/restore": {
      "post": {
        "description": "Checked like any change. Needs `edit`.",
        "operationId": "restoreVersion",
        "parameters": [
          {
            "description": "The document's id (the end of .../d/<id>).",
            "in": "path",
            "name": "doc",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "properties": {
                  "version": {
                    "type": "string"
                  }
                },
                "required": [
                  "version"
                ],
                "type": "object"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "additionalProperties": true,
                  "type": "object"
                }
              }
            },
            "description": "JSON object"
          },
          "403": {
            "description": "Refused: outside your part, a read-only section, you are paused or excluded, or the token's rights are too low. Read the `error` field."
          },
          "404": {
            "description": "Unknown document or section. A wrong, revoked or expired token also gives `Document inconnu.`"
          },
          "429": {
            "description": "Too many requests for this token (300 a minute): wait `Retry-After` seconds."
          }
        },
        "summary": "Bring a version back (usually a person's call)"
      }
    },
    "/api/docs/{doc}/images/unused": {
      "delete": {
        "description": "Erases for good the bytes of the images nothing cites any more (the history and undo then show a missing image). People's call: a token is refused.",
        "operationId": "eraseUnusedImages",
        "parameters": [
          {
            "description": "The document's id (the end of .../d/<id>).",
            "in": "path",
            "name": "doc",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "additionalProperties": true,
                  "type": "object"
                }
              }
            },
            "description": "`{deleted, bytes, kept}`."
          },
          "403": {
            "description": "A token (people's call), or not `edit` on the document."
          },
          "404": {
            "description": "Unknown document."
          }
        },
        "summary": "Erase the images nothing cites (people only)"
      },
      "get": {
        "description": "The images of the document that nothing cites any more (text, headers and footers, notes, page backgrounds, comments), with what they weigh.",
        "operationId": "listUnusedImages",
        "parameters": [
          {
            "description": "The document's id (the end of .../d/<id>).",
            "in": "path",
            "name": "doc",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "additionalProperties": true,
                  "type": "object"
                }
              }
            },
            "description": "`{images: [{id, bytes, width, height, mime}], bytes}`."
          },
          "404": {
            "description": "Unknown document. A wrong, revoked or expired token also gives `Document inconnu.`"
          },
          "429": {
            "description": "Too many requests for this token (300 a minute): wait `Retry-After` seconds."
          }
        },
        "summary": "The images nothing cites any more"
      }
    },
    "/api/docs/{doc}/images/{id}": {
      "get": {
        "description": "Images appear in Markdown as `image:<id>`.",
        "operationId": "getImage",
        "parameters": [
          {
            "description": "The document's id (the end of .../d/<id>).",
            "in": "path",
            "name": "doc",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "The image's id.",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/octet-stream": {
                "schema": {
                  "format": "binary",
                  "type": "string"
                }
              }
            },
            "description": "The image."
          },
          "403": {
            "description": "Refused: outside your part, a read-only section, you are paused or excluded, or the token's rights are too low. Read the `error` field."
          },
          "404": {
            "description": "Unknown document or section. A wrong, revoked or expired token also gives `Document inconnu.`"
          },
          "429": {
            "description": "Too many requests for this token (300 a minute): wait `Retry-After` seconds."
          }
        },
        "summary": "An image's bytes"
      },
      "put": {
        "description": "Body: the file.",
        "operationId": "putImage",
        "parameters": [
          {
            "description": "The document's id (the end of .../d/<id>).",
            "in": "path",
            "name": "doc",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "The image's id.",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/octet-stream": {
              "schema": {
                "format": "binary",
                "type": "string"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "additionalProperties": true,
                  "type": "object"
                }
              }
            },
            "description": "JSON object"
          },
          "403": {
            "description": "Refused: outside your part, a read-only section, you are paused or excluded, or the token's rights are too low. Read the `error` field."
          },
          "404": {
            "description": "Unknown document or section. A wrong, revoked or expired token also gives `Document inconnu.`"
          },
          "429": {
            "description": "Too many requests for this token (300 a minute): wait `Retry-After` seconds."
          }
        },
        "summary": "Upload an image under an id"
      }
    },
    "/api/docs/{doc}/instructions": {
      "get": {
        "description": "As the caller (`agent:<name>` of your token): who is responsible for you, `may_work`, `writable_sections`, the open `requests`, `prompt_revision`. Read it again from time to time. Needs `read`.",
        "operationId": "getInstructions",
        "parameters": [
          {
            "description": "The document's id (the end of .../d/<id>).",
            "in": "path",
            "name": "doc",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "additionalProperties": true,
                  "type": "object"
                }
              }
            },
            "description": "`{agent, registered, owner, prompt, prompt_revision, active, excluded, scope, may_work, writable_sections, requests}`."
          },
          "403": {
            "description": "Refused: outside your part, a read-only section, you are paused or excluded, or the token's rights are too low. Read the `error` field."
          },
          "404": {
            "description": "Unknown document or section. A wrong, revoked or expired token also gives `Document inconnu.`"
          },
          "429": {
            "description": "Too many requests for this token (300 a minute): wait `Retry-After` seconds."
          }
        },
        "summary": "Your instructions for this document (read it first)"
      }
    },
    "/api/docs/{doc}/layout": {
      "get": {
        "description": "Page by page: the parts that start on it (`starts`), its images (`id`, `place`: the placement words of the image title, `x_mm`, `y_mm`, `width_mm`, `height_mm`, `width_pct` of the text width, `section`, `paragraph`, `story`) and how much of the body is filled (`filled`, 0 to 1); `paper` (`name`, `width_mm`, `height_mm`, `margins_mm`); `alerts`, each `{kind, page, message, fix, hint}`: `fix` is the layout operation that corrects it, when there is one. Kinds: `image_too_big`, `image_far_from_paragraph`, `heading_alone`, `blank_before_break`, `blank_before_image`, `table_too_wide`, `font_missing`. Reading is enough.",
        "operationId": "getLayoutReport",
        "parameters": [
          {
            "description": "The document's id (the end of .../d/<id>).",
            "in": "path",
            "name": "doc",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            },
            "description": "`{pages, paper, list: [{n, starts, images, filled}], alerts}`"
          },
          "403": {
            "description": "Refused: outside your part, a read-only section, you are paused or excluded, or the token's rights are too low. Read the `error` field."
          },
          "404": {
            "description": "Unknown document. A wrong, revoked or expired token also gives `Document inconnu.`"
          },
          "429": {
            "description": "Too many requests for this token (300 a minute): wait `Retry-After` seconds."
          }
        },
        "summary": "The layout report"
      },
      "post": {
        "description": "Applies `ops` in order, **all or none**: the first one refused stops everything, nothing is written, and the answer says which (`op`, from 0, and `op_name`) and why (`error`, `code`). Otherwise one change, signed with your name, one step the person can undo. `dry_run: true` (or `?dry_run=1`; with a reading right only, `?dry_run=1` in the address: the body's alone is refused) applies them to a copy and gives its report; a refusal of the rights is then told in `refused`. `images`: `\"changed\"` (the first two pages touched) or up to two page numbers, returned as PNG in base64, `width` pixels wide (1000 by default). Operations: `image` (`image`: `image:<id>` or `{section, nth}`; `place`: the words of the image title, `right; width 40%`; or `width`, `height`, `wrap`, `gap`, `rotate`, `flip` alone; `to`: `{section?, text}`, the paragraph holding that exact passage), `insert_image` (`data`: a `data:` URI, or `url`; `to`; `place`), `paragraph` (`section?`, `text` or `all: true`; `align`, `space_before`, `space_after`, `line`, `indent_left`, `indent_right`, `first_line`, `keep_with_next`, `keep_together`, `page_break_before`), `page` (the front matter keys: `paper`, `orientation`, `margins`, `margin-top`…, `header`, `footer`, `header-align`, `footer-align`, `first-page-header`, `first-page-footer`, `background`, `background-fit`, `numbering-start`, `numbering-style`), `styles` (`normal`, `title`, `heading1`…`heading6`: `font`, `size`, `bold`, `italic`, `color`, `space_before`, `space_after`), `template` (`name`). Images and paragraphs need `edit` on their part; the page, styles and template, an agent working on the whole document (scope `document`).",
        "operationId": "applyLayout",
        "parameters": [
          {
            "description": "The document's id (the end of .../d/<id>).",
            "in": "path",
            "name": "doc",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "`1`: nothing is written (a reading right is enough).",
            "in": "query",
            "name": "dry_run",
            "required": false,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "properties": {
                  "dry_run": {
                    "type": "boolean"
                  },
                  "images": {
                    "oneOf": [
                      {
                        "enum": [
                          "changed"
                        ],
                        "type": "string"
                      },
                      {
                        "items": {
                          "minimum": 1,
                          "type": "integer"
                        },
                        "maxItems": 2,
                        "type": "array"
                      }
                    ]
                  },
                  "ops": {
                    "items": {
                      "additionalProperties": true,
                      "properties": {
                        "op": {
                          "enum": [
                            "image",
                            "insert_image",
                            "paragraph",
                            "page",
                            "styles",
                            "template"
                          ],
                          "type": "string"
                        }
                      },
                      "required": [
                        "op"
                      ],
                      "type": "object"
                    },
                    "maxItems": 50,
                    "minItems": 1,
                    "type": "array"
                  },
                  "width": {
                    "maximum": 2400,
                    "minimum": 200,
                    "type": "integer"
                  }
                },
                "required": [
                  "ops"
                ],
                "type": "object"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            },
            "description": "`{applied, dry_run, pages: [the pages touched], report: (as GET), images?: [{n, png}], refused?: {op, op_name, error, code}}`"
          },
          "400": {
            "description": "An operation not understood, a value out of bounds, or a setting Word cannot write: `error`, `code`, `op`, `op_name`. Nothing was written."
          },
          "403": {
            "description": "Refused by the rights (`agentLayoutScope`: the page, styles and template need the `document` scope; a locked part; paused or excluded). `op` says which operation. Nothing was written."
          },
          "404": {
            "description": "An image, a part, a passage or a template not found (`op` says which), or an unknown document."
          },
          "429": {
            "description": "Too many requests for this token (300 a minute): wait `Retry-After` seconds."
          }
        },
        "summary": "Lay out: place images, set paragraphs, the page, the styles, the template"
      }
    },
    "/api/docs/{doc}/markdown": {
      "get": {
        "description": "Images embedded as base64; `?images=reference` gives `image:<id>` references. In a board (Paginel Board) each card ends with its comments, read-only: a quote `> **Suivi** <!-- comments: read-only -->` then one line per comment; it is left out whenever Markdown is written back (here, sections, append): add a comment with `POST /api/docs/{doc}/comments` `{text, card}`.",
        "operationId": "getMarkdown",
        "parameters": [
          {
            "description": "The document's id (the end of .../d/<id>).",
            "in": "path",
            "name": "doc",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "`reference` for `image:<id>` references.",
            "in": "query",
            "name": "images",
            "required": false,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "text/markdown": {
                "schema": {
                  "format": "binary",
                  "type": "string"
                }
              }
            },
            "description": "Markdown."
          },
          "403": {
            "description": "Refused: outside your part, a read-only section, you are paused or excluded, or the token's rights are too low. Read the `error` field."
          },
          "404": {
            "description": "Unknown document or section. A wrong, revoked or expired token also gives `Document inconnu.`"
          },
          "429": {
            "description": "Too many requests for this token (300 a minute): wait `Retry-After` seconds."
          }
        },
        "summary": "The whole document as Markdown"
      },
      "put": {
        "description": "The body is raw Markdown, not JSON. Refused where you may not write. Needs `edit`. A board's comment blocks (`<!-- comments: read-only -->`) in it are left out: they never change a comment nor become text.",
        "operationId": "putMarkdown",
        "parameters": [
          {
            "description": "The document's id (the end of .../d/<id>).",
            "in": "path",
            "name": "doc",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "text/markdown": {
              "schema": {
                "type": "string"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "additionalProperties": true,
                  "type": "object"
                }
              }
            },
            "description": "The same JSON as `getDocument`."
          },
          "403": {
            "description": "Refused: outside your part, a read-only section, you are paused or excluded, or the token's rights are too low. Read the `error` field."
          },
          "404": {
            "description": "Unknown document or section. A wrong, revoked or expired token also gives `Document inconnu.`"
          },
          "429": {
            "description": "Too many requests for this token (300 a minute): wait `Retry-After` seconds."
          }
        },
        "summary": "Replace the whole document with Markdown"
      }
    },
    "/api/docs/{doc}/original": {
      "delete": {
        "description": "Rarely needed.",
        "operationId": "deleteOriginal",
        "parameters": [
          {
            "description": "The document's id (the end of .../d/<id>).",
            "in": "path",
            "name": "doc",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "additionalProperties": true,
                  "type": "object"
                }
              }
            },
            "description": "JSON object"
          },
          "403": {
            "description": "Refused: outside your part, a read-only section, you are paused or excluded, or the token's rights are too low. Read the `error` field."
          },
          "404": {
            "description": "Unknown document or section. A wrong, revoked or expired token also gives `Document inconnu.`"
          },
          "429": {
            "description": "Too many requests for this token (300 a minute): wait `Retry-After` seconds."
          }
        },
        "summary": "Forget the original .docx"
      },
      "put": {
        "description": "Body: the file. You rarely need it.",
        "operationId": "putOriginal",
        "parameters": [
          {
            "description": "The document's id (the end of .../d/<id>).",
            "in": "path",
            "name": "doc",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/octet-stream": {
              "schema": {
                "format": "binary",
                "type": "string"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "additionalProperties": true,
                  "type": "object"
                }
              }
            },
            "description": "JSON object"
          },
          "403": {
            "description": "Refused: outside your part, a read-only section, you are paused or excluded, or the token's rights are too low. Read the `error` field."
          },
          "404": {
            "description": "Unknown document or section. A wrong, revoked or expired token also gives `Document inconnu.`"
          },
          "429": {
            "description": "Too many requests for this token (300 a minute): wait `Retry-After` seconds."
          }
        },
        "summary": "Keep the .docx the document came from (importers)"
      }
    },
    "/api/docs/{doc}/outline": {
      "get": {
        "description": "Its sections in the order of the text, for a link to one of them (`?section=<id>` of its address, or `[[Title#Part]]`). Needs `read`.",
        "operationId": "getOutline",
        "parameters": [
          {
            "description": "The document's id (the end of .../d/<id>).",
            "in": "path",
            "name": "doc",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "items": {
                    "additionalProperties": true,
                    "type": "object"
                  },
                  "type": "array"
                }
              }
            },
            "description": "`[{section, level, title}]` (`[]` for a document never written)."
          },
          "404": {
            "description": "Unknown document, or not open to your token: nothing of it is said."
          },
          "429": {
            "description": "Too many requests for this token (300 a minute): wait `Retry-After` seconds."
          }
        },
        "summary": "The parts of a document to link to"
      }
    },
    "/api/docs/{doc}/pages": {
      "get": {
        "description": "The number of pages, the paper, and for each page the parts whose text is on it (`starts`: its heading is on this page) and the images drawn on it, their box in millimetres from the page's top left corner, `floating` when anchored, `story`: `body`, `header`, `footer` or `footnote`. The same layout as the PDF.",
        "operationId": "getPages",
        "parameters": [
          {
            "description": "The document's id (the end of .../d/<id>).",
            "in": "path",
            "name": "doc",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            },
            "description": "`{pages, paper: {width_mm, height_mm}, list: [{n, width_mm, height_mm, sections: [{id, title, starts}], images: [{id, x_mm, y_mm, width_mm, height_mm, floating, story}]}]}`"
          },
          "403": {
            "description": "Refused: outside your part, a read-only section, you are paused or excluded, or the token's rights are too low. Read the `error` field."
          },
          "404": {
            "description": "Unknown document. A wrong, revoked or expired token also gives `Document inconnu.`"
          },
          "429": {
            "description": "Too many requests for this token (300 a minute): wait `Retry-After` seconds."
          }
        },
        "summary": "What each page carries"
      }
    },
    "/api/docs/{doc}/pages/{file}": {
      "get": {
        "description": "`file` is the page number from 1 followed by `.png` (`/pages/1.png`). Drawn from the same layout as the PDF: look at it to check where images, text and page breaks fall. The `X-Text-Pages` header gives the number of pages.",
        "operationId": "getPageImage",
        "parameters": [
          {
            "description": "The document's id (the end of .../d/<id>).",
            "in": "path",
            "name": "doc",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "`<n>.png`, `n` from 1.",
            "in": "path",
            "name": "file",
            "required": true,
            "schema": {
              "pattern": "^[1-9][0-9]*\\.png$",
              "type": "string"
            }
          },
          {
            "description": "Width in pixels: 1200 by default, held between 200 and 2400.",
            "in": "query",
            "name": "width",
            "required": false,
            "schema": {
              "maximum": 2400,
              "minimum": 200,
              "type": "integer"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "image/png": {
                "schema": {
                  "format": "binary",
                  "type": "string"
                }
              }
            },
            "description": "The page."
          },
          "400": {
            "description": "`width` is not a number (`code`: `pageWidthInvalid`)."
          },
          "403": {
            "description": "Refused: outside your part, a read-only section, you are paused or excluded, or the token's rights are too low. Read the `error` field."
          },
          "404": {
            "description": "Unknown document, a page the document does not have (`pageNotFound`, with the number of pages) or a file that is not `<n>.png` (`pageNumberInvalid`)."
          },
          "429": {
            "description": "Too many requests for this token (300 a minute): wait `Retry-After` seconds."
          }
        },
        "summary": "A page as an image (PNG)"
      }
    },
    "/api/docs/{doc}/pdf": {
      "get": {
        "description": "`?pdfa=1|2a|2b` asks for PDF/A (the level reached is in `X-Text-Pdfa`; 422 if it cannot be reached).",
        "operationId": "getPdf",
        "parameters": [
          {
            "description": "The document's id (the end of .../d/<id>).",
            "in": "path",
            "name": "doc",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "`1`, `2a` or `2b`.",
            "in": "query",
            "name": "pdfa",
            "required": false,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/pdf": {
                "schema": {
                  "format": "binary",
                  "type": "string"
                }
              }
            },
            "description": "The PDF."
          },
          "403": {
            "description": "Refused: outside your part, a read-only section, you are paused or excluded, or the token's rights are too low. Read the `error` field."
          },
          "404": {
            "description": "Unknown document or section. A wrong, revoked or expired token also gives `Document inconnu.`"
          },
          "429": {
            "description": "Too many requests for this token (300 a minute): wait `Retry-After` seconds."
          }
        },
        "summary": "The paginated PDF"
      }
    },
    "/api/docs/{doc}/people": {
      "get": {
        "description": "People connected, who wrote, who owns a section, the agents and the sections.",
        "operationId": "getPeople",
        "parameters": [
          {
            "description": "The document's id (the end of .../d/<id>).",
            "in": "path",
            "name": "doc",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "additionalProperties": true,
                  "type": "object"
                }
              }
            },
            "description": "JSON object"
          },
          "403": {
            "description": "Refused: outside your part, a read-only section, you are paused or excluded, or the token's rights are too low. Read the `error` field."
          },
          "404": {
            "description": "Unknown document or section. A wrong, revoked or expired token also gives `Document inconnu.`"
          },
          "429": {
            "description": "Too many requests for this token (300 a minute): wait `Retry-After` seconds."
          }
        },
        "summary": "Who is around the document"
      }
    },
    "/api/docs/{doc}/presence": {
      "get": {
        "operationId": "getPresence",
        "parameters": [
          {
            "description": "The document's id (the end of .../d/<id>).",
            "in": "path",
            "name": "doc",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "additionalProperties": true,
                  "type": "object"
                }
              }
            },
            "description": "JSON object"
          },
          "403": {
            "description": "Refused: outside your part, a read-only section, you are paused or excluded, or the token's rights are too low. Read the `error` field."
          },
          "404": {
            "description": "Unknown document or section. A wrong, revoked or expired token also gives `Document inconnu.`"
          },
          "429": {
            "description": "Too many requests for this token (300 a minute): wait `Retry-After` seconds."
          }
        },
        "summary": "Who is connected now"
      }
    },
    "/api/docs/{doc}/preview": {
      "get": {
        "description": "Its title now, the first lines as plain text (300 characters at most), who has it open in the editor now, its last change. Needs `read`.",
        "operationId": "getPreview",
        "parameters": [
          {
            "description": "The document's id (the end of .../d/<id>).",
            "in": "path",
            "name": "doc",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "A part of the document: its section id.",
            "in": "query",
            "name": "section",
            "required": false,
            "schema": {
              "type": "integer"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "additionalProperties": true,
                  "type": "object"
                }
              }
            },
            "description": "`{id, title, kind, excerpt, present, updated, updated_by, url}`; with `section`, also `section` and `part_title` (404 `section.unknown` for a part it does not have)."
          },
          "404": {
            "description": "Unknown document, or not open to your token: nothing of it is said."
          },
          "429": {
            "description": "Too many requests for this token (300 a minute): wait `Retry-After` seconds."
          }
        },
        "summary": "What a link to a document shows"
      }
    },
    "/api/docs/{doc}/sections/{id}": {
      "get": {
        "description": "`{ id, level, title, parent, owner, effective_owner, markdown }`. With `context` the section is returned as a part: its Markdown, its path, the outline and, with `neighbors`, the sections around it.",
        "operationId": "getSection",
        "parameters": [
          {
            "description": "The document's id (the end of .../d/<id>).",
            "in": "path",
            "name": "doc",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "The section's id.",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "`outline`, `neighbors` or `all`.",
            "in": "query",
            "name": "context",
            "required": false,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "additionalProperties": true,
                  "type": "object"
                }
              }
            },
            "description": "The section."
          },
          "403": {
            "description": "Refused: outside your part, a read-only section, you are paused or excluded, or the token's rights are too low. Read the `error` field."
          },
          "404": {
            "description": "Unknown document or section. A wrong, revoked or expired token also gives `Document inconnu.`"
          },
          "429": {
            "description": "Too many requests for this token (300 a minute): wait `Retry-After` seconds."
          }
        },
        "summary": "Read one section"
      },
      "put": {
        "description": "Without headings: its body only (sub-sections kept). With deeper headings: its whole content. 403 with the reason when you may not write it. Needs `edit`.",
        "operationId": "putSection",
        "parameters": [
          {
            "description": "The document's id (the end of .../d/<id>).",
            "in": "path",
            "name": "doc",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "The section's id.",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "properties": {
                  "markdown": {
                    "type": "string"
                  }
                },
                "required": [
                  "markdown"
                ],
                "type": "object"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "additionalProperties": true,
                  "type": "object"
                }
              }
            },
            "description": "The section, as `getSection`."
          },
          "403": {
            "description": "Refused: outside your part, a read-only section, you are paused or excluded, or the token's rights are too low. Read the `error` field."
          },
          "404": {
            "description": "Unknown document or section. A wrong, revoked or expired token also gives `Document inconnu.`"
          },
          "429": {
            "description": "Too many requests for this token (300 a minute): wait `Retry-After` seconds."
          }
        },
        "summary": "Write a section"
      }
    },
    "/api/docs/{doc}/sections/{id}/owner": {
      "put": {
        "description": "`owner`: `agent:<name>`, a person's name, or null. Refused unless your rights allow it; an agent normally cannot give itself sections.",
        "operationId": "putSectionOwner",
        "parameters": [
          {
            "description": "The document's id (the end of .../d/<id>).",
            "in": "path",
            "name": "doc",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "The section's id.",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "properties": {
                  "owner": {
                    "type": [
                      "string",
                      "null"
                    ]
                  }
                },
                "required": [
                  "owner"
                ],
                "type": "object"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "additionalProperties": true,
                  "type": "object"
                }
              }
            },
            "description": "JSON object"
          },
          "403": {
            "description": "Refused: outside your part, a read-only section, you are paused or excluded, or the token's rights are too low. Read the `error` field."
          },
          "404": {
            "description": "Unknown document or section. A wrong, revoked or expired token also gives `Document inconnu.`"
          },
          "429": {
            "description": "Too many requests for this token (300 a minute): wait `Retry-After` seconds."
          }
        },
        "summary": "Assign a section (people)"
      }
    },
    "/api/docs/{doc}/sections/{id}/rights": {
      "put": {
        "description": "`{\"others\": \"read|comment|edit\", \"people\": {\"name\": \"…\"}}`, or null to clear.",
        "operationId": "putSectionRights",
        "parameters": [
          {
            "description": "The document's id (the end of .../d/<id>).",
            "in": "path",
            "name": "doc",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "The section's id.",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "properties": {
                  "others": {
                    "enum": [
                      "read",
                      "comment",
                      "edit"
                    ],
                    "type": "string"
                  },
                  "people": {
                    "additionalProperties": {
                      "enum": [
                        "read",
                        "comment",
                        "edit"
                      ],
                      "type": "string"
                    },
                    "type": "object"
                  }
                },
                "type": [
                  "object",
                  "null"
                ]
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "additionalProperties": true,
                  "type": "object"
                }
              }
            },
            "description": "JSON object"
          },
          "403": {
            "description": "Refused: outside your part, a read-only section, you are paused or excluded, or the token's rights are too low. Read the `error` field."
          },
          "404": {
            "description": "Unknown document or section. A wrong, revoked or expired token also gives `Document inconnu.`"
          },
          "429": {
            "description": "Too many requests for this token (300 a minute): wait `Retry-After` seconds."
          }
        },
        "summary": "Set who may do what in a section (people)"
      }
    },
    "/api/docs/{doc}/title": {
      "put": {
        "description": "A token is refused on a platform.",
        "operationId": "putTitle",
        "parameters": [
          {
            "description": "The document's id (the end of .../d/<id>).",
            "in": "path",
            "name": "doc",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "properties": {
                  "title": {
                    "type": [
                      "string",
                      "null"
                    ]
                  }
                },
                "required": [
                  "title"
                ],
                "type": "object"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "additionalProperties": true,
                  "type": "object"
                }
              }
            },
            "description": "JSON object"
          },
          "403": {
            "description": "Refused: outside your part, a read-only section, you are paused or excluded, or the token's rights are too low. Read the `error` field."
          },
          "404": {
            "description": "Unknown document or section. A wrong, revoked or expired token also gives `Document inconnu.`"
          },
          "429": {
            "description": "Too many requests for this token (300 a minute): wait `Retry-After` seconds."
          }
        },
        "summary": "Rename the document (people only)"
      }
    },
    "/api/files/unused": {
      "get": {
        "description": "In the account's `uploadedFiles` folder, the files attached to cards that no board cites any more (the boards that hold them are read). `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. Needs a right on `uploadedFiles` (else nothing).",
        "operationId": "listUnusedAttachments",
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "additionalProperties": true,
                  "type": "object"
                }
              }
            },
            "description": "`{folder_id, files: [{id, name, size, bytes, created, url}], count, bytes, complete}`."
          },
          "401": {
            "description": "No token, or a wrong, revoked or expired one."
          },
          "429": {
            "description": "Too many requests for this token (300 a minute): wait `Retry-After` seconds."
          }
        },
        "summary": "The attachments no board cites any more"
      }
    },
    "/api/files/unused/clean": {
      "post": {
        "description": "Deletes for good (no trash) those of `ids` that are still unused (all of them without `ids`); the space is given back at once. Needs `edit` on `uploadedFiles`. Ask your user first.",
        "operationId": "cleanUnusedAttachments",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "properties": {
                  "ids": {
                    "items": {
                      "type": "string"
                    },
                    "type": "array"
                  }
                },
                "type": "object"
              }
            }
          },
          "required": false
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "additionalProperties": true,
                  "type": "object"
                }
              }
            },
            "description": "`{deleted, bytes}`."
          },
          "400": {
            "description": "A body that is not `{ids}` (`request.invalid`)."
          },
          "401": {
            "description": "No token, or a wrong, revoked or expired one."
          },
          "403": {
            "description": "Not `edit` on `uploadedFiles` (`file.clean_refused`)."
          },
          "429": {
            "description": "Too many requests for this token (300 a minute): wait `Retry-After` seconds."
          }
        },
        "summary": "Delete the unused attachments for good"
      }
    }
  },
  "security": [
    {
      "bearerAuth": []
    }
  ],
  "servers": [
    {
      "url": "https://paginel.com"
    }
  ]
}