API Reference
1.0.0

Supertext API

Introduction

A RESTful API for translating text with AI, and for finding out what a translation will cost before you ask for it.

Use Cases

/translate/ai/text translates plain text instantly with large language models. Use it to make a website or an application available in more languages.

/translate/ai/file translates a whole document and gives it back in the same format. It answers with a file_id rather than a translation, because extracting, translating and reassembling a document takes longer than a request should stay open; poll the id and download the result when it is ready.

/translate/fused/text translates text and has a human expert review the result before you get it. Use it for the copy you cannot afford to get wrong — key messages, legal or safety-critical wording, the pages most of your users see. It answers with an id to poll rather than a translation, because a person has to do the work; delivery is minutes during covered hours.

/translate/fused/file is the same service for a whole document: it is translated and a reviewer works on the result, and what you download at the end is the reviewed document, not a machine translation of it.

Adding a briefing to either request orders Optimisation instead of Verification: the reviewer works to your instructions — tone, audience, what the text is for — rather than only checking that the translation is correct. It is the same endpoint and the same call sequence; the briefing changes the price, the delivery time and how much text you may send.

/detect-languages/text identifies the language a text is written in. If your goal is to translate text whose language you do not know, you do not need this endpoint — omit source_lang from the translation request instead and the answer comes back as detected_source_lang, at no extra cost.

The supported language pairs, and which features each pair supports, come from /features. Languages are BCP 47 tags.

Authentication

Every endpoint requires an API key. Workspace admins create and revoke keys in the Supertext workspace under API keys; a key belongs to one workspace and inherits that workspace's plan, entitlements and billing.

The key goes in the Authorization header as a bearer token:

Authorization: Bearer st_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

A key is shown once, when it is created, and stored only as a hash — so it cannot be recovered afterwards, only replaced. Revoking a key takes effect immediately.

Usage Costs

These endpoints incur usage costs:

  • /translate/ai/text
  • /detect-languages/text
  • /translate/ai/file
  • /detect-languages/file
  • /translate/fused/text
  • /translate/fused/file

Each has a /quote sibling that takes the same payload and answers what the real call would cost. Validation runs there too, so a quote doubles as a dry run: an unsupported language pair or an oversized request fails on the quote exactly as it would on the translation.

A quote answers prices, keyed by lower-case currency code — one entry, your workspace's own billing currency. It is deliberately not rounded to the cent, because nothing is charged per request: usage accrues in characters and is priced on the accumulated total, so a single request's share of the bill is a fraction of a cent and that fraction is what you are told.

Human review is charged differently from machine translation, because it is different work. A /translate/fused/text order is priced per word of your source text, with a minimum charge per order, and the amount is taken from your credit balance the moment the order is accepted — the same price the same service costs when ordered from the Supertext workspace. The machine translation that produces the reviewer's draft is included in that price; it is not metered separately, in the same way that detecting the language of a translation you did not label costs nothing extra.

API and MCP usage draws on your plan's quota first. Each plan includes a quota of characters per month (per year on a yearly plan), shared by this API and the MCP server, and it resets with your billing period. Only the characters past it are charged. It is separate from the characters included for use of the Supertext workspace itself, which API usage never draws on.

Characters past the quota are paid from the workspace's credit balance. A request whose slice past the quota the balance cannot cover is refused with 402 rather than queued, and the response's reason says which case it is: insufficient_credit means top up (or switch automatic top-up on, which is what an unattended integration wants). Usage accrues in characters and is priced periodically, so a 402 reflects what is already owed plus what you just asked for.

Limits

Size limits cap one request; rate limits cap how many requests you may send per second, per key. Exceeding a rate limit returns 429 with a Retry-After header — read that header rather than hardcoding a backoff.

EndpointSizeRate
/translate/ai/text10,000 characters, 100 terms5/s
/translate/ai/text/quotesame10/s
/detect-languages/textfirst 500 characters read10/s
/detect-languages/text/quotesame10/s
/translate/ai/file30 MiB1/s
/translate/ai/file/quotesame10/s
/detect-languages/file30 MiB1/s
/detect-languages/file/quotesame10/s
/translate/fused/text3,000 characters, or 12,000 with a briefing1/s
/translate/fused/text/quotesame10/s
/translate/fused/file30 MiB1/s
/translate/fused/file/quotesame10/s
/features—10/s
/webhooks (every method)10 webhooks per workspace1/s
/webhooks/{webhook_id}/test—1 per 5 s

