API docs

Authenticate every request with an API key (create one on the API Keys page) sent in the x-api-key header.

The dashboard itself uses short-lived bearer tokens (Authorization: Bearer …); the public API described here uses API keys.

Two routes need no key: GET /v1/meta/languages and GET /v1/meta/plans. Everything that touches a document, a job or an organization needs one.

Send a document and get it back translated, with its layout intact. The call is synchronous by default: the finished document comes back inside the job on a 200.

A large scan can take longer than a connection should be held. syncTimeoutMs caps the wait — from 1000 to 55000 milliseconds. Leave it out and our own budget applies: 55 seconds, sized down for a small document. It can lower that budget and never raise it, so a value above the ceiling is refused with a 400 rather than capped. If the wait passes you get a 202 with the job still running — the work is never cancelled, and GET /translate/jobs/:id has the document once it finishes. Send an Idempotency-Key as well: that is what stops a client with a short timeout from paying twice for the same document.

There are two modes, and the size of the document decides. delivery: "sync" is the default: it holds the connection and hands back the finished document. delivery: "webhook" answers 202 at once, then posts the finished document to the address you name — see Webhooks below.

Above 2 MB, or for any scan, use "webhook". A large document takes minutes, and a 95-page scan takes about a quarter of an hour. A synchronous call gives up before that and answers 202, so you poll for the result anyway. Nothing is refused for being large: the webhook mode saves you the polling.

outputFormat decides the shape of the result and defaults to "json": the document as positioned blocks, each with its source text, its translation, a normalized bounding box and its style. "text" is the plain text, "pdf" is a rendered PDF, and "original" is the source file rewritten in place. The first two are inlined in the result; the last two arrive as a downloadUrl.

What counts as text follows the format. A CSV header row is text, so it is translated with the table under it — read the output by column position, not by column name. JSON keys are not text: only the values change. Subtitle timings and an AWS Transcribe result's own ids come back exactly as they arrived.

Send one document and get it back in several languages, in one call — targetLangs is the list. The response is a batch: batch.jobs is keyed by the language code you asked for, and each value is a whole job — its own status, its own result, its own cost. This endpoint is API-only; the dashboard has no screen for it.

A batch always answers 202, and there is no delivery field to change that: a batch multiplies the work by the number of languages, so a synchronous call could not honour its own name. Poll GET /v1/translate/batches/:id and read batch.status. queued and processing mean ask again; succeeded, partial and failed come back on a 200. partial is the one only a batch has — some languages landed and some did not, and each failure is written on the language it belongs to. batch.usage is the total, and stays null until the batch stops.

Give webhookUrl to be called back instead of polling. That is one delivery per language, each carrying that language's finished document, and it needs no delivery field here — unlike the single-document route, where a URL without delivery: "webhook" is refused. The signing secret, the verification rules and the retry schedule are the ones under Webhooks below.

Every language costs a whole document. 5 languages of a 12-page PDF is 60 credits, with no batch discount: the engine runs once per language and reads the document again each time. The credits for the whole batch are held before any language starts, so a batch that does not fit your allowance is refused whole rather than half-accepted.

usePremiumEngine is accepted here too, and it is the one field on this endpoint that multiplies with the list: a batch of 5 languages redraws the same pages 5 times, at 5 credits a page each. The whole cost is held before any language starts, so a batch that does not fit your allowance is refused whole. It needs outputFormat "pdf" or "original", exactly as on the single-document route.

Ask for delivery: "webhook" and we answer 202 straight away, then post the finished translation to your endpoint. The event carries the document itself, in the same result shape the synchronous call returns — there is nothing to fetch afterwards.

There are two event types, so branch on type rather than assuming: translation.succeeded carries the document in data.result, and translation.failed carries data.result: null with the reason in job.error. job.usage is null when nothing was measured, which is most failures, and says what the job cost when the engine had already run before it failed — usually zero, and not always. That is what makes it add up to GET /v1/usage. Both are signed the same way.

Create a signing secret first, on the API keys page of your dashboard. That page is the only door: the route behind it takes a signed-in session, never an API key, because a key that could read what signs our deliveries could forge one. Without a secret a webhook translation is refused with a 400 rather than delivered unsigned. Rotating takes effect immediately, with no overlap window.

• Compute the HMAC-SHA256 of <t>.<raw body> with your secret, over the body exactly as received. Parsing and re-serializing changes the bytes, and the signature will not match.
• Compare in constant time — hash_equals, hmac.compare_digest, timingSafeEqual.
• Refuse a t more than 5 minutes old. That is what makes a captured delivery useless to replay.
• Tranly-Event-Id is the same on every attempt of one delivery: use it to recognise a retry you already handled. Ignore signature pairs you do not know, so a future v2= cannot break your receiver.

A delivery is accepted on any 2xx within 10 seconds. Anything else is retried on the schedule opposite, up to six attempts; 410 Gone stops us for good. We never follow redirects, so a 3xx is a failed attempt — give us the final address.

We deliver to https on port 443 only, and only to a public address: localhost, 127.0.0.1 and the private ranges are refused, and the address is checked again inside the connection itself. While you develop, that means a public tunnel. Nothing of ours travels with the request except the signature. Track it on the job: job.webhook carries the status, the attempt count, and why the last attempt failed.

