Run translation pass

POST/api/v1/run_translation_pass

Features

Start a REAL translation catch-up run for one or more languages: the same batch the panel's 'Translate now' starts, with pages that are behind translated before pages that are missing. Answers with the job id per language as soon as the runs are open — the pages themselves land over the following minutes and are visible in Translations. It NEVER discards existing translations (that is the owner's 'Re-translate everything'). Every call translates that site chrome for every language asked about — INCLUDING the ones it reports as skipped — so a project whose pages are all current is repaired by an ordinary call.

Price — $0.00001 per call (twice what serving it costs us), charged to the workspace balance, the same as over MCP.

Also reachable by name at POST /api/v1/tools/run_translation_pass.

Input2

Authorizationheaderrequired

Your API key, sent as Authorization: Bearer dbk_YOUR_API_KEY.Sent from your browser straight to the API — never to Docsbook, never stored.

languagesstring[] · body

ISO codes to bring level (default: every language switched on for this project)

forceboolean · body

Run even for a language coverage says is already level with the source (default false)

Output3

okboolean

Whether the tool itself succeeded. A tool that ran and refused — an exhausted balance, a plan restriction, a bad argument — answers 200 with ok: false: the call was made and billed, and that refusal is its answer.

resultobject

The tool's own JSON answer, already parsed — not a string to parse a second time.

Show child attributes1

……

The job id started per language — pages land over the following minutes.

duration_msinteger

Server-side wall time for the call.

Limitations

Languages already level with the source are skipped unless force=true, a language with a live run is left alone, and at most 3 languages are started per call.
🔴 THIS IS ALSO THE CALL FOR 'the pages are translated but the MENU / breadcrumbs / header buttons / tabs / suggested questions are still in English'.
Do NOT reach for force=true to fix English chrome: force re-runs every page in the repo and costs real money to rewrite a few dozen short strings.
REQUIRES PRO or higher.

Responses

200The tool ran. Read ok to see whether it succeeded.

401Missing or invalid API key.

Example input

curl -X POST 'https://docsbook.io/api/v1/run_translation_pass' \
  -H 'Authorization: Bearer dbk_YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{}'

Example output

{
  "ok": true,
  "result": {
    "…": "<…>"
  },
  "duration_ms": 0
}

Updated Sep 24, 2026