This list is not exhaustive, and limits may change without a new API version.

Errors

Every error is application/problem+json (RFC 9457):

{
  "type": "urn:supertext:error:validation_error",
  "title": "Unprocessable Entity",
  "status": 422,
  "detail": "body.target_lang: unsupported target language",
  "code": "validation_error",
  "error_id": "9f1c7a2e"
}

detail is always a string and is safe to show to a person. code is the stable slug to branch on in code. Errors carry an error_id; quote it when reporting a problem.

Response headers

Every response carries an X-Request-ID, also returned as request_id in the bodies that have one; quote it with any support request. A 429 carries Retry-After (seconds) and a 401 carries WWW-Authenticate. A download carries Content-Disposition with the file name. The rest — Cache-Control, Strict-Transport-Security, Content-Security-Policy, X-Content-Type-Options, X-Frame-Options, Referrer-Policy, Permissions-Policy — are standard security headers a client can ignore.

Webhooks

Instead of polling, register a webhook: an HTTPS URL that we call when something happens — a translation finishes, or the workspace needs attention. Polling keeps working; a webhook tells you when to look.

A webhook belongs to the API key that created it. A key lists, changes, tests and deletes only its own webhooks, and translation events go only to the webhooks of the key that started the translation. Workspace events go to every webhook in the workspace that subscribed to them. A webhook stops when its key is revoked or expires. A workspace can have up to 10 webhooks.

A webhook subscribes to an explicit list of event types; there is no wildcard.

Event typeSent whenSample data
translation.ai_file.completedAn API-started AI file translation finishes successfully.{"file_id": "b0f3a1d84c6e4a7f9c2e5d1b8a7f6e30"}
translation.ai_file.failedAn API-started AI file translation fails.{"file_id": "b0f3a1d84c6e4a7f9c2e5d1b8a7f6e30", "error": "The document could not be translated."}
translation.fused_text.completedAn API-ordered Fused text translation is delivered.{"translation_id": "0e9b7c52-6a1d-4f3e-8b2a-9c4d5e6f7a81"}
translation.fused_file.completedAn API-ordered Fused file translation is delivered.{"translation_id": "7d3f9a12-4b6c-4e8d-a1f2-3c5b7d9e0f14"}
translation.fused_file.failedAn API-ordered Fused file translation fails.{"translation_id": "7d3f9a12-4b6c-4e8d-a1f2-3c5b7d9e0f14", "error": "The document could not be translated."}
wallet.low_balanceThe wallet balance newly drops below its low-balance threshold.{"currency": "CHF", "balance": "18.40"}
wallet.topped_upA wallet top-up is finalised, manual or automatic.{"top_up_id": "c41a8e3d-2b7f-4d9a-8e1c-6f5b3a2d9e07", "currency": "CHF", "amount": "200.00", "balance": "218.40"}
invoice.issuedAn invoice PDF is issued.{"invoice_id": "a9e2d7c4-1f3b-4a6e-9d8c-2b5f7e1a3c60", "issued_at": "2026-11-01T00:04:31Z"}
subscription.payment_failedThe subscription goes past due after a failed payment.{"plan_code": "growth"}
subscription.payment_recoveredThe subscription is restored after a payment succeeds.{"plan_code": "growth"}
api_key.expiringAn API key is 30 days, and again 7 days, from its expiry.{"api_key_id": "3e7b1d9f-5c2a-4f8e-b6d1-8a4c2e9f7b35", "name": "CMS plugin", "expires_at": "2026-12-01T09:00:00Z", "days_left": 30}
api_key.revokedAn API key is revoked.{"api_key_id": "3e7b1d9f-5c2a-4f8e-b6d1-8a4c2e9f7b35", "name": "CMS plugin", "revoked_at": "2026-10-28T15:42:07Z"}

