# Design API _Category: REST API reference_ Change a help center's design from code: its theme, pages and components, navigation, custom CSS and scripts. You edit the same draft that the template editor opens, a person reviews it there with a live preview, and visitors see nothing until you publish. Start by reading where the design stands: ``` curl https://api.helpcenter.io/v1/template \ -H "apikey: $HELPCENTER_API_KEY" \ -H "Accept: application/json" ``` The response names the draft and the live version, gives the link to review the draft, and outlines the draft (trimmed here to the colors and the synced regions): ``` { "status": "success", "template": { "engine": "v2", "site": { "id": 391, "name": "Acme Help", "subdomain": "acme" }, "draft": { "id": 223, "etag": "\"223-1790778695000-9b93f595\"", "updated_at": "2026-09-30T14:31:35+00:00", "preset_key": "compass", "has_unpublished_changes": false }, "published": { "id": 222, "status": "published", "live": true, "message": "Initial template", "preset_key": "compass", "published_at": "2026-09-30T14:31:28+00:00" }, "urls": { "live_site": "https://acme.helpcenter.io", "customizer": "https://helpcenter.io/app/sites/acme/customizer-v2", "draft_preview": "https://acme.helpcenter.dev" } }, "outline": { "theme": { "colors": { "primary": "#24644f", "accent": "#edf6f1", "fg": "#1c2926", "bg": "#ffffff", "muted": "#626c68", "surface": "#f6f8f6", "border": "#e2e8e4" } }, "syncedRegions": [ "footer" ], "syncedButDiverged": null } } ``` ## How it works 1. **Read.** `GET /v1/template` returns an outline of the draft and its `etag`. Read any part in full with `GET /v1/template/draft`, and look up what you can change with `GET /v1/template/schema`. 2. **Start from a theme, if you like.** `POST /v1/template/themes/{themeKey}/apply` copies a theme onto the draft, whole or only some parts of it, such as its colors and fonts. 3. **Edit.** `PATCH /v1/template/draft` applies a batch of operations to the draft, all or nothing. 4. **Review.** Send the person responsible for the design to `template.urls.customizer`. The template editor opens on the same draft, with a live preview, and they can adjust it there. 5. **Publish.** `POST /v1/template/publish` puts the draft live. It's the only call that changes what visitors see. - **One draft per help center, shared with the template editor.** Your edits appear in the editor, and edits made in the editor appear in your next read, so a person can pick up where your code stopped, and the other way round (see [Get started with the template editor](https://self.helpcenter.io/content/template-editor)). - **Visitors keep seeing the live design until you publish.** `urls.draft_preview` shows the draft as a website too, but only to signed-in members of the help center's team. - **You can always go back.** Discard the draft to return to the live design, or load an earlier version into the draft and review it before it goes live again. ## Help centers that use the template editor The design API works with help centers designed in the template editor. On a help center that hasn't switched to the template editor yet, every endpoint answers `409 Conflict` with the code `template_migration_required`, and `customizer_url` in the body links to its template editor. The request changes nothing. Switching is the help center owner's decision, and it happens in the dashboard: the template editor turns the current design into a draft to review, and publishing that draft completes the switch. From then on, the design API works. ## Get access Access to the design is granted separately from access to your content, and checked twice on every request. The design API works on every plan, with an API key or an OAuth access token. - **An API key must be created with design access.** When you create the key, tick **Allow access to the help center design** under **Design** (see [API keys](https://developers.helpcenter.io/content/api-keys)). A **Read only** key then holds `design.read` and can read the design. A **Read & write** key also holds `design.write` and can change and publish it. A key created without the option can't reach the design, whatever its scope, and you can't add the option to an existing key: create a new one. Keys with design access carry a **Design** tag in the list of keys. - **OAuth apps** get `design.read` and `design.write` only when they ask for these scopes and the person connecting the app approves them. `content.read` and `content.write` don't include them (see [Scopes](https://developers.helpcenter.io/content/scopes)). - **The person behind the credential must be able to edit the design.** Every request checks that the team member who created the key, or who approved the app, can still edit this help center's design in the dashboard: an Owner, Admin or Editor. Translators and Viewers can't. Without that access, the API answers `403 Forbidden` with the code `design_forbidden`, whatever the credential holds. Replace the key with one created by a current Owner or Admin, or connect the app again as someone who can edit the design. A credential without the scope gets `403` with the code `insufficient_scope` and a message that names the scope, such as `This action requires the design.write scope.` `design.write` reaches the help center's custom CSS and scripts, which run in every visitor's browser once the design is published. Treat a key with design access like an admin password: keep it on a server, give it only to tools you trust, and delete it when the work is done. ## Endpoints | Method and path | What it does | Scope | | --- | --- | --- | | `GET /v1/template` | Read where the design stands, and an outline of the draft | `design.read` | | `GET /v1/template/draft` | Read the draft document, whole or one part | `design.read` | | `GET /v1/template/schema` | Read the customization guide | `design.read` | | `GET /v1/template/themes` | List the themes | `design.read` | | `GET /v1/template/themes/{themeKey}` | Read one theme, and what applying it would change | `design.read` | | `POST /v1/template/themes/{themeKey}/apply` | Apply a theme to the draft | `design.write` | | `PATCH /v1/template/draft` | Edit the draft | `design.write` | | `POST /v1/template/draft/discard` | Discard the draft's changes | `design.write` | | `POST /v1/template/publish` | Publish the draft | `design.write` | | `GET /v1/template/versions` | List the published versions | `design.read` | | `POST /v1/template/versions/{versionId}/restore` | Load an earlier version into the draft | `design.write` | Every request counts toward your credential's 300 requests a minute, and the five writes also toward its 120 writes a minute (see [Rate limits](https://developers.helpcenter.io/content/rate-limits)). ## The template object `GET /v1/template` and every write return `template`, which says where the design stands: | Field | Type | Description | | --- | --- | --- | | `engine` | string | Always `v2`. | | `site` | object | The help center: `id`, `name` (its current name, which becomes the draft's `brand.name` when the draft is published) and `subdomain`. | | `draft.id` | integer | The draft. Every publish starts a new draft, with a new `id`. | | `draft.etag` | string | The draft's current version. Send it with a write to change only the draft you read (see Avoid overwriting someone else's changes, below). The quotes inside it are part of the value. | | `draft.updated_at` | string | When the draft last changed, ISO 8601 with an offset. | | `draft.preset_key` | string | The key of the theme the draft came from, or of the theme last applied to it. Applying only some sections of a theme sets it too, and discarding the draft leaves it as it was. | | `draft.has_unpublished_changes` | boolean | `true` when the draft differs from the live design. | | `published` | object or null | The live version: `id`, `status`, `live`, `message`, `preset_key` and `published_at`, as described under List the published versions, below. | | `urls.live_site` | string | The live help center, on its custom domain when it has one. | | `urls.customizer` | string | The template editor, open on this draft. Send people here to review your changes and to publish them. | | `urls.draft_preview` | string | The draft as a website. It opens only for signed-in members of the help center's team. | ## The design document A help center's design is one document. `GET /v1/template/draft` returns it, and the customization guide describes every part of it. | Part | What it holds | | --- | --- | | `brand` | The help center's name, tagline, logo, dark-mode logo, favicon and main website. When the draft is published, `brand.name` becomes the help center's name everywhere it appears, including the widget, contact form emails and the API. | | `theme` | Colors for light mode (`colors`) and dark mode (`darkColors`), `fonts`, corner `radius` and `density`. | | `meta` | The SEO title and description, social sharing texts and image, text direction and the search engine settings. | | `pages` | Six pages: `home`, `category`, `article`, `search`, `contact` and `notFound`. Each has a `layout`, its own settings, and six regions: `header`, `hero`, `sidebar`, `main`, `footer` and `utility`. A region holds an ordered list of components, and a Hero or Container holds components of its own. | | `syncedRegions` | The regions every page shares (see Synced regions whose pages differ, below). | | `globals` | `navigation`, the menu that every Navigation component draws, and `scripts`, the scripts and snippets injected into the pages. | | `customCssItems` | Labelled blocks of custom CSS. `customCss` is the stylesheet compiled from the enabled blocks, rebuilt on every change. | | `schemaVersion`, `preset` | Kept by HelpCenter.io. You can't set them. | A component is `{id, type, config, visibleOn, children}`. Its `id` is how operations find it, and how custom CSS targets it, with `[data-hc-instance-id=""]`. To see how pages, regions and shared headers look in the template editor, see [Pages, regions and shared headers explained](https://self.helpcenter.io/content/pages-and-regions). Text you set is in the help center's default language. Translations of design texts are made in the dashboard (see [Translate texts in your design](https://self.helpcenter.io/content/translate-design-texts)). The API reads them but can't edit them. When you move or copy a component, its translations go with it, and when you remove it, they go too. ## Read the design GET`/v1/template` Read where the design stands: the draft, the live version, the review link, and an outline of the draft. The outline holds what you need to decide on an edit, without the full document: - `brand`, `theme` and `meta`, in full. - `pages`: for each page, `settings` with its `layout` and the settings that differ from the defaults, and `regions` with each region's components. A component shows its `id`, `type`, the settings that differ from its defaults, and its `children`. Values longer than 120 characters are cut short and large lists are summarized: read them whole with `section=component`. - `sharedRegions`: the synced regions whose pages are the same, listed once instead of on every page. - `syncedButDiverged`: `null`, or an object whose `regions` lists the synced regions whose pages differ, with a `note` on how to choose. Those regions then appear under each page. - `styledByCustomCss` on a region: the labels of the custom CSS blocks that restyle it. A theme's CSS can lay a region out its own way, and whatever you add there is laid out the same way. - `navigation`, `scripts` and `customCss`: lists of ids and labels, without the bodies. `presetStartedFrom` is the theme the document came from. If the help center has no draft yet, for example because no one has opened its design since the help center was created, reading starts a new one from the live design. ## Read the draft document GET`/v1/template/draft` Read the draft document, whole or one part of it. Every answer has `section`, the draft's `etag` and the part you asked for in `data`. The whole document of a theme can be large (the Compass theme's is about 85 KB, most of it custom CSS), so read the part you need. | `section` | Other parameters | `data` | | --- | --- | --- | | `document` (the default) | None | The whole document. | | `brand`, `theme`, `meta` | None | That part of the document. | | `navigation` | None | The menu items. | | `scripts` | `id`, optional | Every script, or the one with that `id`. | | `custom_css` | `id`, optional | Every custom CSS block, or the one with that `id`. | | `page` | `page`, required | One page: its settings and its six regions. | | `region` | `page` and `region`, required | One region: `instances`, its components, and `config`, its styling. | | `component` | `id`, required. `page`, optional | `page`, `region` and `component`: the component with all its settings and children. Add `page` when the id is on several pages. | | `translations` | None | The translated design texts, by language code. An empty list, `[]`, when there are none. | An unknown component id answers `404 Not Found` with `component_not_found`, and an unknown script or CSS block id `404` with `not_found`. ## Read the customization guide GET`/v1/template/schema` Read the customization guide: every operation, component, setting and rule the draft accepts, one topic at a time. The guide is built from the components and settings this API accepts, so it always matches what `PATCH /v1/template/draft` checks. Read it before you change a component's settings. | `topic` | What it holds | | --- | --- | | `overview` (the default) | The model of pages, regions and components, every operation with an example, an index of the components (what each is for, and on which pages and in which regions it can go), this help center's languages, FAQ sections and uploaded fonts, and the limits. | | `components` | Every setting of the component types you list in `types`, comma-separated, up to 8, such as `types=Hero,SearchBar`: its type, allowed values or range, default and description, and what the component can hold. Without `types`, the index of components. | | `settings` | Every path the `set` operation accepts, with the values it takes, and the region styling `update_region` takes. | | `theme` | The color tokens, font formats, radius and density, and the CSS variables they become. | | `css` | How custom CSS is scoped, the hooks for components and regions, dark mode, and what is removed. | | `scripts` | Script positions, kinds, page filters and safety. | | `navigation` | The format of menu items. | ## List themes GET`/v1/template/themes` List the themes you can apply to the draft. Each theme has a `key` and `name`, a `tagline`, `summary` and `best_for`, its light and dark palettes, fonts and density, a `preview_image` and, for some, an `industry`. `current` is `true` for the theme in the draft's `preset_key`. The `blank` theme is an empty canvas: default colors, and no components except an ArticleMetadata on the article page and a ContactForm on the contact page. ## Read a theme GET`/v1/template/themes/{themeKey}` Read one theme, and which sections of the draft applying it would change. One theme adds its `description`, `screenshots` of the home, category, article and search pages and of dark mode and a phone, and `anatomy`, what each page is built from. `changed_sections` lists the sections of your draft that applying the theme would change, and `sections` every section you can apply. ## Apply a theme POST`/v1/template/themes/{themeKey}/apply` Copy a theme onto the draft: every section, or only the ones you name. | Field | Type | Description | | --- | --- | --- | | `sections` | array of strings | The parts of the theme to take. Default: every section, `brand` and `meta` included (see Name your sections, below). Any of `brand`, `theme.colors`, `theme.darkColors`, `theme.fonts`, `theme.radius`, `theme.density`, `pages.home`, `pages.category`, `pages.article`, `pages.search`, `pages.contact`, `pages.notFound`, `globals.navigation`, `globals.scripts`, `meta` and `customCss`. | | `etag` | string | Optional. The draft's `etag` from your last read or write. | - **Each section you apply replaces that part of the draft** with the theme's. Applying a page replaces its components, with new ids, so read the draft again before you edit them. Applying `customCss` replaces your custom CSS blocks. `warnings` says when either happened. - **To borrow a theme's look without its layout**, apply only `theme.colors`, `theme.darkColors`, `theme.fonts`, `theme.radius` and `theme.density`. - **Name your sections.** Without `sections`, every section is applied, `brand` and `meta` included: the draft gets the theme's placeholder name and tagline instead of yours, such as `Help Center`, loses your logo, dark-mode logo and favicon, and takes the theme's SEO title and description, with the no-index setting off. Once published, that placeholder name becomes your help center's name. The template editor leaves `brand` out unless someone ticks it. - The draft's `preset_key` becomes the theme's key, even when you apply only some sections. Nothing changes for visitors until you publish. ## Edit the draft PATCH`/v1/template/draft` Edit the draft with a batch of up to 50 operations, applied in order and all or nothing. | Field | Type | Description | | --- | --- | --- | | `operations` | array | Required. 1 to 50 operations, each an object with an `op` and that operation's fields. | | `etag` | string | Optional. The draft's `etag` from your last read or write. | - **In order.** Each operation sees what the ones before it did. Give a new container your own `id`, and you can add components into it in the same batch. - **All or nothing.** The first operation that can't be applied fails the whole batch with `422 Unprocessable Entity` and `template_invalid`, and nothing is saved, not even the operations before it. - **The template editor's rules.** A component goes only on the pages and in the regions it's made for, a component that's allowed once per region stays unique, a container takes only the component types it accepts, and a setting takes only the values the template editor offers. - **What you get back.** `results` has one entry per operation, in order: `operation` (its position in the batch, from 0), `op`, and what it did, such as the `id` of a new component, CSS block or script, or the `paths` a `set` changed. `template` carries the new `etag`. - **Warnings.** `warnings` points out what is allowed but probably not what you want, such as a script that every visitor will run, a Hero with an image background and no image, a Logo that shows an image when `brand.logoAssetId` is empty, or a batch that left the draft as it was. ### Operations | Operation | Fields | What it does | | --- | --- | --- | | `set` | `path`, `value` | Changes document settings: `brand.*`, `theme.colors.*`, `theme.darkColors.*`, `theme.fonts.*`, `theme.radius.*`, `theme.density`, `meta.*` and `pages..`. An object sets several at once: `{"op": "set", "path": "theme.colors", "value": {"primary": "#1d4ed8", "accent": "#dbeafe"}}`. `null` empties a setting that can be empty. The guide's `settings` topic lists every path. | | `add_component` | `page`, `region`, `type`, `config`, `index`, `parent_id`, `id` | Adds a component. Settings you leave out in `config` get the component's defaults. `index` is its position from 0; leave it out to add it at the end. `parent_id` puts it inside a Hero or Container, whose page and region it takes. `id` is optional: 1 to 64 letters, digits, `-` or `_`, starting with a letter or digit, and not used elsewhere in the draft. A new Hero comes with a SearchBar inside it. | | `update_component` | `id`, `config`, `page` | Changes some of a component's settings. `null` puts a setting back to its default. Add `page` when the id is on several pages of a region that isn't synced. | | `remove_component` | `id`, `page` | Removes a component and everything inside it. | | `move_component` | `id`, `region`, `parent_id`, `index`, `page` | Moves a component on its page: to another region, into a container with `parent_id`, or out to the top level with `"parent_id": null`. With only `id` and `index`, it reorders the component among its neighbors, inside a container too. | | `update_region` | `page`, `region`, `config` | Styles a region: `background` (a hex color or a token such as `var(--hc-color-primary)`), `padding` (`compact`, `standard` or `tall`), `borderBottom` (`true` or `false`) and `align` (`left` or `center`). `null` resets one. | | `sync_region` | `region`, `enabled`, `source_page` | `true` makes every page share the region and copies the `source_page`'s version (default `home`) over the others. `false` lets pages differ. Works on `header`, `hero`, `sidebar`, `footer` and `utility`: `main` always belongs to its page. | | `copy_region` | `region`, `from_page`, `to_pages` | Copies a region that isn't synced from one page to others, once. Later edits don't travel. | | `add_css` | `css`, `label`, `enabled`, `index`, `id` | Adds a labelled custom CSS block. The stylesheet is rebuilt from the enabled blocks, in order. | | `update_css` | `id`, `css`, `label`, `enabled`, `index` | Changes a block, or moves it with `index`. `"enabled": false` keeps the block without applying it. | | `remove_css` | `id` | Deletes a block. | | `add_script` | `position`, and one of `src`, `inlineBody` or `htmlBody`. Optional: `label`, `pages`, `enabled`, `defer`, `async`, `integrity`, `index`, `id` | Injects a script at `headStart`, `headEnd`, `bodyStart` or `bodyEnd`: an external `https` URL in `src`, JavaScript without `