The Notiondesk API lets you change the languages your help center serves, choose its default language, and turn automatic AI translation on or off. Use it to roll out a new language across several help centers, or to keep language settings in sync with your own configuration.
| Method | Path | Scope | Does |
|---|---|---|---|
PATCH | /sites/{site_id}/settings/supported-languages | write | Sets the languages served and the default language |
PATCH | /sites/{site_id}/settings/auto-translate | write | Turns automatic translation on or off and sets its source language |
Both routes answer 204 No Content. Read the new state with GET /sites/{site_id}, as described in Read your help centers with the Notiondesk API.
Set the languages your help center serves
curl -i -X PATCH "https://api.notiondesk.so/sites/c74781f6-1aea-4e17-ab23-bbb8b4d174b6/settings/supported-languages" \
-H "Authorization: Bearer $NOTIONDESK_API_KEY" \
-H "nd-version: 2026-10-16" \
-H "Content-Type: application/json" \
-d '{"locales": ["en", "fr", "de"], "default_locale": "en"}'| Field | Type | Notes | Read back as |
|---|---|---|---|
locales | list of strings | Every language the help center serves, at least one. Each must be one of the help center's available_locales | supported_locales |
default_locale | string | The language readers fall back to. Must be in the resulting languages, and cannot be null | default_locale |
A field you leave out keeps its current value.
locales replaces the whole list. A language you leave out is removed from the help center, together with its settings for that language, such as its page title and description. To add a language, read supported_locales first, then send the full list with the new language added.The same addition in JavaScript, keeping the current languages:
const siteId = "c74781f6-1aea-4e17-ab23-bbb8b4d174b6";
const headers = {
Authorization: `Bearer ${process.env.NOTIONDESK_API_KEY}`,
"nd-version": "2026-10-16",
"Content-Type": "application/json",
};
const site = await (await fetch(`https://api.notiondesk.so/sites/${siteId}`, { headers })).json();
const locales = [...new Set([...site.supported_locales, "de"])];
await fetch(`https://api.notiondesk.so/sites/${siteId}/settings/supported-languages`, {
method: "PATCH",
headers,
body: JSON.stringify({ locales }),
});Plan limits
Your plan sets how many languages a help center can serve. A locales list longer than that answers 403 permission_denied.
When your help center stores a language that its supported_locales does not show, every request to this route answers 403 permission_denied, whatever you send. That happens when:
- the help center holds more languages than the plan allows, for example after a downgrade;
- a stored language is disabled;
- the default language has no stored settings and takes one of the plan's places.
Change that help center's languages in the dashboard. The API refuses the change to protect the languages it cannot show you: a request that changed only the default language would otherwise remove them, with their settings. See Support multiple languages in your Help Center.
Turn automatic translation on or off
curl -i -X PATCH "https://api.notiondesk.so/sites/c74781f6-1aea-4e17-ab23-bbb8b4d174b6/settings/auto-translate" \
-H "Authorization: Bearer $NOTIONDESK_API_KEY" \
-H "nd-version: 2026-10-16" \
-H "Content-Type: application/json" \
-d '{"auto_translate_enabled": true, "auto_translate_source_locale": "en"}'| Field | Type | Notes |
|---|---|---|
auto_translate_enabled | boolean | Whether missing translations are produced automatically |
auto_translate_source_locale | string or null | The language automatic translation reads from. Must be one of the help center's supported_locales. null clears it |
Send the JSON booleans true or false. The values 0 and "false" are read as true, which turns billed translation on.
Turning automatic translation on starts translating your help center. The first time, it also turns on translation billing for your workspace. Your plan must include automatic translation. Learn how it works in Getting started with AI automated translation.
What bills translation while it is on
| Action | What is translated |
|---|---|
| Adding a language | The help center's content, into the new language |
| Any sync, scheduled or triggered | The content the sync changed in the source language, and anything not yet translated |
| An article sync on an article with files uploaded to Notion | Every auto-translated language of that article, even with unchanged text |
See Trigger Notion syncs with the Notiondesk API for how syncs translate.
Errors
| Status | code | When |
|---|---|---|
| 400 | validation_error | locales is empty or holds an unavailable language, default_locale is null or not in the resulting languages, auto_translate_source_locale is not one of the help center's languages, or the body has an unknown field |
| 403 | insufficient_scope | The key lacks the write scope |
| 403 | permission_denied | Too many languages for your plan, a stored language is hidden (see Plan limits), your plan does not include automatic translation, or the key's creator cannot change this help center |
| 404 | not_found | The help center does not exist in your workspace |
See Handle Notiondesk API errors, rate limits, and retries for the error envelope and the other codes.
Common questions
How do I add a language without removing the others?
Read the help center's supported_locales, add the new language, and send the whole list as locales. The route replaces the list with what you send.
Which language codes can I use?
The ones in the help center's available_locales, returned by GET /sites/{site_id}.
Can I translate a single article with the API?
No. Automatic translation runs on the whole help center while it is on, and each sync translates what it changed. The API turns it on or off and sets its source language.
Does removing a language delete its articles in Notion?
No. The API never changes your Notion content. Removing a language stops the help center from serving it and removes the help center's settings for that language.