Good to know about individual events. Some events have conditions the table does not show:

  • api_key.revoked is never sent to the webhooks of the key that was revoked: they are deleted first. Only the workspace's other webhooks hear of it.
  • wallet.low_balance is sent at most once every 24 hours per wallet, not when a wallet is first seen, nor after its threshold is changed. It is sent only when the balance crosses below the threshold.
  • invoice.issued is sent only when the invoice is issued within 24 hours of its payment; an invoice that turns up later is not announced. invoice.issued issued_at is the invoice date, which is the payment time; for a top-up the invoice_id equals the top_up_id.
  • wallet.topped_up amount is the credits added, not the price paid. In every event, amounts are strings with 2 decimal places and the currency is upper-case, for example "18.40" and "CHF".
  • api_key.expiring is sent at 30 days and again at 7 days before expiry, at most one warning per hourly run: a key first seen inside the 7-day window gets only that one.
  • translation.fused_file.completed can be held for up to 5 minutes, until the translated document is ready to download.

Payloads never contain content. An event carries ids, statuses and amounts — never text, documents or download links. Fetch the result with your API key, from the endpoint you would otherwise poll. The error of a failed event is always the same generic message; call that endpoint's /status for the detail.

Every event is a POST with a JSON body:

POST https://cms.example.com/hooks/supertext
content-type: application/json
user-agent: Supertext-Webhooks/1
webhook-id: 2f6c1b0e-9d4a-4e37-8c15-7a3b9e2d4f60
webhook-timestamp: 1761656713
webhook-signature: v1,K5oZfzN95Z9UVu1EsfQmfVNQhnkZ2pj9o9NDN/H/pI4=

{"type":"translation.ai_file.completed","timestamp":"2026-10-28T13:05:12Z","data":{"file_id":"b0f3a1d84c6e4a7f9c2e5d1b8a7f6e30"}}

timestamp in the body is when the event happened, in UTC; webhook-timestamp is when this attempt was sent, in Unix seconds.

Verify every request. Requests are signed the Standard Webhooks way: webhook-signature is v1, followed by the base64 HMAC-SHA256 of {webhook-id}.{webhook-timestamp}.{body}, keyed with your secret (the base64 part after whsec_, decoded). Check it against the raw body, before any JSON parsing, and reject a request whose timestamp is more than a few minutes old. The Standard Webhooks libraries do all of this. In Python, with the standardwebhooks package:

from standardwebhooks.webhooks import Webhook

webhook = Webhook(secret)  # the whsec_... value from the create response
event = webhook.verify(raw_body, headers)  # raises unless the request is ours

Libraries exist for JavaScript, PHP, Go, Java, Ruby, C#, Rust and more; see standardwebhooks.com.

Source IPs are not fixed. Requests can come from any address and the addresses change without notice, so verify the signature instead of allowlisting IPs.

Answer with a 2xx, quickly. Any 2xx is a success. Anything else — another status, a redirect (never followed), or no answer within 10 seconds — is a failed attempt. Answer first and do the work afterwards.

Retries. After each failed attempt the event is sent again, waiting 5 s, 5 min, 30 min, 2 h, 5 h, 10 h, 10 h in turn. After the 8th failed attempt it is given up.

At least once, in any order. An event can arrive more than once: webhook-id is the same on every retry, so deduplicate on it. Events are not guaranteed to arrive in the order they happened.

Disabled webhooks. A webhook that answers 410 Gone is disabled at once. One that has failed 20 attempts in a row and not succeeded for 5 days is disabled too; the 5 days run from the last success, or from when you created or re-enabled the webhook, whichever is latest. A disabled webhook shows status: disabled with a disabled_reason (gone or failing), and the events still waiting for it are cancelled. Once your endpoint is fixed, re-enable it with PATCH /webhooks/{webhook_id} and {"enabled": true}.

Testing. POST /webhooks/{webhook_id}/test sends a webhook.test event straight away, with data set to {"webhook_id": "5b0c1e7a-3d2f-4c8e-9a61-2f7d8e4b1c90"}, and answers with what your endpoint replied. It is not retried and does not count as a failure. You cannot subscribe to webhook.test.

Server
https://api-platform.supertext.com/v1
AuthenticationOptional
Name:Authorization
Value:

Text Translation

Translate plain text with AI or human assistance, or request a quote before ordering.

POST/translate/ai/textCosts

AI translation

Translate plain text, with optional glossary terms, formality control and tag handling.

This endpoint incurs usage costs.

Send one or several strings in text; each is translated independently and the results come back in the same order. Omit source_lang to have it detected — the detected language is reported as detected_source_lang, and detection costs nothing extra because the translation pays for the text anyway.

Ask /features whether the pair you want supports politeness or a glossary. Sending either for a pair that does not support it is refused rather than silently ignored.