Fetches one translation by id. You need it in two cases: a synchronous call that ran out of time answered 202, and the document is here once it finishes; or you asked for a webhook and want to see how the delivery went, which job.webhook reports. Binary results carry a downloadUrl plus a suggested filename; text results are inlined.

downloadUrl is a data: URI, not a link to a file. The document travels inside the response, so there is nothing to fetch and nothing that expires — decode it rather than handing it to a downloader. It also means a big result is a big response: a 95-page scan is several megabytes of JSON.

result.notices says why part of a document came back in the language it went in as. The key is absent on a clean run, so its presence is the signal. Each entry carries a code and how much it covers: esign_record_kept (a signature certificate is an audit record, so we return it verbatim), segments_untranslated (passages we tried and did not land), no_translatable_text, wrong_target_language (passages delivered in neither the source's language nor the one you asked for), and premium_engine_unavailable (pages you asked the premium engine to redraw and it did not — translated the standard way, and charged the standard rate). Read it: the page looks finished either way.

The HTTP code says whether the job is finished; job.status says whether it worked. A translation that failed is still a 200.

Synchronous plain-text translation — no job, the translation comes back in the response.

Take personal data out of a PDF or an image. The data leaves the file — the text is removed, not painted over — and the rest of the page stays the same. Two calls: POST /redact/detect answers with the areas it proposes, page by page, and POST /redact/apply removes the areas you send back. Read a job with GET /redact/jobs/:id. POST /redact does both in one call, for an integration with no review.

A detection costs 1 credit a page. An apply that names a detection of the same file from the last 24 hours in detectionJobId costs nothing. The result is always a PDF, and we read it again before we hand it back: a job whose covered text is still readable fails instead. Pro plan and above. A lower plan gets one free test of a short document, and a 403 after it: GET /redact/trial answers with the page ceiling and whether the test is open. delivery, webhookUrl and Idempotency-Key work as on /translate/document.

Send an AWS Transcribe result and get the same result file back, translated. Upload it as any other document — a .json that carries results.transcripts or results.audio_segments is recognised on its own — or name it explicitly with source.kind: "transcribe". With outputFormat: "original" the response is a Transcribe result your existing pipeline can read without a change.

The translation unit is the speech segment, never the word. jobName, accountId, status and every speaker_label survive byte-exact, segment start_time/end_time are the recognition's own and never move, and results.transcripts, results.items and speaker_labels are rebuilt to keep agreeing with the translated segments.

One limit, stated plainly: word-level times are estimates. A translated sentence has a different number of words, so no word carries the old word's timestamp — we distribute the segment's real span across the new words by length. Segment boundaries are exact; if you build word-highlighted captions off items, that is the field to know about. confidence is likewise inherited from the segment, because the recognition was confident about speech we did not re-recognise.

A prompt is your organization's house style — voice, register and terminology — applied on top of the engine's translation rules. Write and edit them on the Prompts page of your dashboard, then name one from a translation with promptId. Writing one takes a signed-in session; naming one, and reading one back, take any credential — so an integration only ever sends the id.

Prompts are named, never inlined: raw instructions in a translation body are rejected, so the text that reached the model is always a record you can look up. An id belonging to another organization is a 404.

The answer names the style that ran: promptId comes back on POST /translate/text and on every read of a job, and is null when none was named. Resolve it with GET /v1/prompts/:id — that read, and the list, take your API key as well as a session.

Everything is metered in credits. One credit is one page of a document, or 2,500 characters of plain text rounded up, with a minimum of one credit per request. A text translation reports what it cost in usage.credits; a document reports it in job.usage once the job finishes, with the page count and the OCR page count beside it.

A scanned page costs the same as a native one — there is no OCR surcharge, so a photographed invoice and a text PDF of the same length bill identically. Which model translates is ours to choose, so a page costs the same whichever one we happen to be running. The one exception is the premium image engine: usePremiumEngine redraws a page — every page of a PDF, an image, or a picture inside an office file — with an image model at 5 credits instead of 1, and only the pages it really drew are multiplied — job.usage.premiumPages counts them.

Running out returns 429 with code QUOTA_EXCEEDED. A file larger than your plan allows returns 400, and the message names both sizes: the ceiling is 12 MB on every plan, Free included, and base64 adds about a third to a file. GET /v1/usage answers your allowance and what is left of it — with a key or a session.

Non-2xx responses share one envelope, a route that does not exist included. Branch on code: it is stable and upper-case, while the message is written for a person and may be reworded.

Every response carries the rate limit in force for the route you called, so you can pace yourself without waiting for a 429: x-ratelimit-limit, x-ratelimit-remaining, and x-ratelimit-reset in seconds. A 429 adds retry-after. The default is 300 requests per 60 seconds, per address, counted across every route including the public ones; sign-in is deliberately tighter. Read the headers rather than the number — they are the ones that answer for the route you are on.

Each API key also has a ceiling of requests per minute, set by your plan. It counts every request sent with x-api-key, in a window of 60 seconds per key. Two routes are not counted, so you can poll a result as often as you need: GET /v1/translate/jobs/:id and GET /v1/translate/batches/:id. A request past the ceiling returns 429 with code API_KEY_RATE_LIMITED and retry-after in seconds. A dashboard session is not counted.

Idempotency-Key applies to POST /translate/document and POST /translate/documents, which leave a job or a batch to replay. POST /translate/text refuses the header with a 400: its answer is the translation itself, so there is nothing to replay, and accepting it would suggest a protection you do not have.