Developers

Documents API

List, read, create and update documents, and avoid overwriting a newer edit.

On this page

Endpoints
List documents
Create a document
Update without overwriting someone else

The documents API reads and writes documents in the Documentation module. It follows the same permissions as the web app, on the docs.documents key.

Endpoints#

Endpoint	Needs	Purpose
`GET /api/documentation/documents`	`view`	List documents.
`GET /api/documentation/documents/:id`	`view`	Read one document.
`POST /api/documentation/documents`	`write`	Create a document.
`PUT /api/documentation/documents/:id`	`write`	Update a document.
`DELETE /api/documentation/documents/:id`	`write`	Delete a document.
`GET /api/documentation/documents/:id/versions`	`view`	List saved versions.
`POST /api/documentation/documents/:id/versions/:versionNumber/restore`	`write`	Restore an earlier version.
`GET /api/documentation/folders`	`view`	List folders.

You only see documents you have access to, even with view.

List documents#

GET /api/documentation/documents

Query	Meaning
`page`, `limit`	Paging.
`status`	`draft`, `review`, `published` or `archived`.
`visibility`	`private`, `department`, `project` or `public`.
`search`	Words to find in titles and text.
`tags`	Comma-separated tags.
`departmentId`	Only one department.
`sortBy`, `sortOrder`	Order of the results (`asc` or `desc`).
`includeContent`	`true` to include each document's body. Off by default.

bash

curl "https://<your-host>/api/documentation/documents?status=published&limit=20" \
  -H "Authorization: Bearer $TOKEN"

The response has documents and pagination. Each document is shown here with its main fields.

json

{
  "documents": [
    {
      "id": "…",
      "title": "Onboarding checklist",
      "content_type": "markdown",
      "status": "published",
      "visibility": "department",
      "tags": ["hr"],
      "updated_at": "2026-10-01T09:30:00.000Z"
    }
  ],
  "pagination": { "currentPage": 1, "hasMore": false }
}

Create a document#

POST /api/documentation/documents needs write. Only title is required.

Field	Type	Notes
`title`	string	Required.
`content`	string	The body.
`content_type`	string	`html`, `markdown` or `plain`.
`summary`	string	Short description.
`status`	string	`draft`, `review`, `published` or `archived`.
`visibility`	string	`private`, `department`, `project` or `public`.
`folder_id`	string	Put the document in a folder.
`tags`	string array	Labels.

bash

curl -X POST https://<your-host>/api/documentation/documents \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"title": "Onboarding checklist", "content": "## Day one", "content_type": "markdown", "status": "draft"}'

Update without overwriting someone else#

PUT /api/documentation/documents/:id accepts the same fields. To avoid replacing a newer edit, also send baseUpdatedAt: the updated_at you last read.

await fetch(`https://<your-host>/api/documentation/documents/${id}`, {
  method: "PUT",
  headers: { Authorization: `Bearer ${token}`, "Content-Type": "application/json" },
  body: JSON.stringify({ title: "New title", baseUpdatedAt: doc.updated_at }),
});

If someone saved a newer version first, the API answers 409 with the code DOCUMENT_CONFLICT and the current updated_at. Reload the document, merge the change and try again.

Note: A 403 means your role does not hold the level the call needs. See Roles and permissions.

Need more help?

Can’t find what you need? Talk to the team.

Contact support

PreviousRoles and permissions NextErrors and rate limits