Limits: 10,000 characters per request (the total across text), 100 glossary terms, 5 request(s) per second.

Request Body
application/json
Response
200
Add your API key to send requests

One string, from a stated source language into one target variant.

Editable

This request will incur usage costs

POST/translate/ai/text/quote

AI translation quote

What a translation would cost.

Takes the same payload as /translate/ai/text, so you can price the exact call you are about to make by re-sending it. Nothing is translated, nothing is metered, and no usage is recorded. Validation still runs, which makes this a dry run as well as a price.

prices gives what these characters cost, keyed by your workspace's billing currency in lower case ({"chf": 0.00056}). The price is what the request would cost beyond your plan's API & MCP quota at the time of the quote, so it is 0.0 while the request fits inside the quota. It is not rounded to the cent, because usage is priced on an accumulated character total rather than per request.

Quotes are not gated on your balance: the moment you most need to ask the price is the moment you have run out.

Limits: 10 request(s) per second.

Request Body
application/json
Response
200
Add your API key to send requests

One string, from a stated source language into one target variant.

Editable
POST/translate/fused/textCosts

Fused translation

Translate text and have a human expert review the result.

This endpoint incurs usage costs.

This is an asynchronous operation: several HTTP requests are needed to get the finished text.

  1. (optional) Ask /translate/fused/text/quote what it will cost and when it will be delivered. Same payload, nothing charged.
  2. POST /translate/fused/text. Keep the translation_id from the response.
  3. Poll GET /translate/fused/text/{translation_id}/status — once a minute is a sensible interval. estimated_duration_left_in_seconds tells you how long is left, and goes negative if the promised time has passed.
  4. When status is completed, fetch the text from GET /translate/fused/text/{translation_id}/translation.

The price covers the whole thing — the machine translation and the review. /translate/fused/text/quote reports it before you commit.

A briefing orders Optimisation instead of Verification. Without one, a reviewer checks that the translation is correct. With one, the reviewer also works the text to your instructions. You will get back briefing_applied so you can tell which service you bought without parsing the name, and service_label for showing a person. Branch on the boolean, not the label — the names may change.

source_lang is required here, unlike on /translate/ai/text: the order is priced and routed to a linguist before anything is translated, and both need the language pair up front.

Not every language pair can be reviewed by a human — it depends on there being a linguist for that direction. /features marks the ones that can with supports_fused_translation. Sending an unsupported pair is refused before anything is charged.

Limits: 3,000 characters per request, or 12,000 with a briefing; 1 request(s) per second.

Request Body
application/json
Response
202
Add your API key to send requests

A reviewer checks that the translation is correct. This is the default.

Editable

This request will incur usage costs

GET/translate/fused/text/{translation_id}/status

Fused translation status

Where a human-assisted translation has got to.

in_progress covers everything before delivery, whether or not a reviewer has started. completed means the text is ready to fetch. failed means the order was cancelled and no text is coming — check it rather than polling forever.

estimated_duration_left_in_seconds counts down to the delivery time promised when the order was placed. A negative number means that time has passed; the order is still being worked on, and the number says by how much it is late.

Parameters
Response
200
Add your API key to send requests
GET/translate/fused/text/{translation_id}/translation

Fused translation download

Download a human-assisted translation once a reviewer has delivered it.

202 with "status": "in_progress" while the order is still open — the id is valid, the text just is not ready. Poll the status endpoint rather than retrying this one on a tight loop.

The text stays available for as long as the order is kept in your workspace, so you can fetch it more than once.

Parameters
Response
200
Add your API key to send requests
POST/translate/fused/text/quote

Fused translation quote

What a human-assisted translation would cost, and when it would be delivered.

Takes the same payload as /translate/fused/text, including the briefing, which is what decides both numbers. Nothing is translated, nothing is metered, no order is placed and no reviewer is engaged.

prices is what the call costs, in your workspace's billing currency: the review, priced per source word with a per-order minimum. The machine translation is included in it. word_count is the unit the price is computed from, so you can see where the number comes from.

estimated_duration_in_seconds is measured from now and accounts for our review hours, so a request sent at the end of a working day is quoted longer than the same request sent at the start of one. It is an estimate, not a guarantee.

Validation runs here too, so this doubles as a dry run: an unsupported pair, an oversized text or a service we cannot currently deliver fails on the quote exactly as it would on the order.

