Customize help center branding and themes with the Notiondesk API

The Notiondesk API lets you read and change your help center's branding: colors, fonts, layout, header and footer, links, search and feedback display, and theme. Use it to roll out the same brand across several help centers, or to keep your branding in code next to the rest of your design system.

Branding is visible on every public page, so updating it needs the admin scope, not write. Only a key created by a workspace owner or Admin holds admin.

To change branding in the dashboard instead, see Customize your help center colors and fonts.

What the API does not change

These stay dashboard-only. The read route does not return them, and an update that names one answers 400 validation_error:

• custom CSS and custom JavaScript. See Customize your help center with custom CSS;

• logos (light and dark), footer logos (light and dark), favicon, social media image and header images (light and dark).

Read your branding

curl "https://api.notiondesk.so/sites/c74781f6-1aea-4e17-ab23-bbb8b4d174b6/settings/customize" \
  -H "Authorization: Bearer $NOTIONDESK_API_KEY" \
  -H "nd-version: 2026-10-16"

The response holds exactly the fields the update accepts, under the same names. A shortened example:

{
  "colors": {
    "primary": "#2563eb",
    "text": "#111827",
    "link": "#2563eb",
    "link_hover": "#1d4ed8",
    "header": "#2563eb",
    "header_text": "#ffffff",
    "background": "#ffffff",
    "footer_background": ""
  },
  "appearance": null,
  "layout_collection": "column_2",
  "layout_article": "column_1",
  "footer_layout": "compact",
  "primary_font": "Inter",
  "header_links": [{"title": "Docs", "url": "https://example.com/docs"}],
  "footer_links": [{"title": "Product", "links": [{"title": "Pricing", "url": "https://example.com/pricing"}]}],
  "show_powered_by_badge": false,
  "theme": null
}

• A color that was never set reads "". colors.dark holds the dark mode colors, and is absent when the help center has no dark palette.

• A list that holds nothing reads [].

• theme is the code of the current theme, or null.

Update your branding

curl -i -X PATCH "https://api.notiondesk.so/sites/c74781f6-1aea-4e17-ab23-bbb8b4d174b6/settings/customize" \
  -H "Authorization: Bearer $NOTIONDESK_API_KEY" \
  -H "nd-version: 2026-10-16" \
  -H "Content-Type: application/json" \
  -d '{"primary_font": "Inter", "colors": {"primary": "#2563eb"}, "header_links": [{"title": "Docs", "url": "https://example.com/docs"}]}'

The route answers 204 No Content. Read the branding again to confirm the change.

• A field you leave out keeps its value. Inside colors, a color you leave out keeps its value too.

• A list you send replaces the whole stored list, and [] empties it.

• Colors are #rrggbb hexadecimal values, or "". Short forms such as #fff are rejected.

• Send JSON booleans. The values 0 and "false" are read as true, and null as false.

Every accepted update refreshes the whole help center: Notiondesk clears its cached pages and rebuilds every page, whatever the update changed. Send every change in one request, not one request per field.

Safe updates: read, change, send back

The safest way to update branding is to send back what you read, with your changes applied. A field sent with its current value is accepted on any plan, so this pattern never trips a plan limit on fields you did not touch.

const url = "https://api.notiondesk.so/sites/c74781f6-1aea-4e17-ab23-bbb8b4d174b6/settings/customize";
const headers = {
  Authorization: `Bearer ${process.env.NOTIONDESK_API_KEY}`,
  "nd-version": "2026-10-16",
  "Content-Type": "application/json",
};

const branding = await (await fetch(url, { headers })).json();
branding.colors.primary = "#7c3aed";
branding.colors.link = "#7c3aed";

const response = await fetch(url, { method: "PATCH", headers, body: JSON.stringify(branding) });
console.log(response.status);

A body sent back can still be refused in two cases. Fix the value in the dashboard, or leave that field out of the body:

• a stored color in a short form such as #fff;

• a stored list longer than the limits below.

Fields you can change

Links are objects with a title and a url. Footer link groups are objects with a title and a links list. Translations are objects with a locale and the translated links, groups or value.

Plan limits

Changing one of them on a plan without the feature answers 403 permission_denied, the message names the feature, and nothing is written.

Without advanced customization, the footer colors keep their stored value with no error. Without an enabled AI chatbot, ai_search_display_mode, ai_search_aside_position and ai_search_enabled: true also keep their stored value.

List limits

• Each list holds up to 100 entries, and so does each links or groups list inside it.

• All lists together hold up to 3,000 entries, counting nested entries and the stored lists your body leaves out.

The contact button turns the contact form on

While show_contact_us_button is true on a plan with advanced customization, every branding update turns the help center's contact form on, as a save in the dashboard does. See the contact form section of Update help center settings with the Notiondesk API.

Choose a theme

curl "https://api.notiondesk.so/sites/c74781f6-1aea-4e17-ab23-bbb8b4d174b6/themes" \
  -H "Authorization: Bearer $NOTIONDESK_API_KEY" \
  -H "nd-version: 2026-10-16"

{
  "object": "list",
  "data": [
    {
      "code": "ocean",
      "name": "Ocean",
      "description": "A calm, airy theme",
      "preview_image_url": "https://example.com/ocean.png",
      "layout": "default"
    }
  ],
  "has_more": false,
  "next_cursor": null
}

The list always holds every theme in one response, in display order. Apply one by sending its code as theme:

curl -i -X PATCH "https://api.notiondesk.so/sites/c74781f6-1aea-4e17-ab23-bbb8b4d174b6/settings/customize" \
  -H "Authorization: Bearer $NOTIONDESK_API_KEY" \
  -H "nd-version: 2026-10-16" \
  -H "Content-Type: application/json" \
  -d '{"theme": "ocean"}'

Setting a theme needs advanced customization. Sending "theme": null leaves the theme unchanged.

Errors

Field errors name the value, for example colors.primary or footer_links[0].links. See Handle Notiondesk API errors, rate limits, and retries.

Common questions

What's next

• Update help center settings with the Notiondesk API

• Manage help center integrations with the Notiondesk API

• Automate common help center tasks with the Notiondesk API