Kodkila Developers

GET/cms/docs/navThe sidebar of a version: nested {id, kind, title, path, deprecated, children} (Public; weak ETag)
GET/cms/docs/pageOne page by path: Markdown, TOC, reading time, breadcrumbs, prev/next, deprecation, other versions (Public; weak ETag)
GET/cms/docs/searchSearch a version's live pages: title, path, breadcrumbs, excerpt, matching headings, highlight offsets (Public; weak ETag)
GET/cms/docs/versionsReadable docs versions, which one latest is, and deprecation banners (Public; weak ETag)
GET/cms/public/{channelId}/layoutSite layout / theme settings (Public)
GET/cms/public/{channelId}/menusPublished menus with their item trees (Public)
GET/cms/public/{channelId}/postsLive blog posts, newest first (Public, max 50)
GET/cms/public/{channelId}/posts/{slug}One live blog post by slug (Public)
GET/cms/public/{channelId}/surfaces/{surface}A published home surface for one audience: {banners[], shortcuts[], ads[], texts{}} (Public; ETag/304; cached)
GET/cms/public/{channelId}/surfaces/{surface}/eventsLive 'surface changed' signal (SSE, Public)
GET/cms/public/{channelId}/surfaces/{surface}/versionJust the public version of a surface (cheap polling fallback for the stream)
GET/cms/public/{channelId}/testimonialsPublished testimonials (Public, max 100)
GET/cms/surfaces/{surface}The same, naming the channel with x-ref, X-App-Key or ?channel_id (Public)

The sidebar of a version: nested {id, kind, title, path, deprecated, children} (Public; weak ETag)

GET/cms/docs/nav

Public: no sign-in needed.

Parameters

Name	Type	Description
channel_id	string (uuid), query	The channel, when no X-App-Key / x-ref is sent
version	string, query	A version tag, or latest (default) At most 32 characters. Example: "latest"
X-App-Key	string, header	The channel's app key (names the channel)
x-ref	string, header	Or the channel id
If-None-Match	string, header	A previous weak ETag; a match answers 304

Response

200. data is object (PublicDocNavDto). OK. Headers: ETag (weak), Cache-Control (public, short), Vary: Accept-Encoding, X-App-Key, X-Ref