Quotes are not gated on your balance.

Limits: 10 request(s) per second.

Request Body
application/json
Response
200
Add your API key to send requests

A reviewer checks that the translation is correct. This is the default.

Editable

File Translation

Translate documents with AI or human review, follow progress, and download the result.

POST/translate/ai/fileCosts

AI file translation

Translate a document and get it back in the same format.

This endpoint incurs usage costs.

Send the file as multipart/form-data. This is an asynchronous operation:

  1. (optional) Ask /translate/ai/file/quote what it will cost. Same form body, nothing charged.
  2. POST /translate/ai/file. Keep the file_id from the response.
  3. Poll GET /translate/ai/file/{file_id}/status — every few seconds is plenty.
  4. When status is done, download the translated document from GET /translate/ai/file/{file_id}/translation.

Supported formats: DOCX, PPTX, XLSX, PDF, HTML, TXT, SRT. A PDF comes back as a DOCX, because a translated PDF has to be rebuilt as an editable document.

use_ocr applies to PDFs only. Set it when the document is a scan, or when its text layer is unreliable — leaving it off on such a file yields an empty or garbled translation rather than an error.

glossary is a JSON object of source → target terms, sent as a string inside the form field. At most 100 terms.

You are charged for the characters the document turns out to hold, which is not knowable until it has been extracted. The upload checks that your balance can be charged at all and refuses immediately if it cannot; the real charge lands when the translation finishes.

Limits: 30 MiB per file, 1 request(s) per second.

Request Body
multipart/form-data
Response
202
Add your API key to send requests

Supported: DOCX, PPTX, XLSX, PDF, HTML, TXT, SRT

This request will incur usage costs

GET/translate/ai/file/{file_id}/status

AI file translation status

Where a file translation has got to.

translating covers everything before the document is ready — extraction, translation and reassembly are our stages, not yours. Then done, or error with a message, or deleted if you withdrew the document.

Polling this is also what finalises the charge for the translation, so keep polling until you see a terminal status.

Parameters
Response
200
Add your API key to send requests
GET/translate/ai/file/{file_id}/translation

AI file translation download

Download the translated document once it is ready.

The response is the file itself, with a Content-Disposition header — not JSON. A PDF you uploaded comes back as a DOCX.

202 with "status": "in_progress" while the document is not ready yet: the id is valid, the translation just is not finished. Poll the status endpoint rather than retrying this one in a tight loop.

Translations stay available for 24 hours.

Parameters
Response
200
Add your API key to send requests
DELETE/translate/ai/file/{file_id}

AI file translation delete

Delete an uploaded document before its retention window elapses.

The document is removed from storage, together with its translation and everything extracted from it. Use this when you have uploaded something confidential and do not want to wait 24 hours for it to expire.

Deleting the same id twice answers the same both times. A translation already finished has already been charged for; deleting the document does not undo that.

Parameters
Response
200
Add your API key to send requests
POST/translate/ai/file/quote

AI file translation quote

What translating a document would cost.

Send exactly the request you would send to /translate/ai/file. Every field that endpoint takes is accepted here, so pricing a call means re-sending it rather than rewriting it. Nothing is translated, nothing is metered and no job is created.

Most of those fields cannot change the price — characters cost the same in every language, and neither a glossary nor a politeness setting adds any — but they are validated here anyway, so a request that would be refused by the translation is refused by its quote.

The price is what the request would cost beyond your plan's API & MCP quota at the time of the quote.

use_ocr does change the price. It decides how a PDF's text is read, and therefore how many characters the document turns out to hold: quote a scan without it and you are pricing a document that appears to be empty, while the real charge lands on everything OCR finds. Send the same value you will order with.

The document does have to be read to count its characters, so this takes about as long as an extraction — it is a dry run for the price, not for the time. With use_ocr, it takes about as long as OCR: a large scan can take a while, and the answer is worth the wait only because the alternative is a price for a document that appears to be empty.

Limits: 30 MiB per file, 10 request(s) per second.

Request Body
multipart/form-data
Response
200
Add your API key to send requests

Supported: DOCX, PPTX, XLSX, PDF, HTML, TXT, SRT

POST/translate/fused/fileCosts

Fused file translation

Translate a document and have a human expert review the result.

This endpoint incurs usage costs.

