# Wiki Read and write the team's internal wiki pages, spaces, databases, the trash, templates, links and tags, comments, and their links to tickets and the help center. The wiki holds your team's internal pages: runbooks, policies, notes, plans, databases. It is for members only and never shown to customers. Pages nest under each other and live in the workspace, a teamspace or one member's private pages. Scopes: `wiki:read` to read, `wiki:write` to change. Guides: [Wiki](/guides/wiki/), [Databases](/guides/wiki-databases/), [Canvas](/guides/wiki-canvas/), [Links, tags and the graph](/guides/wiki-links/), [Comments and following](/guides/wiki-collaboration/), [Tickets, the help center and Ollie](/guides/wiki-desk/), [Import and export](/guides/wiki-import-export/). ## Pages | Method | Path | Description | | --- | --- | --- | | `GET` | `/v1/wiki/pages` | Every page you can see, without its body, to build the tree | | `POST` | `/v1/wiki/pages` | Create a page: `parent_id`, `space`, `team_id`, `title`, `icon`, `body_html`, `position`, `template`, `kind`, `database`, `props`, `canvas` (all optional) | | `GET`, `PATCH`, `DELETE` | `/v1/wiki/pages/{id}` | Read a page with its body, change it, or delete it for good with its subpages | | `POST` | `/v1/wiki/pages/{id}/move` | Put it under another page, or at the top level of a space, at a position | | `POST` | `/v1/wiki/pages/{id}/duplicate` | Copy it with its subpages: `parent_id`, `space`, `team_id`, `template`, `title`, `position` | | `POST` | `/v1/wiki/pages/{id}/trash` | Move it and its subpages to the trash | | `POST` | `/v1/wiki/pages/{id}/restore` | Put it back from the trash, with what went with it | | `GET` | `/v1/wiki/trash` | The pages in the trash, last first | | `GET` | `/v1/wiki/templates` | The templates you can see | | `GET` | `/v1/wiki/pages/{id}/revisions` | Its history, newest first | | `GET` | `/v1/wiki/pages/{id}/revisions/{revisionId}` | One revision with its body | | `POST` | `/v1/wiki/pages/{id}/revisions/{revisionId}/restore` | Put a revision back as a new version | | `GET` | `/v1/wiki/search?q=` | Pages matching the words, best first, with a passage around the match | | `POST` | `/v1/wiki/unfurl` | A link's title, description and picture, for a bookmark block | Viewers read. Agents and up create, edit, move, copy and restore pages. `GET /v1/search` also returns the top wiki pages, in `wiki_pages`. ## Objects ```ts type WikiNode = { id: string; parent_id: string | null; title: string; // "" until named; up to 200 characters (longer is 422) icon: string; // one emoji, or "" position: number; // among its siblings, from 0 version: number; // goes up on every change of title, icon or body updated_at: string; created_by_id: string | null; tags: string[]; // the #tags in its text, lower case kind: "page" | "database" | "canvas"; private: boolean; // yours alone team_id: string | null; // the teamspace it is in journal?: true; // your journal, which holds your daily notes daily_date?: string; // a daily note's day, YYYY-MM-DD template?: true; verified?: true; // verified, and not past the day it was verified until }; type WikiPage = WikiNode & PageSettings & { body_html: string; database: Database | null; // a database's properties and views canvas: Canvas | null; // a canvas's cards and connections props: Record; // a database row's values, by property id verification: { by: UserRef | null; at: string; until: string | null; expired: boolean } | null; deleted_at: string | null; // in the trash since deleted_by: UserRef | null; created_by: UserRef | null; updated_by: UserRef | null; created_at: string; breadcrumbs: { id: string; title: string; icon: string }[]; // top-level page first children: { id: string; title: string; icon: string }[]; }; type PageSettings = { cover: string; // "", "gradient:", or an image: https or /v1/attachments/ cover_y: number; // 0..100, which part of an image cover shows full_width: boolean; small_text: boolean; font: "default" | "serif" | "mono"; locked: boolean; // the app opens it read-only until someone unlocks it }; ``` `created_by_id` and `created_by` are null for a page an API key created, or once its creator deleted their account. ## Spaces A top-level page lives in a space, and every page under it lives there too: - `workspace` (the default): every member sees it. - `private`: one member's own. Nobody else sees it, admins included, nor an API key. AI clients connected as that member read it as them. - `team`: a teamspace, with `team_id`. A private team's pages are its members' alone; a public team's every member sees. Create, move and duplicate take `space` and `team_id` for a top-level page; a subpage always lives where its parent does. Moving a page to another space takes its subpages along. A page you can't see is `404` on every route and never shows in the tree, search, links, the graph, favorites or recent pages. ## Edit without overwriting a teammate Send the `version` you started from. If someone saved the page since, the API answers `409` with code `page_changed` and changes nothing: ```sh curl -X PATCH https://api.opendesk.sh/v1/wiki/pages/0192f0c4-... \ -H "Authorization: Bearer od_live_..." \ -H "Content-Type: application/json" \ -d '{"body_html": "

Refunds over 100 euros go to the team lead.

", "version": 4}' ``` Leave `version` out to always apply the change. A `PATCH` that changes nothing keeps the version. `PATCH` also takes, without a `version`: - The page's look: `cover`, `cover_y`, `full_width`, `small_text`, `font`, `locked`. A cover is `""`, `gradient:` and one of `dawn`, `ocean`, `forest`, `dusk`, `sand`, `slate`, `rose`, `lagoon`, `aurora`, `ember`, or an image: https or one of your attachments. - `verified: true` (with `verified_days`, 1 to 3650, or without for until someone changes it) verifies the page as you; `verified: false` takes it away. People only: an API key is `403`. - `database` (a database only, replaced whole) and `props` (a row only, merged; `null` removes a value). See [Databases](#databases). - `canvas` (a canvas only, replaced whole). See [Canvas](#canvas). None of these moves the version or adds a revision. `locked` is for the app: the API doesn't refuse edits to a locked page. ## Body `body_html` is sanitized before it is stored: only the formatting and blocks below survive, nothing runs, and a value that doesn't match is dropped. Up to 512 KB. | Block | HTML | | --- | --- | | Text, headings 1 to 3 | `p`, `h1` to `h3`, optionally `style="text-align: center"` (left, center, right, justify) | | Block colour | `data-color` (text) and `data-bg` (background) on `p`, `h1` to `h3`, `li`, lists, `blockquote`, `details`: `gray`, `brown`, `orange`, `yellow`, `green`, `blue`, `purple`, `pink`, `red` | | Inline colour | ``, ``, same tones | | To-do list | `