CMS · docs
12 routes. Paths are relative to https://api.intersink.com/v1.
- GET/cms/channels/{channelId}/doc-versionsVersions with page counts, what latest resolves to, and deprecation
- PUT/cms/channels/{channelId}/doc-versions/{name}Create or change a version's settings: label, is_latest, deprecated + banner, order
- DELETE/cms/channels/{channelId}/doc-versions/{name}Delete a version's settings
- POST/cms/channels/{channelId}/doc-versions/{name}/cloneStart this version as a copy of another (copies start as drafts unless as_draft is false)
- GET/cms/channels/{channelId}/docsList the channel's doc pages (all statuses; no bodies)
- POST/cms/channels/{channelId}/docsCreate a doc page or sidebar group (Markdown is made safe; the answer lists changes as warnings)
- GET/cms/channels/{channelId}/docs/{id}One doc page with its Markdown
- PATCH/cms/channels/{channelId}/docs/{id}Update a doc page (a new slug or parent moves the pages under it too, atomically)
- DELETE/cms/channels/{channelId}/docs/{id}Delete a doc page
- POST/cms/channels/{channelId}/docs/previewCheck Markdown without saving: the safe Markdown, TOC, reading time and warnings
- POST/cms/channels/{channelId}/docs/reorderMove and reorder pages of one version in one go (all or nothing; paths follow)
- GET/cms/channels/{channelId}/docs/treeEvery page and group of a version as a tree, drafts included (default: the latest version)
Versions with page counts, what latest resolves to, and deprecation
GET/cms/channels/{channelId}/doc-versions
Needs a signed-in user (Bearer token or access_token cookie).
Parameters
| Name | Type | Description |
|---|---|---|
| channelIdrequired | string, path |
Response
200. data is object (DocVersionsAdminResultDto).
| Field | Type | Description |
|---|---|---|
| latest_versionrequired | string | Example: "v2" |
| versionsrequired | object[] | |
| versions[].namerequired | string | Example: "v2" |
| versions[].labelrequired | string | |
| versions[].is_latestrequired | boolean | What latest resolves to for readers now |
| versions[].marked_latestrequired | boolean | Marked latest in its settings (readers fall back while it has no live pages) |
| versions[].deprecatedrequired | boolean | |
| versions[].bannerrequired | string | |
| versions[].sortrequired | number | |
| versions[].pagesrequired | number | Example: 42 |
| versions[].publishedrequired | number | Example: 40 |
| versions[].liverequired | boolean | Has live pages (readers can open it) |
| versions[].configuredrequired | boolean | Has a settings row |
Create or change a version's settings: label, is_latest, deprecated + banner, order
PUT/cms/channels/{channelId}/doc-versions/{name}
Needs a signed-in user (Bearer token or access_token cookie).
Parameters
| Name | Type | Description |
|---|---|---|
| channelIdrequired | string, path | |
| namerequired | string, path |
Request body application/json
| Field | Type | Description |
|---|---|---|
| label | string | At most 60 characters. Example: "v2 (current)" |
| is_latest | boolean | Make this the version latest points to (it must have live pages) |
| deprecated | boolean | Every page of this version shows a deprecation banner |
| banner | string | At most 300 characters. Example: "v1 is no longer maintained." |
| sort | number | Order in the version switcher (lower first) Minimum -100000, maximum 100000. |
Response
200. data is object (DocVersionRecordDto).
| Field | Type | Description |
|---|---|---|
| idrequired | number | |
| channel_idrequired | string (uuid) | |
| namerequired | string | Example: "v2" |
| labelrequired | string | |
| is_latestrequired | boolean | |
| deprecatedrequired | boolean | |
| bannerrequired | string | |
| sortrequired | number |
Delete a version's settings
DELETE/cms/channels/{channelId}/doc-versions/{name}
Needs a signed-in user (Bearer token or access_token cookie).
Parameters
| Name | Type | Description |
|---|---|---|
| channelIdrequired | string, path | |
| namerequired | string, path |
Response
200. data is object (DocVersionDeletedDto).
| Field | Type | Description |
|---|---|---|
| namerequired | string | Example: "v0" |
| deletedrequired | boolean | Example: true |
Start this version as a copy of another (copies start as drafts unless as_draft is false)
POST/cms/channels/{channelId}/doc-versions/{name}/clone
Needs a signed-in user (Bearer token or access_token cookie).
Parameters
| Name | Type | Description |
|---|---|---|
| channelIdrequired | string, path | |
| namerequired | string, path |
Request body application/json
| Field | Type | Description |
|---|---|---|
| fromrequired | string | Copy every page of this version Example: "v1" |
| as_draft | boolean | Copied pages start as drafts |
Response
201. data is object (DocCloneResultDto). Copied
| Field | Type | Description |
|---|---|---|
| versionrequired | string | Example: "v2" |
| fromrequired | string | Example: "v1" |
| copiedrequired | number | Example: 42 |
| as_draftrequired | boolean |
List the channel's doc pages (all statuses; no bodies)
GET/cms/channels/{channelId}/docs
Needs a signed-in user (Bearer token or access_token cookie).
Parameters
| Name | Type | Description |
|---|---|---|
| channelIdrequired | string, path | |
| page | number, query | Minimum 1, maximum 10000. |
| limit | number, query | Minimum 1, maximum 100. |
| status | string, query | One of: "draft", "published", "archived". |
| version | string, query | Example: "v1" |
| q | string, query | Search in the title and path At most 100 characters. |
Response
200. data is object (DocListResultDto).
| Field | Type | Description |
|---|---|---|
| datarequired | object[] | Pages without body_md |
| data[].idrequired | number | Example: 12 |
| data[].channel_idrequired | string (uuid) | |
| data[].kindrequired | string | One of: "page", "group". |
| data[].versionrequired | string | Example: "v1" |
| data[].parent_idrequired | number | Example: 10 |
| data[].slugrequired | string | Example: "sessions" |
| data[].pathrequired | string | Example: "guides/auth/sessions" |
| data[].sortrequired | number | Example: 0 |
| data[].titlerequired | string | Example: "Sessions" |
| data[].nav_titlerequired | string | |
| data[].nav_hiddenrequired | boolean | |
| data[].descriptionrequired | string | |
| data[].body_mdrequired | string | Safe, canonical Markdown |
| data[].tocrequired | object[] | |
| data[].toc[].depthrequired | number | Example: 2 |
| data[].toc[].textrequired | string | Example: "Refresh tokens" |
| data[].toc[].idrequired | string | Anchor id (rehype-slug / github-slugger) Example: "refresh-tokens" |
| data[].reading_minutesrequired | number | Example: 3 |
| data[].word_countrequired | number | Example: 512 |
| data[].statusrequired | string | One of: "draft", "published", "archived". |
| data[].deprecatedrequired | boolean | |
| data[].deprecated_bannerrequired | string | |
| data[].seo_titlerequired | string | |
| data[].seo_descriptionrequired | string | |
| data[].author_user_idrequired | string (uuid) | |
| data[].updated_by_user_idrequired | string (uuid) | |
| data[].date_createdrequired | string (date-time) | |
| data[].date_updatedrequired | string (date-time) | |
| pagerequired | number | Example: 1 |
| limitrequired | number | Example: 20 |
| totalrequired | number | Example: 42 |
| hasMorerequired | boolean |
Create a doc page or sidebar group (Markdown is made safe; the answer lists changes as warnings)
POST/cms/channels/{channelId}/docs
Needs a signed-in user (Bearer token or access_token cookie).
Parameters
| Name | Type | Description |
|---|---|---|
| channelIdrequired | string, path |
Request body application/json
| Field | Type | Description |
|---|---|---|
| titlerequired | string | At most 200 characters. Example: "Sessions" |
| kind | string | page: has content; group: a sidebar heading only (no body, not a page of its own) One of: "page", "group". |
| slug | string | This page's path segment (default: from the title) At most 80 characters. Example: "sessions" |
| parent_id | number | Parent page id (same channel and version); null = top level Example: 12 |
| version | string | Version tag (default: the channel's latest version, else v1). Fixed once created. Example: "v1" |
| sort | number | Position among its siblings (lower first) Minimum -100000, maximum 100000. Example: 10 |
| nav_title | string | Shorter label for the sidebar At most 80 characters. Example: "Sessions" |
| nav_hidden | boolean | Kept out of the sidebar and prev/next (still reachable by path) |
| description | string | At most 300 characters. Example: "How sign-in sessions work and how to refresh them." |
| body_md | string | Markdown (docs/cms-docs.md); made safe and canonical on save At most 100000 characters. Example: "## Refresh tokens\n\n:::warning[Keep it secret]\nNever ship a server key.\n:::\n\n``ts title=\"client.ts\"\nawait client.refresh()\n``" |
| status | string | One of: "draft", "published", "archived". |
| deprecated | boolean | Show a deprecation banner on this page |
| deprecated_banner | string | At most 300 characters. Example: "Use sessions instead." |
| seo_title | string | At most 70 characters. |
| seo_description | string | At most 170 characters. |
Response
201. data is object (DocWriteResultDto). Created
| Field | Type | Description |
|---|---|---|
| idrequired | number | Example: 12 |
| channel_idrequired | string (uuid) | |
| kindrequired | string | One of: "page", "group". |
| versionrequired | string | Example: "v1" |
| parent_idrequired | number | Example: 10 |
| slugrequired | string | Example: "sessions" |
| pathrequired | string | Example: "guides/auth/sessions" |
| sortrequired | number | Example: 0 |
| titlerequired | string | Example: "Sessions" |
| nav_titlerequired | string | |
| nav_hiddenrequired | boolean | |
| descriptionrequired | string | |
| body_mdrequired | string | Safe, canonical Markdown |
| tocrequired | object[] | |
| toc[].depthrequired | number | Example: 2 |
| toc[].textrequired | string | Example: "Refresh tokens" |
| toc[].idrequired | string | Anchor id (rehype-slug / github-slugger) Example: "refresh-tokens" |
| reading_minutesrequired | number | Example: 3 |
| word_countrequired | number | Example: 512 |
| statusrequired | string | One of: "draft", "published", "archived". |
| deprecatedrequired | boolean | |
| deprecated_bannerrequired | string | |
| seo_titlerequired | string | |
| seo_descriptionrequired | string | |
| author_user_idrequired | string (uuid) | |
| updated_by_user_idrequired | string (uuid) | |
| date_createdrequired | string (date-time) | |
| date_updatedrequired | string (date-time) | |
| warningsrequired | object[] | What was changed to make the Markdown safe (empty when nothing) |
| warnings[].coderequired | string | One of: "HTML_ESCAPED", "HTML_COMMENT_REMOVED", "MDX_REMOVED", "UNSAFE_URL", "CODE_LANGUAGE_REMOVED", "CODE_META_CLEANED", "DIRECTIVE_AS_TEXT", "UNKNOWN_CONTAINER", "ATTRIBUTES_REMOVED", "CODE_GROUP_CONTENT". Example: "HTML_ESCAPED" |
| warnings[].messagerequired | string | Example: "Raw HTML is not allowed in docs; it is shown as text." |
| warnings[].linerequired | number | Example: 3 |
One doc page with its Markdown
GET/cms/channels/{channelId}/docs/{id}
Needs a signed-in user (Bearer token or access_token cookie).
Parameters
| Name | Type | Description |
|---|---|---|
| channelIdrequired | string, path | |
| idrequired | number, path |
Response
200. data is object (DocAdminDto).
| Field | Type | Description |
|---|---|---|
| idrequired | number | Example: 12 |
| channel_idrequired | string (uuid) | |
| kindrequired | string | One of: "page", "group". |
| versionrequired | string | Example: "v1" |
| parent_idrequired | number | Example: 10 |
| slugrequired | string | Example: "sessions" |
| pathrequired | string | Example: "guides/auth/sessions" |
| sortrequired | number | Example: 0 |
| titlerequired | string | Example: "Sessions" |
| nav_titlerequired | string | |
| nav_hiddenrequired | boolean | |
| descriptionrequired | string | |
| body_mdrequired | string | Safe, canonical Markdown |
| tocrequired | object[] | |
| toc[].depthrequired | number | Example: 2 |
| toc[].textrequired | string | Example: "Refresh tokens" |
| toc[].idrequired | string | Anchor id (rehype-slug / github-slugger) Example: "refresh-tokens" |
| reading_minutesrequired | number | Example: 3 |
| word_countrequired | number | Example: 512 |
| statusrequired | string | One of: "draft", "published", "archived". |
| deprecatedrequired | boolean | |
| deprecated_bannerrequired | string | |
| seo_titlerequired | string | |
| seo_descriptionrequired | string | |
| author_user_idrequired | string (uuid) | |
| updated_by_user_idrequired | string (uuid) | |
| date_createdrequired | string (date-time) | |
| date_updatedrequired | string (date-time) |
Update a doc page (a new slug or parent moves the pages under it too, atomically)
PATCH/cms/channels/{channelId}/docs/{id}
Needs a signed-in user (Bearer token or access_token cookie).
Parameters
| Name | Type | Description |
|---|---|---|
| channelIdrequired | string, path | |
| idrequired | number, path |
Request body application/json
| Field | Type | Description |
|---|---|---|
| title | string | At most 200 characters. |
| slug | string | A new slug moves the pages under this one too At most 80 characters. |
| parent_id | number | A new parent moves the pages under this one too |
| sort | number | Minimum -100000, maximum 100000. |
| nav_title | string | At most 80 characters. |
| nav_hidden | boolean | |
| description | string | At most 300 characters. |
| body_md | string | At most 100000 characters. |
| status | string | One of: "draft", "published", "archived". |
| deprecated | boolean | |
| deprecated_banner | string | At most 300 characters. |
| seo_title | string | At most 70 characters. |
| seo_description | string | At most 170 characters. |
Response
200. data is object (DocWriteResultDto).
| Field | Type | Description |
|---|---|---|
| idrequired | number | Example: 12 |
| channel_idrequired | string (uuid) | |
| kindrequired | string | One of: "page", "group". |
| versionrequired | string | Example: "v1" |
| parent_idrequired | number | Example: 10 |
| slugrequired | string | Example: "sessions" |
| pathrequired | string | Example: "guides/auth/sessions" |
| sortrequired | number | Example: 0 |
| titlerequired | string | Example: "Sessions" |
| nav_titlerequired | string | |
| nav_hiddenrequired | boolean | |
| descriptionrequired | string | |
| body_mdrequired | string | Safe, canonical Markdown |
| tocrequired | object[] | |
| toc[].depthrequired | number | Example: 2 |
| toc[].textrequired | string | Example: "Refresh tokens" |
| toc[].idrequired | string | Anchor id (rehype-slug / github-slugger) Example: "refresh-tokens" |
| reading_minutesrequired | number | Example: 3 |
| word_countrequired | number | Example: 512 |
| statusrequired | string | One of: "draft", "published", "archived". |
| deprecatedrequired | boolean | |
| deprecated_bannerrequired | string | |
| seo_titlerequired | string | |
| seo_descriptionrequired | string | |
| author_user_idrequired | string (uuid) | |
| updated_by_user_idrequired | string (uuid) | |
| date_createdrequired | string (date-time) | |
| date_updatedrequired | string (date-time) | |
| warningsrequired | object[] | What was changed to make the Markdown safe (empty when nothing) |
| warnings[].coderequired | string | One of: "HTML_ESCAPED", "HTML_COMMENT_REMOVED", "MDX_REMOVED", "UNSAFE_URL", "CODE_LANGUAGE_REMOVED", "CODE_META_CLEANED", "DIRECTIVE_AS_TEXT", "UNKNOWN_CONTAINER", "ATTRIBUTES_REMOVED", "CODE_GROUP_CONTENT". Example: "HTML_ESCAPED" |
| warnings[].messagerequired | string | Example: "Raw HTML is not allowed in docs; it is shown as text." |
| warnings[].linerequired | number | Example: 3 |
Delete a doc page
DELETE/cms/channels/{channelId}/docs/{id}
Needs a signed-in user (Bearer token or access_token cookie).
Parameters
| Name | Type | Description |
|---|---|---|
| channelIdrequired | string, path | |
| idrequired | number, path |
Response
200. data is object (DocDeletedDto).
| Field | Type | Description |
|---|---|---|
| idrequired | number | Example: 12 |
| deletedrequired | boolean | Example: true |
Check Markdown without saving: the safe Markdown, TOC, reading time and warnings
POST/cms/channels/{channelId}/docs/preview
Needs a signed-in user (Bearer token or access_token cookie).
Parameters
| Name | Type | Description |
|---|---|---|
| channelIdrequired | string, path |
Request body application/json
| Field | Type | Description |
|---|---|---|
| body_mdrequired | string | Markdown to check At most 100000 characters. Example: "Hi <b>there</b>\n\n:::tip Did you know\nIt works.\n:::" |
Response
200. data is object (DocPreviewResultDto).
| Field | Type | Description |
|---|---|---|
| body_mdrequired | string | Example: "Hi \\<b>there\\</b>\n\n:::tip[Did you know]\nIt works.\n:::" |
| tocrequired | object[] | |
| toc[].depthrequired | number | Example: 2 |
| toc[].textrequired | string | Example: "Refresh tokens" |
| toc[].idrequired | string | Anchor id (rehype-slug / github-slugger) Example: "refresh-tokens" |
| reading_minutesrequired | number | |
| word_countrequired | number | |
| code_blocksrequired | object[] | |
| code_blocks[].langrequired | string | Example: "ts" |
| code_blocks[].titlerequired | string | Example: "client.ts" |
| code_blocks[].grouprequired | number | Index of its :::code-group, else null |
| calloutsrequired | number | |
| warningsrequired | object[] | |
| warnings[].coderequired | string | One of: "HTML_ESCAPED", "HTML_COMMENT_REMOVED", "MDX_REMOVED", "UNSAFE_URL", "CODE_LANGUAGE_REMOVED", "CODE_META_CLEANED", "DIRECTIVE_AS_TEXT", "UNKNOWN_CONTAINER", "ATTRIBUTES_REMOVED", "CODE_GROUP_CONTENT". Example: "HTML_ESCAPED" |
| warnings[].messagerequired | string | Example: "Raw HTML is not allowed in docs; it is shown as text." |
| warnings[].linerequired | number | Example: 3 |
Move and reorder pages of one version in one go (all or nothing; paths follow)
POST/cms/channels/{channelId}/docs/reorder
Needs a signed-in user (Bearer token or access_token cookie).
Parameters
| Name | Type | Description |
|---|---|---|
| channelIdrequired | string, path |
Request body application/json
| Field | Type | Description |
|---|---|---|
| versionrequired | string | Example: "v1" |
| itemsrequired | object[] | Up to 500 moves, applied together At most 500 items. |
| items[].idrequired | number | Example: 12 |
| items[].parent_id | number | Omitted = parent unchanged; null = top level |
| items[].sortrequired | number | Minimum -100000, maximum 100000. Example: 0 |
Response
200. data is object (DocReorderResultDto).
| Field | Type | Description |
|---|---|---|
| versionrequired | string | Example: "v1" |
| movedrequired | number | Pages whose parent, order or path changed Example: 4 |
Every page and group of a version as a tree, drafts included (default: the latest version)
GET/cms/channels/{channelId}/docs/tree
Needs a signed-in user (Bearer token or access_token cookie).
Parameters
| Name | Type | Description |
|---|---|---|
| channelIdrequired | string, path | |
| version | string, query | Default: the latest version Example: "v1" |
Response
200. data is object (DocTreeResultDto).
| Field | Type | Description |
|---|---|---|
| versionrequired | string | Example: "v1" |
| totalrequired | number | Example: 42 |
| treerequired | object[] | |
| tree[].idrequired | number | Example: 12 |
| tree[].kindrequired | string | One of: "page", "group". |
| tree[].titlerequired | string | Example: "Sessions" |
| tree[].nav_titlerequired | string | |
| tree[].slugrequired | string | Example: "sessions" |
| tree[].pathrequired | string | Example: "guides/auth/sessions" |
| tree[].sortrequired | number | |
| tree[].statusrequired | string | One of: "draft", "published", "archived". |
| tree[].nav_hiddenrequired | boolean | |
| tree[].deprecatedrequired | boolean | |
| tree[].date_updatedrequired | string (date-time) | |
| tree[].childrenrequired | object[] | |
| tree[].children[].idrequired | number | Example: 12 |
| tree[].children[].kindrequired | string | One of: "page", "group". |
| tree[].children[].titlerequired | string | Example: "Sessions" |
| tree[].children[].nav_titlerequired | string | |
| tree[].children[].slugrequired | string | Example: "sessions" |
| tree[].children[].pathrequired | string | Example: "guides/auth/sessions" |
| tree[].children[].sortrequired | number | |
| tree[].children[].statusrequired | string | One of: "draft", "published", "archived". |
| tree[].children[].nav_hiddenrequired | boolean | |
| tree[].children[].deprecatedrequired | boolean | |
| tree[].children[].date_updatedrequired | string (date-time) | |
| tree[].children[].childrenrequired | object[] |