Send the file as multipart/form-data. One call places the whole order — the document is translated and a reviewer takes it from there:

  1. (optional) Ask /translate/fused/file/quote what it will cost and how long it will take. Same form body, nothing ordered.
  2. POST /translate/fused/file. Keep the translation_id from the response.
  3. Poll GET /translate/fused/file/{translation_id}/status — once a minute is plenty. It stays in_progress while the document is being translated and while it is being reviewed.
  4. When status is completed, download the reviewed document from GET /translate/fused/file/{translation_id}/translation.

Supported formats: DOCX, PPTX, XLSX, PDF, HTML, TXT, SRT. A PDF comes back as a DOCX, because a translated document has to be rebuilt as an editable one.

source_lang is required here, as it is for text: the review is priced and routed to a linguist before anything is translated, and both need the pair up front.

The price is the service's, per source word of your document, and the machine translation is included in it. It is not knowable until the document has been extracted, so this call checks that your balance can be charged at all and the real debit lands when the order is placed. If your balance no longer covers it by then, status answers failed with that as the reason.

Limits: 30 MiB per file, 1 request(s) per second. There is no character cap: a document too large to promise a delivery date for is refused with a 422 pointing at a manual quote.

Request Body
multipart/form-data
Response
202
Add your API key to send requests

Supported: DOCX, PPTX, XLSX, PDF, HTML, TXT, SRT

This request will incur usage costs

GET/translate/fused/file/{translation_id}/status

Fused file translation status

Where your order has got to.

in_progress covers both phases — the machine translation and the human review. completed means the reviewed document is ready to download. failed means the order will not be delivered, and error says why: the document could not be translated, it held no text to review, or your balance did not cover the price when the order was placed.

estimated_duration_left_in_seconds counts down to the promised delivery once a reviewer has the document, and is 0 before that. A negative number means the promise has passed.

Parameters
Response
200
Add your API key to send requests
GET/translate/fused/file/{translation_id}/translation

Fused file translation download

Download the reviewed document.

Answers the document itself, with the reviewer's changes patched back into it, under a Content-Disposition filename — not JSON. It is a DOCX: a PDF is converted on the way in, and what comes back is the document as it was translated.

202 with "status": "in_progress" until a reviewer has delivered. The machine translation exists long before that, and handing it back here would sell you a draft as a reviewed document. Poll the status endpoint rather than retrying this one on a tight loop.

Parameters
Response
200
Add your API key to send requests
POST/translate/fused/file/quote

Fused file translation quote

What a human review of this document would cost, and when it would arrive.

Send exactly the request you would send to /translate/fused/file. Every field that endpoint takes is accepted here, so pricing a call means re-sending it rather than rewriting it. Nothing is translated, nothing is metered, no order is placed and no reviewer is engaged.

Two of those fields change the answer. The briefing selects Optimisation instead of Verification, which changes both the price and the delivery time. And use_ocr decides how a PDF's text is read, and therefore how many words the document turns out to hold — quote a scan without it and you are pricing a document that appears to be empty. politeness steers the draft the reviewer starts from, not how much there is to review, so it cannot change either number.

prices is what the call costs, in your workspace's billing currency: the review, priced per source word with a per-order minimum, with the machine translation included. word_count and character_count are what was found in the document, so you can see where the number comes from — neither is a quantity you are charged for separately.

The document is read to answer this, so the same size and format rules apply as for the order itself.

Limits: 30 MiB per file, 10 requests per second.

Request Body
multipart/form-data
Response
200
Add your API key to send requests

Supported: DOCX, PPTX, XLSX, PDF, HTML, TXT, SRT

Feature Scope

Discover supported language pairs and their available features.

GET/features

Language & feature support

Every supported language pair, and the features supported for each.

Translation itself is a full matrix — every source language translates into every target language. What has gaps is the features, and the gaps are per language: formality is meaningless in some targets, and glossary terms cannot be enforced in every target. So this endpoint answers one entry per pair with the feature names that pair supports; a name that is absent is not supported.

Filter with source_lang and/or target_lang to ask about one row rather than the whole matrix. A filter naming a language we do not support narrows the answer to nothing rather than failing — a language picker asking about an unknown language wants an empty list, not an error. A target_lang naming a base language with several variants (de) keeps all of them.

Limits: 10 request(s) per second.

Parameters
Response
200
Add your API key to send requests