Field	Type	Description
versionrequired	string	Example: "v2"
labelrequired	string	Example: "v2 (current)"
latest_versionrequired	string	Example: "v2"
is_latestrequired	boolean
deprecationrequired	object	The version's own deprecation
deprecation.deprecatedrequired	boolean
deprecation.bannerrequired	string	Example: "You are reading the docs for v1, which is deprecated."
navrequired	object[]
nav[].idrequired	number	Example: 12
nav[].kindrequired	string	group: a heading without a page (don't link it) One of: "page", "group".
nav[].titlerequired	string	Example: "Sessions"
nav[].pathrequired	string	Example: "guides/auth/sessions"
nav[].deprecatedrequired	boolean
nav[].childrenrequired	object[]
nav[].children[].idrequired	number	Example: 12
nav[].children[].kindrequired	string	group: a heading without a page (don't link it) One of: "page", "group".
nav[].children[].titlerequired	string	Example: "Sessions"
nav[].children[].pathrequired	string	Example: "guides/auth/sessions"
nav[].children[].deprecatedrequired	boolean
nav[].children[].childrenrequired	object[]

One page by path: Markdown, TOC, reading time, breadcrumbs, prev/next, deprecation, other versions (Public; weak ETag)

GET/cms/docs/page

Public: no sign-in needed.

Parameters

Name	Type	Description
channel_id	string (uuid), query	The channel, when no X-App-Key / x-ref is sent
version	string, query	A version tag, or latest (default) At most 32 characters. Example: "latest"
pathrequired	string, query	The page's full path (leading/trailing slashes and case are ignored) At most 700 characters. Example: "guides/auth/sessions"
X-App-Key	string, header	The channel's app key (names the channel)
x-ref	string, header	Or the channel id
If-None-Match	string, header	A previous weak ETag; a match answers 304

Response

200. data is object (PublicDocPageDto). OK. Headers: ETag (weak), Cache-Control (public, short), Vary: Accept-Encoding, X-App-Key, X-Ref

Field	Type	Description
idrequired	number	Example: 12
versionrequired	string	Example: "v2"
slugrequired	string	Example: "sessions"
pathrequired	string	Example: "guides/auth/sessions"
titlerequired	string	Example: "Sessions"
nav_titlerequired	string
descriptionrequired	string
body_mdrequired	string	Example: "## Refresh tokens\n\nUse the refresh token…"
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
seo_titlerequired	string
seo_descriptionrequired	string
date_createdrequired	string (date-time)
date_updatedrequired	string (date-time)
is_latestrequired	boolean
latest_versionrequired	string	Example: "v2"
deprecationrequired	object
deprecation.deprecatedrequired	boolean
deprecation.bannerrequired	string	Example: "You are reading the docs for v1, which is deprecated."
breadcrumbsrequired	object[]
breadcrumbs[].titlerequired	string	Example: "Tokens"
breadcrumbs[].pathrequired	string	Example: "guides/auth/tokens"
breadcrumbs[].kindrequired	string	One of: "page", "group". Example: "page"
prevrequired	object
prev.titlerequired	string	Example: "Tokens"
prev.pathrequired	string	Example: "guides/auth/tokens"
nextrequired	object
next.titlerequired	string	Example: "Tokens"
next.pathrequired	string	Example: "guides/auth/tokens"
other_versionsrequired	object[]
other_versions[].versionrequired	string	Example: "v1"
other_versions[].labelrequired	string	Example: "v1"
other_versions[].is_latestrequired	boolean
other_versions[].pathrequired	string	This page in that version, else that version's first page Example: "guides/auth/sessions"
other_versions[].same_pagerequired	boolean	false when path is that version's first page instead

Search a version's live pages: title, path, breadcrumbs, excerpt, matching headings, highlight offsets (Public; weak ETag)

GET/cms/docs/search

Public: no sign-in needed.

Parameters

Name	Type	Description
channel_id	string (uuid), query	The channel, when no X-App-Key / x-ref is sent
version	string, query	A version tag, or latest (default) At most 32 characters. Example: "latest"
qrequired	string, query	At most 200 characters. Example: "refresh token"
limit	number, query	Minimum 1, maximum 50.
X-App-Key	string, header	The channel's app key (names the channel)
x-ref	string, header	Or the channel id
If-None-Match	string, header	A previous weak ETag; a match answers 304

Response

200. data is object (PublicDocSearchDto). OK. Headers: ETag (weak), Cache-Control (public, short), Vary: Accept-Encoding, X-App-Key, X-Ref

Field	Type	Description
queryrequired	string	Example: "refresh token"
versionrequired	string	Example: "v2"
latest_versionrequired	string	Example: "v2"
is_latestrequired	boolean
totalrequired	number	Every live page that matches Example: 3
hitsrequired	object[]
hits[].titlerequired	string	Example: "Sessions"
hits[].pathrequired	string	Example: "guides/auth/sessions"
hits[].versionrequired	string	Example: "v2"
hits[].breadcrumbsrequired	object[]
hits[].breadcrumbs[].titlerequired	string	Example: "Tokens"
hits[].breadcrumbs[].pathrequired	string	Example: "guides/auth/tokens"
hits[].breadcrumbs[].kindrequired	string	One of: "page", "group". Example: "page"
hits[].excerptrequired	string	Example: "…Use the refresh token to get a new session…"
hits[].headingsrequired	object[]	Headings containing a query word; link as /<path>#<id>
hits[].headings[].depthrequired	number	Example: 2
hits[].headings[].textrequired	string	Example: "Refresh tokens"
hits[].headings[].idrequired	string	Anchor id (rehype-slug / github-slugger) Example: "refresh-tokens"
hits[].headings[].highlightsrequired	integer[][]
hits[].highlightsrequired	object
hits[].highlights.titlerequired	integer[][]	[start, end) offsets in title
hits[].highlights.excerptrequired	integer[][]	[start, end) offsets in excerpt
hits[].scorerequired	number	Example: 61

Readable docs versions, which one latest is, and deprecation banners (Public; weak ETag)

GET/cms/docs/versions

Public: no sign-in needed.

Parameters

Name	Type	Description
channel_id	string (uuid), query	The channel, when no X-App-Key / x-ref is sent
version	string, query	A version tag, or latest (default) At most 32 characters. Example: "latest"
X-App-Key	string, header	The channel's app key (names the channel)
x-ref	string, header	Or the channel id
If-None-Match	string, header	A previous weak ETag; a match answers 304

Response

200. data is object (PublicDocVersionsDto). OK. Headers: ETag (weak), Cache-Control (public, short), Vary: Accept-Encoding, X-App-Key, X-Ref

Field	Type	Description
latest_versionrequired	string	Example: "v2"
versionsrequired	object[]
versions[].namerequired	string	Example: "v2"
versions[].labelrequired	string	Example: "v2 (current)"
versions[].is_latestrequired	boolean
versions[].deprecatedrequired	boolean
versions[].bannerrequired	string

Site layout / theme settings (Public)

GET/cms/public/{channelId}/layout

Public: no sign-in needed.

Parameters

Name	Type	Description
channelIdrequired	string, path

Response

200. The payload in data is of type object.

Published menus with their item trees (Public)

GET/cms/public/{channelId}/menus

Public: no sign-in needed.

Parameters

Name	Type	Description
channelIdrequired	string, path
location	string, query	Example: "header"

Response

200. data is object[].

Live blog posts, newest first (Public, max 50)

GET/cms/public/{channelId}/posts

Public: no sign-in needed.

Parameters

Name	Type	Description
channelIdrequired	string, path

Response

200. data is object[].

One live blog post by slug (Public)

GET/cms/public/{channelId}/posts/{slug}

Public: no sign-in needed.

Parameters

Name	Type	Description
channelIdrequired	string, path
slugrequired	string, path

Response

200. The payload in data is of type object.

A published home surface for one audience: {banners[], shortcuts[], ads[], texts{}} (Public; ETag/304; cached)

GET/cms/public/{channelId}/surfaces/{surface}

Public: no sign-in needed.

Parameters

Name	Type	Description
channelIdrequired	string, path
surfacerequired	string, path
If-None-Match	string, header
locale	any, query	Example: "en-GB"
platform	any, query	web, ios, android, mac, windows or linux Example: "windows"
country	any, query	Example: "GB"

Response

200. The payload in data is not described in the spec yet.

Live 'surface changed' signal (SSE, Public)

GET/cms/public/{channelId}/surfaces/{surface}/events

Public: no sign-in needed.

Server-Sent Events: surface.version on connect (the current public version), then surface.changed {surface, version, published} each time it is published, unpublished or deleted. No content travels; refetch the surface (with If-None-Match) when the version is newer than yours.

Parameters

Name	Type	Description
channelIdrequired	string, path
surfacerequired	string, path

Response

200. The payload in data is not described in the spec yet.

Just the public version of a surface (cheap polling fallback for the stream)

GET/cms/public/{channelId}/surfaces/{surface}/version

Public: no sign-in needed.

Parameters

Name	Type	Description
channelIdrequired	string, path
surfacerequired	string, path

Response

200. The payload in data is not described in the spec yet.

Published testimonials (Public, max 100)

GET/cms/public/{channelId}/testimonials

Public: no sign-in needed.

Parameters

Name	Type	Description
channelIdrequired	string, path

Response

200. data is object[].

The same, naming the channel with x-ref, X-App-Key or ?channel_id (Public)

GET/cms/surfaces/{surface}

Public: no sign-in needed.

Parameters

Name	Type	Description
surfacerequired	string, path
x-ref	string, header	Channel id (or send X-App-Key)
channel_id	any, query
locale	any, query	Example: "en-GB"
platform	any, query	web, ios, android, mac, windows or linux Example: "windows"
country	any, query	Example: "GB"

Response

200. The payload in data is not described in the spec yet.

CMS · public

The sidebar of a version: nested {id, kind, title, path, deprecated, children} (Public; weak ETag)

Parameters

Response

One page by path: Markdown, TOC, reading time, breadcrumbs, prev/next, deprecation, other versions (Public; weak ETag)

Parameters

Response

Search a version's live pages: title, path, breadcrumbs, excerpt, matching headings, highlight offsets (Public; weak ETag)

Parameters

Response

Readable docs versions, which one latest is, and deprecation banners (Public; weak ETag)

Parameters

Response

Site layout / theme settings (Public)

Parameters

Response

Published menus with their item trees (Public)

Parameters

Response

Live blog posts, newest first (Public, max 50)

Parameters

Response

One live blog post by slug (Public)

Parameters

Response

A published home surface for one audience: {banners[], shortcuts[], ads[], texts{}} (Public; ETag/304; cached)

Parameters

Response

Live 'surface changed' signal (SSE, Public)

Parameters

Response

Just the public version of a surface (cheap polling fallback for the stream)

Parameters

Response

Published testimonials (Public, max 100)

Parameters

Response

The same, naming the channel with x-ref, X-App-Key or ?channel_id (Public)

Parameters

Response