Get Themes by ID

get/v3/kb/themes/{id}
Requires any one of these rolesAbout roles
org.permission.kb.read
Legacyorg.user.content.kb.readorg.user.kb.readorg.admin.content.kb.readorg.admin.kb.read

The API key or user must hold at least one of them. Legacy roles still work; prefer the others for new keys.

Fetches Knowledge Base theme by ID.

About this resource

Knowledge base themes

A theme controls how a help center looks and is laid out, from colors and fonts to the code for each page. Themes keep a history of revisions, so you can edit and preview a draft before you publish it. Templates are the ready-made starting points that new themes are copied from.

Admins customize themes in the theme editor in the knowledge base settings. Each knowledge base displays the theme set in its theme field. A theme's active and default fields are left over from an older model, so ignore them. The public endpoint for the active theme returns the theme of the knowledge base that the request's host identifies.

A theme is customized at two levels. The manifest holds settings that admins change without code. It is grouped into sections such as design, header, footer, searchBar, announcement and featuredArticles, and each variable has a type such as color, select, slider, text, link, list, boolean or file. Theme files hold the code.

Theme files

type What it is Examples
page One help center page homepage.jsx, article.jsx, categories.jsx, search.jsx, tag.jsx, contact.jsx, 404.jsx
component A piece shared between pages Nav.jsx, Footer.jsx, ArticleBreadcrumbs.jsx
asset Stylesheets and scripts, used as written styles.css, utils.js

Pages and components are JSX. Kustomer compiles them when you save and returns the output in compiled. If the content doesn't compile, the save fails with 400. File names must be unique within a revision. Text in a theme can use snippets, so one theme serves every language. Kustomer collects the snippet keys in the manifest into configSnippets for you. List the keys your code uses in the theme's jsxSnippets and in each file's snippets, and make sure each key exists, because Kustomer rejects a file that lists an unknown key.

Drafts and revisions

A theme keeps a stack of revisions, and each revision has its own files. The newest revision is either the published one or a single draft on top of it. The theme's status is draft while a draft exists and published otherwise.

  1. POST …/revisions/draft creates the draft from the name, manifest and jsxSnippets you send, with a copy of the published revision's files. To copy an older revision's settings and files instead, send only duplicateRevisionId. If a draft already exists, it is replaced, and edits to its files are lost.
  2. Edit the draft's name, manifest and jsxSnippets with PUT …/revisions/draft, and edit its files through the file endpoints using the draft's revision ID.
  3. Preview the draft with the public endpoints by passing status=draft or the revisionId.
  4. Send { "publish": true } to PUT …/revisions/draft to publish, or DELETE the draft to discard it.

Kustomer keeps the 30 most recent revisions. When a publish pushes out the oldest revision, its files are deleted.

Templates

Templates aren't page templates. Each template is a complete starter theme that Kustomer provides, such as "Midtown". It has a title, a description, preview images, a version and a default manifest. Templates are read-only. To start from one, create a theme with duplicateTemplateId, and the theme's templateVersionId records the template version it came from. To copy one of your own themes, use duplicateThemeId instead. You can't send both. A new knowledge base created without a theme gets one built from Midtown.

Which endpoint to use

To Call
List themes, or read one GET /v3/kb/themes or GET /v3/kb/themes/{id}
Create a theme from a template or another theme POST /v3/kb/themes
Load the live theme or a preview, without an API key GET /p/v3/kb/themes/active, GET /p/v3/kb/themes/{id} or GET /p/v3/kb/themes/{id}/files
Browse revision history GET …/revisions or GET …/revisions/{id}
Start, edit, publish or discard the draft POST, PUT or DELETE /v3/kb/themes/{themeId}/revisions/draft
List or read a revision's files GET …/revisions/{revisionId}/files or GET …/files/{id}
Add, change or remove a file POST …/files, PUT …/files/{id} or DELETE …/files/{id}
List the starter templates, or read one GET /v3/kb/templates or GET /v3/kb/templates/{id}

The public theme endpoints return the published revision unless you ask for a draft or a specific revision. Reads need a knowledge base read role, and writes need org.admin.kb.write or the matching permission.

RelatedKnowledge basesSnippetsAdd chat to a Kustomer knowledge base

Path parameters

idstringrequired

Resource ID

Example "6026aba3fcca5f03e5541cd5"

Query parameters

includestring

Comma-separated related resources to include.

Example "snippets"

Responses

OK

objectrequired