Language Detection

Identify the language of text or files, or quote detection.

POST/detect-languages/textCosts

Language detection

Detect the language of the provided text.

This endpoint incurs usage costs, charged like a translation of the 500-character snippet actually read. An inconclusive answer — an empty detected_languages — is free.

Limits: 10 request(s) per second.

Request Body
application/json
Response
200
Add your API key to send requests
Editable

This request will incur usage costs

POST/detect-languages/text/quote

Language detection quote

What a detection would cost.

Takes the same payload as /detect-languages/text. Same fields as the translation quote, priced on the capped snippet. The price is what the request would cost beyond your plan's API & MCP quota at the time of the quote.

Limits: 10 request(s) per second.

Request Body
application/json
Response
200
Add your API key to send requests
Editable
POST/detect-languages/fileCosts

File language detection

Identify the language a document is written in.

This endpoint incurs usage costs.

Send the file as multipart/form-data. The answer comes back on the same request — no polling. The document is read while you wait, so a large file, or a scan that needs OCR, can take a while and may time out; if that happens, extracting the text yourself and using /detect-languages/text is the reliable path.

A document with no readable text answers with an empty detected_languages list and costs nothing.

Charged on the first 500 characters of the document, like the text endpoint — identifying a language needs a sample, not the whole file.

Limits: 30 MiB per file, 1 request(s) per second.

Request Body
multipart/form-data
Response
200
Add your API key to send requests

Supported: DOCX, PPTX, XLSX, PDF, HTML, TXT, SRT

This request will incur usage costs

POST/detect-languages/file/quote

File language detection quote

What detecting a document's language would cost.

Takes the same file as /detect-languages/file. Nothing is identified and no usage is recorded, but the document is still read to see how much text it holds, so this is as slow as the detection itself. The price is what the request would cost beyond your plan's API & MCP quota at the time of the quote.

Limits: 10 request(s) per second.

Request Body
multipart/form-data
Response
200
Add your API key to send requests

Supported: DOCX, PPTX, XLSX, PDF, HTML, TXT, SRT

Webhooks

Register endpoints that we call when your translations finish or your workspace needs attention.

GET/webhooks

List webhooks

The webhooks this API key created. Another key's webhooks, even in the same workspace, are not listed.

Limits: 1 request(s) per second.

Response
200
Add your API key to send requests
POST/webhooks

Create a webhook

Register a URL to receive the events you list. See the Webhooks section for the event types, the request we send and how to verify it.

The response carries the signing secret, and only this response does. Store it now: it cannot be read again. To get a new one, delete the webhook and create it again.

The URL must be https, carry no credentials and resolve to a public address; it is checked now and again before every delivery. A workspace can have up to 10 webhooks; the next one is refused with 409 webhook_limit_reached.

Limits: 1 request(s) per second.

Request Body
application/json
Response
201
Add your API key to send requests

The usual set for an integration that uploads documents and wants the result.

Editable
GET/webhooks/{webhook_id}

Get a webhook

One of this API key's webhooks, with its delivery health: when an event last reached it, the last failure and how many attempts in a row have failed.

Limits: 1 request(s) per second.

Parameters
Response
200
Add your API key to send requests
PATCH/webhooks/{webhook_id}

Update a webhook

Change the URL, the event types or the description. Only the fields you send change; "description": null clears the description.

"enabled": true switches a disabled webhook back on and resets its failure count. Events that were cancelled while it was disabled are not sent again.

Limits: 1 request(s) per second.

Parameters
Request Body
application/json
Response
200
Add your API key to send requests

Once your endpoint answers again. Resets the failure count.

Editable
DELETE/webhooks/{webhook_id}

Delete a webhook

Delete a webhook. Events not yet delivered to it are cancelled, and nothing new is sent to it; at most a request already in progress may still arrive.

Limits: 1 request(s) per second.

Parameters
Add your API key to send requests
POST/webhooks/{webhook_id}/test

Send a test event

Send a webhook.test event to the webhook now and report what came back. Use it to check an endpoint while you set it up.

It is signed and sent exactly like a real event, but it is not retried and does not count towards the webhook's failure record. A failed test is still a 200: read delivered, status_code and error. A disabled webhook answers 409 webhook_disabled; re-enable it first.

Limits: 1 per 5 s.

Parameters
Response
200
Add your API key to send requests