Machine translation uses API keys that the organisation brings, so the service bills the organisation and not us. What happens to the text and the key is explained in Machine translation.
GET /org/mt
PUT /org/mt/{provider}
POST /org/mt/{provider}/models
DELETE /org/mt/{provider}Access: Session token only. API keys get 403 with insufficient_scope.
Role: Organisation owner or admin.
An organisation can set up several machine translation services, one key per service. The provider is one of deepl, google, azure (Azure Translator), anthropic (Claude), openai, gemini, mistral and deepseek.
The key is never returned. It is checked with the service when you send it, stored encrypted, and not shown again by any route, the audit log or the organisation settings.
Get the setup #
GET /org/mt lists every service, set up or not, and answers 200:
{
"providers": [
{
"provider": "deepl",
"configured": true,
"last4": "cd:fx",
"keyStatus": "ok",
"default": true,
"settings": {},
"monthlyLimit": 500000,
"usage": { "period": "2026-10", "characters": 1280, "requests": 14, "limit": 500000 }
}
],
"default": "deepl"
}| Field | Type | Description |
|---|---|---|
default | string|null | The service that suggestions and automatic filling start with. The first service you set up is the default until you choose another. null when none is set up. |
providers[].provider | string | The service. |
providers[].configured | boolean | Whether a key is stored. |
providers[].last4 | string|null | The last four characters of the key. |
providers[].keyStatus | string|null | ok, or rejected once the service refused the key. No requests are made to it until a new key is saved. |
providers[].default | boolean | Whether this is the default service. |
providers[].settings | object | The options besides the key, which are not secret: region for azure, model for the AI models (the default model for a service that is not set up). Empty for the others. |
providers[].monthlyLimit | integer|null | Characters per calendar month (UTC). null means no limit of ours. Without a key it shows the default, 500000. |
providers[].usage | object | Characters and requests counted this month. Each service has its own count and limit. |
Save the key and the limit #
PUT /org/mt/{provider} takes:
| Field | Type | Required | Description |
|---|---|---|---|
apiKey | string | The first time | The API key. Leave it out to keep the stored key. A new key replaces the old one and sets keyStatus to ok. |
monthlyLimit | integer|null | no | From 1 to 1,000,000,000 characters, or null for no limit. Left out, the limit stays as it was (500000 for a new connection). |
settings | object | no | The options besides the key, see providers[].settings. azure needs a region (lower case letters, digits and dashes, such as westeurope, or global). An AI model’s model is optional and defaults to the model named in Machine translation. Left out, the stored values stay. Changing them checks the stored key again. |
default | boolean | no | true makes this the default service. false takes the default away from it (when another service is set up, that one is not chosen for you). Left out, the default stays as it was. |
It answers 200 with the entry of that service as in providers[], plus default with the name of the default service. Adding or replacing the key records org.mt_key_set in the audit log, and a changed limit records org.mt_limit_changed.
List the models #
POST /org/mt/{provider}/models lists the models that a key can use, for choosing settings.model. It takes an optional apiKey: the key being set up, which is not stored yet. Without it the stored key is used. It is a POST so that the key is not part of an address. The key is sent to the service only, never returned.
{ "models": [{ "id": "claude-haiku-5-5", "name": "Claude Haiku 5.5" }] }Only anthropic (Claude) and gemini list their models for now. models is null when the service has no list, when no key is stored or sent, or when the service refused the key or could not be reached, and the model can then be typed. Saving still checks the model with the service. Role and access are as above; an unknown provider answers 404.
Remove the key #
DELETE /org/mt/{provider} deletes the key and answers 204. Machine translation with that service stops for the whole organisation. When it was the default, another service that is set up becomes the default. It records org.mt_key_removed.
Errors #
| Status | error | When |
|---|---|---|
| 401 | unauthenticated | The token is missing or not valid. |
| 403 | forbidden | You are not an owner or admin. |
| 404 | not_found | provider is not a service we know, or DELETE without a stored key for it. |
| 422 | invalid_request | fields.apiKey is malformed (not the shape of a key of that service, often a key of another service), rejected (the service refused it, for azure also a wrong region), scope_missing (the service knows the key but it lacks a permission we need, as a DeepL key limited to some scopes) or required; fields.monthlyLimit is invalid; fields.region is required or invalid; fields.model is invalid or unknown (the service does not know it). |
| 502 | mt_provider_unavailable | The service could not be reached to check the key. |
| 429 | rate_limited | Too many requests, see Rate limiting. |
See Errors for the error format.