---
api-reference/admin-api.mdx | 299 ++++++
.../admin-api/managing-admin-keys.mdx | 77 +-
api-reference/document.mdx | 348 +++++++
.../upload-and-translate-a-document.mdx | 15 +-
api-reference/glossaries.mdx | 366 +++++++
.../glossaries/create-a-glossary.mdx | 7 +-
api-reference/improve-text.mdx | 194 ++++
.../improve-text/request-text-improvement.mdx | 6 +-
api-reference/jobs-voice-translate.mdx | 369 +++++++
.../create-voice-translate-job.mdx | 12 -
api-reference/languages.mdx | 387 +++++++
.../languages/language-feature-use-cases.mdx | 152 +++
.../retrieve-languages-by-resource.mdx | 79 --
...trieve-supported-languages-by-resource.mdx | 246 +++++
api-reference/multilingual-glossaries.mdx | 721 ++++++++++++++
.../create-a-glossary.mdx | 7 +-
api-reference/quality-evaluation.mdx | 35 +
api-reference/quality-evaluation/submit.mdx | 17 +-
api-reference/style-rules.mdx | 940 ++++++++++++++++++
.../style-rules/list-all-style-rules.mdx | 7 +-
api-reference/translate.mdx | 537 ++++++++++
.../translate/request-translation.mdx | 8 +-
api-reference/usage-and-quota.mdx | 79 ++
.../check-usage-and-limits.mdx | 7 +-
api-reference/voice.mdx | 401 ++++++++
api-reference/voice/request-session.mdx | 7 -
docs.json | 35 +-
docs/getting-started/about.mdx | 27 +-
28 files changed, 5154 insertions(+), 231 deletions(-)
create mode 100644 api-reference/admin-api.mdx
create mode 100644 api-reference/document.mdx
create mode 100644 api-reference/glossaries.mdx
create mode 100644 api-reference/improve-text.mdx
create mode 100644 api-reference/jobs-voice-translate.mdx
create mode 100644 api-reference/languages.mdx
create mode 100644 api-reference/languages/language-feature-use-cases.mdx
create mode 100644 api-reference/languages/retrieve-supported-languages-by-resource.mdx
create mode 100644 api-reference/multilingual-glossaries.mdx
create mode 100644 api-reference/quality-evaluation.mdx
create mode 100644 api-reference/style-rules.mdx
create mode 100644 api-reference/translate.mdx
create mode 100644 api-reference/usage-and-quota.mdx
create mode 100644 api-reference/voice.mdx
diff --git a/api-reference/admin-api.mdx b/api-reference/admin-api.mdx
new file mode 100644
index 0000000..50c4c46
--- /dev/null
+++ b/api-reference/admin-api.mdx
@@ -0,0 +1,299 @@
+---
+title: "Admin API"
+public: true
+sidebarTitle: "Overview"
+description: "Explore DeepL API offering designed for admins"
+---
+
+### Get started
+
+
+ The Admin API is available to all API Growth and API Enterprise subscribers, and to a limited set of Pro API subscribers. To enable access, contact your DeepL customer success manager or DeepL support.
+
+
+Once the Admin API is enabled, follow the instructions in [Managing admin keys](/api-reference/admin-api/managing-admin-keys)
+to create an admin key. You will use the generated key for authentication in each request to the API.
+
+
+ Note that managing admin keys themselves is currently available only in the self-admin area under the
+ [“Admin Keys” tab](https://www.deepl.com/your-account/admin).
+
+
+With an admin key in hand, you are now ready to manage developer keys within your organization through the public API.
+
+### Managing developer keys
+
+The admin API keys allow admins to [manage developer API keys](/docs/getting-started/managing-api-keys) through DeepL API. These functionalities are equivalent to
+those available in the self-admin area under the ["API Keys & Limits" tab](https://www.deepl.com/your-account/keys).
+
+The Admin API currently consists of a single endpoint, `/v2/admin/developer-keys`, available under our API pro endpoint `https://api.deepl.com`.
+
+#### Create a developer key
+
+`POST /v2/admin/developer-keys`
+
+You can optionally give an API key a name of your choosing during the creation process. If you do not name the key, the
+name “DeepL API Key” will be given to the key automatically.
+
+Up to 25 simultaneously active API keys are allowed.
+
+
+
+ ```sh Example request: Create a developer key as an admin
+ curl -X POST 'https://api.deepl.com/v2/admin/developer-keys' \
+ --header 'Authorization: DeepL-Auth-Key [yourAdminKey]' \
+ --header 'Content-Type: application/json' \
+ --data '{
+ "label": "admin-key"
+ }'
+ ```
+ ```json Example response
+ {
+ "key_id": "ca7d5694-96eb-4263-a9a4-7f7e4211529e:20c2abcf-4c3c-4cd6-8ae8-8bd2a7d4da38",
+ "label": "developer key prod",
+ "creation_time": "2025-07-08T08:15:29.362Z",
+ "deactivated_time": "2025-07-09T08:15:29.362Z",
+ "is_deactivated": true,
+ "usage_limits": {
+ "characters": 5000
+ }
+ }
+ ```
+
+
+ ```http
+ POST /v2/admin/developer-keys HTTP/2
+ Host: api.deepl.com
+ Authorization: DeepL-Auth-Key [yourAdminKey]
+ User-Agent: YourApp/1.2.3
+ Content-Length: 123
+ Content-Type: application/json
+
+ {
+ "label": "admin-key"
+ }
+ ```
+
+
+
+#### Get all developer keys
+
+`GET /v2/admin/developer-keys`
+
+This method will return both active and deactivated keys.
+
+
+
+ ```sh Example request: Get all developer keys as an admin
+ curl -X GET 'https://api.deepl.com/v2/admin/developer-keys' \
+ --header 'Authorization: DeepL-Auth-Key [yourAdminKey]' \
+ --header 'Content-Type: application/json'
+ ```
+ ```json Example response
+ [
+ {
+ "key_id": "ca7d5694-96eb-4263-a9a4-7f7e4211529e:20c2abcf-4c3c-4cd6-8ae8-8bd2a7d4da38",
+ "label": "developer key prod",
+ "creation_time": "2025-07-08T08:15:29.362Z",
+ "deactivated_time": "2025-07-09T08:15:29.362Z",
+ "is_deactivated": true,
+ "usage_limits": {
+ "characters": 5000
+ }
+ }
+ ]
+ ```
+
+
+ ```http
+ GET /v2/admin/developer-keys HTTP/2
+ Host: api.deepl.com
+ Authorization: DeepL-Auth-Key [yourAdminKey]
+ User-Agent: YourApp/1.2.3
+ Content-Length: 123
+ Content-Type: application/json
+ ```
+
+
+
+#### Deactivate a developer key
+
+`PUT /v2/admin/developer-keys/deactivate`
+
+
+ **IMPORTANT:** An API key will stop working immediately when deactivated. After a key is deactivated, it cannot be reactivated—deactivating a key is permanent!
+
+
+To deactivate a key, pass its ID in the request, as shown below. The key ID is composed of two GUIDs separated by the `:` symbol.
+
+
+
+ ```sh Example request: Deactivate a developer key as an admin
+ curl -X PUT 'https://api.deepl.com/v2/admin/developer-keys/deactivate' \
+ --header 'Authorization: DeepL-Auth-Key [yourAdminKey]' \
+ --header 'Content-Type: application/json' \
+ --data '{
+ "key_id": "GUID:GUID"
+ }'
+ ```
+ ```json Example response
+ {
+ "key_id": "ca7d5694-96eb-4263-a9a4-7f7e4211529e:20c2abcf-4c3c-4cd6-8ae8-8bd2a7d4da38",
+ "label": "developer key prod",
+ "creation_time": "2025-07-08T08:15:29.362Z",
+ "deactivated_time": "2025-07-09T08:15:29.362Z",
+ "is_deactivated": true,
+ "usage_limits": {
+ "characters": 5000
+ }
+ }
+ ```
+
+
+ ```http
+ PUT /v2/admin/developer-keys/deactivate HTTP/2
+ Host: api.deepl.com
+ Authorization: DeepL-Auth-Key [yourAdminKey]
+ User-Agent: YourApp/1.2.3
+ Content-Length: 123
+ Content-Type: application/json
+
+ {
+ "key_id": "GUID:GUID"
+ }
+ ```
+
+
+
+#### Rename a developer key
+
+`PUT /v2/admin/developer-keys/label`
+
+To rename a key, pass its ID in the request and the new label, as shown below.
+The key ID is composed of two GUIDs separated by the `:` symbol.
+
+
+
+ ```sh Example request: Rename a developer key as an admin
+ curl -X PUT 'https://api.deepl.com/v2/admin/developer-keys/label' \
+ --header 'Authorization: DeepL-Auth-Key [yourAdminKey]' \
+ --header 'Content-Type: application/json' \
+ --data '{
+ "key_id": "GUID:GUID",
+ "label": "admin-key-prod"
+ }'
+ ```
+ ```json Example response
+ {
+ "key_id": "ca7d5694-96eb-4263-a9a4-7f7e4211529e:20c2abcf-4c3c-4cd6-8ae8-8bd2a7d4da38",
+ "label": "developer key prod",
+ "creation_time": "2025-07-08T08:15:29.362Z",
+ "deactivated_time": "2025-07-09T08:15:29.362Z",
+ "is_deactivated": true,
+ "usage_limits": {
+ "characters": 5000
+ }
+ }
+ ```
+
+
+ ```http
+ PUT /v2/admin/developer-keys/label HTTP/2
+ Host: api.deepl.com
+ Authorization: DeepL-Auth-Key [yourAdminKey]
+ User-Agent: YourApp/1.2.3
+ Content-Length: 123
+ Content-Type: application/json
+
+ {
+ "key_id": "GUID:GUID",
+ "label": "admin-key-prod"
+ }
+ ```
+
+
+
+#### Set usage limits for a developer key
+
+`PUT /v2/admin/developer-keys/limits`
+
+Key-level limits restrict the number of total characters (across text translation, document translation, and text
+improvement) that can be consumed by an API key in a one-month usage period.
+
+For example, if you set a key-level usage limit of 1,000,000 characters, the API key will not consume more than 1,000,000 characters per usage period.
+
+The character count will "reset" at the start of the next usage period, at which point the key will again be able to consume characters.
+
+As with subscription-level cost control:
+
+* Developers will receive notification emails when 80% and 100% of a key-level limit has been reached
+* The API will respond with `456 Quota exceeded` errors when 100% of a key-level limit has been reached
+
+
+ Setting the limit to `0` means the API key will not be able to consume characters.
+
+
+
+ Setting the limit to `null` disables the limit, effectively allowing unlimited usage.
+
+
+
+
+ ```sh Example request: Set usage limits for a developer key as an admin
+ curl -X PUT 'https://api.deepl.com/v2/admin/developer-keys/limits' \
+ --header 'Authorization: DeepL-Auth-Key [yourAdminKey]' \
+ --header 'Content-Type: application/json' \
+ --data '{
+ "key_id": "GUID:GUID",
+ "characters": 1000
+ }'
+ ```
+
+ ```sh Example request: Prevent using a developer key as an admin
+ curl -X PUT 'https://api.deepl.com/v2/admin/developer-keys/limits' \
+ --header 'Authorization: DeepL-Auth-Key [yourAdminKey]' \
+ --header 'Content-Type: application/json' \
+ --data '{
+ "key_id": "GUID:GUID",
+ "characters": 0
+ }'
+ ```
+
+ ```sh Example request: Allow unlimited usage of a developer key as an admin
+ curl -X PUT 'https://api.deepl.com/v2/admin/developer-keys/limits' \
+ --header 'Authorization: DeepL-Auth-Key [yourAdminKey]' \
+ --header 'Content-Type: application/json' \
+ --data '{
+ "key_id": "GUID:GUID",
+ "characters": null
+ }'
+ ```
+ ```json Example response
+ {
+ "key_id": "ca7d5694-96eb-4263-a9a4-7f7e4211529e:20c2abcf-4c3c-4cd6-8ae8-8bd2a7d4da38",
+ "label": "developer key prod",
+ "creation_time": "2025-07-08T08:15:29.362Z",
+ "deactivated_time": "2025-07-09T08:15:29.362Z",
+ "is_deactivated": true,
+ "usage_limits": {
+ "characters": 5000
+ }
+ }
+ ```
+
+
+ ```http
+ PUT /v2/admin/developer-keys/limits HTTP/2
+ Host: api.deepl.com
+ Authorization: DeepL-Auth-Key [yourAdminKey]
+ User-Agent: YourApp/1.2.3
+ Content-Length: 123
+ Content-Type: application/json
+
+ {
+ "key_id": "GUID:GUID",
+ "characters": 1000
+ }
+ ```
+
+
\ No newline at end of file
diff --git a/api-reference/admin-api/managing-admin-keys.mdx b/api-reference/admin-api/managing-admin-keys.mdx
index fb8cb7d..6a820f0 100644
--- a/api-reference/admin-api/managing-admin-keys.mdx
+++ b/api-reference/admin-api/managing-admin-keys.mdx
@@ -1,97 +1,88 @@
---
title: "Managing admin API keys"
-description: "Create, copy, rename, and deactivate admin API keys in the DeepL self-admin area."
+description: "Learn how admins can create and manage admin API keys."
public: true
---
-
- The Admin API is available to all API Growth and API Enterprise subscribers, and to a limited set of Pro API subscribers. To enable access, contact your DeepL customer success manager or DeepL support.
-
+### Get started
-Once Admin API access is enabled for your account, you can find and manage your admin API keys in the ["Admin Keys" tab](https://www.deepl.com/your-account/admin) when signed into your DeepL API account. You can have multiple simultaneously active admin API keys on a single subscription.
+Once the Admin API access has been enabled for your account, you can find and manage your admin API keys in the
+[“Admin Keys” tab](https://www.deepl.com/your-account/admin) when signed into your DeepL API account.
+It’s possible to have multiple, simultaneously active admin API keys in a single API subscription.
- 
+ 
-## Create a key
+### Create new key
-Click "Create Key" to create a new admin API key. You can optionally give the key a custom name during creation. If you don't provide a name, it defaults to "DeepL Admin Key".
+Create a new admin API key by clicking on the "Create Key" button.
+You can optionally give an API key a custom name during the creation process.
+If you do not name the key, the name “DeepL Admin Key” will be given to the key automatically.
You can create up to 25 simultaneously active admin API keys.
- 
+ 
-After creating a key, a popup displays the newly created key:
+After creating a key, a popup with the newly created key will appear:
- 
+ 
-Copy the key from this popup and use it immediately. You can also copy it from the table in the "Admin Keys" tab at any time.
+You can copy the key from this popup and use the key immediately.
+You can also copy the key from the table in the “Admin Keys” tab at any time.
-Admin keys always have an `:adm` suffix, which distinguishes them from developer keys.
+Note that the generated admin keys always have an *:adm* suffix, to distinguish them from the developer keys which do not have a suffix.
-Naming your keys makes them searchable via the search bar on the "Admin Keys" tab:
+Giving your API keys a name during the key creation process makes it possible for you to search for the key by name
+using the search bar on the “Admin Keys” tab:
- 
+ 
-## Deactivate a key
+### Deactivate key
- An API key stops working immediately when deactivated. Deactivation is permanent and cannot be reversed.
+ **IMPORTANT:** An API key will stop working immediately when deactivated. After a key is deactivated, it cannot be reactivated—deactivating a key is permanent!
-To deactivate an active admin API key, select "Deactivate key" from the key's options menu:
+To deactivate an active admin API key:
- 
+ 
- 
+ 
- 
+ 
-## Rename a key
+### Rename key
-You can rename both active and deactivated keys. Two keys may share the same name.
+Allows you to edit the name of an API key. Note that it *is* possible for two keys to have the same name.
-Select "Rename key" from the key's options menu:
+Both active and deactivated keys can be renamed.
- 
+ 
-
- 
+ 
-## Copy a key
+### Copy key
-To copy an admin API key to your clipboard, click the "Copy" icon next to the key. Both active and deactivated keys can be copied.
+To copy an admin API key to your clipboard click the "Copy" icon next to the key.
- 
+ 
-For security reasons, the full key is not shown in the "Admin Keys" tab table.
-
-## Using admin keys in the API
-
-With an admin key, you can manage developer API keys programmatically. These operations are equivalent to those available in the ["API Keys & Limits" tab](https://www.deepl.com/your-account/keys) of the self-admin area.
-
-Use the admin key for authentication by passing it in the `Authorization` header of each request:
-
-```http
-Authorization: DeepL-Auth-Key [yourAdminKey]
-```
-
-The Admin API is available at `https://api.deepl.com/v2/admin/developer-keys`. See the [developer keys endpoint reference](/api-reference/admin-api) for full request and response schemas.
\ No newline at end of file
+For security reasons, we do not show the full key in the table in the “Admin Keys” tab. Both active and deactivated keys can be copied.
diff --git a/api-reference/document.mdx b/api-reference/document.mdx
new file mode 100644
index 0000000..f0767ac
--- /dev/null
+++ b/api-reference/document.mdx
@@ -0,0 +1,348 @@
+---
+title: "Translate documents"
+sidebarTitle: "Overview"
+public: true
+---
+
+The document translation API allows you to translate whole documents and supports the following file types and extensions:
+
+* `docx` / `doc` - Microsoft Word Document
+* `pptx` - Microsoft PowerPoint Document
+* `xlsx` - Microsoft Excel Document
+* `pdf` - Portable Document Format
+* `htm / html` - HTML Document
+* `txt` - Plain Text Document
+* `xlf / xliff` - XLIFF Document (versions 1.2, 2.0, and 2.1)
+* `srt` - SRT (SubRip Subtitle) Document
+* `idml` - Adobe InDesign Markup Language
+* `xml` - XML Document
+* `json` - JSON Document
+* `dita` - DITA topic (Darwin Information Typing Architecture)
+* `mif` - Adobe FrameMaker Interchange Format
+* `jpeg` / `jpg` / `png` - Image (currently in beta)
+
+Please note that with every submitted document of type .pptx, .docx, .doc, .xlsx, or .pdf, you are billed a minimum of 50,000 characters with the DeepL API plan, no matter how many characters are included in the document.
+
+The maximum upload limit for documents is [available here](/docs/resources/usage-limits#maximum-upload-limits-per-document-format) and may vary based on API plan and document type.
+
+We also provide specs that are auto-generated from DeepL's OpenAPI file. [You can find it here](/api-reference/document/upload-and-translate-a-document).
+
+
+When translating a `doc` file, you will receive a `docx` file as the output format.
+
+
+### Step 1: upload a document to the `/document` endpoint
+
+This call uploads a document and queues it for translation. The call returns once the upload is complete, returning a document ID and key which can be used to [query the translation status](/api-reference/document#step-2%3A-check-the-document-status-and-wait-for-translation-to-complete) and to [download the translated document](/api-reference/document#step-3%3A-download-the-translated-document) once translation is complete.
+
+Because the request includes a file upload, it must be an HTTP POST request with content type `multipart/form-data`.
+
+Please be aware that the uploaded document is automatically removed from the server once the translated document has been downloaded. You have to upload the document again in order to restart the translation.
+
+You may specify the glossary to use for the document translation using the `glossary_id` parameter. **Important:** This requires the `source_lang` parameter to be set and the language pair of the glossary has to match the language pair of the request.
+
+For more detail about request body parameters, see the [Request Body Descriptions](/api-reference/document#request-body-descriptions) section further down on the page.
+
+
+
+The examples below use our API Pro endpoint `https://api.deepl.com`. If you're an API Free user, remember to update your requests to use `https://api-free.deepl.com` instead.
+
+```sh Example request: document upload (no glossary)
+curl -X POST 'https://api.deepl.com/v2/document' \
+--header 'Authorization: DeepL-Auth-Key [yourAuthKey]' \
+--form 'target_lang=DE' \
+--form 'file=@document.docx'
+```
+
+```sh Example request: document upload (with glossary)
+curl -X POST 'https://api.deepl.com/v2/document' \
+--header 'Authorization: DeepL-Auth-Key [yourAuthKey]' \
+--form 'source_lang=EN' \
+--form 'target_lang=DE' \
+--form 'file=@document.docx' \
+--form 'glossary_id=[yourGlossaryId]'
+```
+
+```json Example response
+{
+ "document_id": "04DE5AD98A02647D83285A36021911C6",
+ "document_key": "0CB0054F1C132C1625B392EADDA41CB754A742822F6877173029A6C487E7F60A"
+}
+```
+
+
+The examples below use our API Pro endpoint `https://api.deepl.com`. If you're an API Free user, remember to update your requests to use `https://api-free.deepl.com` instead.
+
+```http Example request: document upload (no glossary)
+POST /v2/document HTTP/2
+Host: api.deepl.com
+Authorization: DeepL-Auth-Key [yourAuthKey]
+User-Agent: YourApp/1.2.3
+Content-Length: [length]
+Content-Type: multipart/form-data;boundary="boundary"
+
+--boundary,Content-Disposition: form-data; name=target_lang
+
+DE
+--boundary,Content-Disposition: form-data; name=file
+
+@document.docx
+```
+
+```http Example request: document upload (with glossary)
+POST /v2/document HTTP/2
+Host: api.deepl.com
+Authorization: DeepL-Auth-Key [yourAuthKey]
+User-Agent: YourApp/1.2.3
+Content-Length: [length]
+Content-Type: multipart/form-data;boundary="boundary"
+
+--boundary,Content-Disposition: form-data; name=source_lang
+
+EN
+--boundary,Content-Disposition: form-data; name=target_lang
+
+DE
+--boundary,Content-Disposition: form-data; name=file
+
+@document.docx
+--boundary,Content-Disposition: form-data; name=glossary_id
+
+[yourGlossaryId]
+```
+
+```json Example response
+{
+ "document_id": "04DE5AD98A02647D83285A36021911C6",
+ "document_key": "0CB0054F1C132C1625B392EADDA41CB754A742822F6877173029A6C487E7F60A"
+}
+```
+
+
+
+These examples are for demonstration purposes only. In production code, the authentication key should not be hard-coded but instead fetched from a configuration file or environment variable.
+
+#### Request Body Descriptions
+
+**Note:** the `model_type` parameter is not supported for API document translation and is only supported for [text translation](/api-reference/translate#about-the-model_type-parameter). It’s possible to submit a document translation request that includes the parameter, but the parameter will be ignored and will not have an effect on translation results.
+
+
+ Language of the text to be translated. If omitted, the API will attempt to detect the language of the text and translate it. You can find supported languages here.
+
+
+ The language into which the text should be translated. You can find supported languages here.
+
+
+ The document file to be translated. The file name should be included in this part's content disposition. As an alternative, the filename parameter can be used.
+ The following file types and extensions are supported:
+
+ - `docx`: Microsoft Word Document
+ - `pptx`: Microsoft PowerPoint Document
+ - `xlsx`: Microsoft Excel Document
+ - `pdf`: Portable Document Format
+ - `htm / .html`: HTML Document
+ - `txt`: Plain Text Document
+ - `xlf / xliff`: XLIFF Document (versions 1.2, 2.0, and 2.1)
+ - `srt` - SRT (SubRip Subtitle) Document
+ - `idml`: Adobe InDesign Markup Language
+ - `xml`: XML Document
+ - `json`: JSON Document
+ - `dita`: DITA topic (Darwin Information Typing Architecture)
+ - `mif`: Adobe FrameMaker Interchange Format
+ - `jpeg` / `jpg` / `png` - Image (currently in beta)
+
+
+
+ The name of the uploaded file. Can be used as an alternative to including the file name in the file part's content disposition.
+
+
+ Sets whether the translated text should lean towards formal or informal language. This feature currently only works for target languages `DE` (German), `FR` (French), `IT` (Italian), `ES` (Spanish), `NL` (Dutch), `PL` (Polish), `PT-BR` and `PT-PT` (Portuguese), `JA` (Japanese), and `RU` (Russian). Learn more about the plain/polite feature for Japanese here. Setting this parameter with a target language that does not support formality will fail, unless one of the `prefer_...` options are used. To check formality support dynamically, call GET /v3/languages?resource=translate_document and look for the formality feature key on the target language. Possible options are:
+
+ - `default` (default)
+ - `more` - for a more formal language
+ - `less` - for a more informal language
+ - `prefer_more` - for a more formal language if available, otherwise fallback to default formality
+ - `prefer_less` - for a more informal language if available, otherwise fallback to default formality
+
+
+
+ A unique ID assigned to a glossary. To check glossary support for a language pair, call GET /v3/languages?resource=translate_document and verify the glossary feature key is present on both the source and target language.
+
+ Cannot be used together with glossary_ids.
+
+
+
+ Specify up to 5 glossaries to use for the document translation, as an array of glossary IDs. Each glossary's matching terms are applied to the translated document.
+
+ Important: This requires the source_lang parameter to be set, and every listed glossary must contain a dictionary for the requested language pair.
+
+ Cannot be used together with glossary_id.
+
+
+
+ Specify the style rule list to use for the translation which can be used to customize translations according to the selected formatting and style conventions.
+
+ The target language has to match the language of the style rule list.
+
+
+
+ The [translation memory](/api-reference/translation-memory/list-translation-memories) to use for the translation. The value should be the UUID of a translation memory associated with your account.
+
+
+ The minimum matching percentage required for a translation memory segment to be applied (recommended to be 75% or higher). Accepts values from 0 to 100. Default: `75`.
+
+
+ File extension of desired format of translated file, for example: `pdf`. If unspecified, by default the translated file will be in the same format as the input file.
+ Note: Not all combinations of input file and translation file extensions are permitted. See Document format conversions for the permitted combinations.
+
+
+### Step 2: check the document status and wait for translation to complete
+
+Retrieve the current status of a document translation process.
+
+Please note that the `seconds_remaining` parameter is just an estimate and can be unreliable (e.g. sometimes it might return 2^27). We recommend polling the document status, either in regular intervals or with exponential back-off. Translation time depends on the document size and server load, but should be in the order of seconds for small documents and 1-2 minutes for larger documents once translation has started.
+
+
+
+The example below uses our API Pro endpoint `https://api.deepl.com`. If you're an API Free user, remember to update your requests to use `https://api-free.deepl.com` instead.
+
+```sh Example request: check document status
+curl -X POST 'https://api.deepl.com/v2/document/{document_id}' \
+--header 'Authorization: DeepL-Auth-Key [yourAuthKey]' \
+--header 'Content-Type: application/json' \
+--data '{
+ "document_key": "0CB0054F1C132C1625B392EADDA41CB754A742822F6877173029A6C487E7F60A"
+}'
+```
+
+```json Example response: translating
+{
+ "document_id": "04DE5AD98A02647D83285A36021911C6",
+ "status": "translating",
+ "seconds_remaining": 20
+}
+```
+
+```json Example response: done
+{
+ "document_id": "04DE5AD98A02647D83285A36021911C6",
+ "status": "done",
+ "billed_characters": 1337
+}
+```
+
+```json Example response: queued
+{
+ "document_id": "04DE5AD98A02647D83285A36021911C6",
+ "status": "queued"
+}
+```
+
+```json Example response: error
+{
+ "document_id": "04DE5AD98A02647D83285A36021911C6",
+ "status": "error",
+ "message": "Source and target language are equal."
+}
+```
+
+
+The example below uses our API Pro endpoint `https://api.deepl.com`. If you're an API Free user, remember to update your requests to use `https://api-free.deepl.com` instead.
+
+```http Example request: check document status
+POST /v2/document/{document_id} HTTP/2
+Host: api.deepl.com
+Authorization: DeepL-Auth-Key [yourAuthKey]
+User-Agent: YourApp/1.2.3
+Content-Length: 83
+Content-Type: application/json
+
+{"document_key":"0CB0054F1C132C1625B392EADDA41CB754A742822F6877173029A6C487E7F60A"}
+```
+
+```json Example response: translating
+{
+ "document_id": "04DE5AD98A02647D83285A36021911C6",
+ "status": "translating",
+ "seconds_remaining": 20
+}
+```
+
+```json Example response: done
+{
+ "document_id": "04DE5AD98A02647D83285A36021911C6",
+ "status": "done",
+ "billed_characters": 1337
+}
+```
+
+```json Example response: queued
+{
+ "document_id": "04DE5AD98A02647D83285A36021911C6",
+ "status": "queued"
+}
+```
+
+```json Example response: error
+{
+ "document_id": "04DE5AD98A02647D83285A36021911C6",
+ "status": "error",
+ "message": "Source and target language are equal."
+}
+```
+
+
+
+### Step 3: download the translated document
+
+Once the status of the document translation process is `done`, the result can be downloaded.
+
+For privacy reasons the translated document is automatically removed from the server once it was downloaded and cannot be downloaded again.
+
+
+
+The example below uses our API Pro endpoint `https://api.deepl.com`. If you're an API Free user, remember to update your requests to use `https://api-free.deepl.com` instead.
+
+```sh Example request: download translated document
+curl -X POST 'https://api.deepl.com/v2/document/{document_id}/result' \
+--header 'Authorization: DeepL-Auth-Key [yourAuthKey]' \
+--header 'Content-Type: application/json' \
+--data '{
+ "document_key": "0CB0054F1C132C1625B392EADDA41CB754A742822F6877173029A6C487E7F60A"
+}'
+```
+
+
+The example below uses our API Pro endpoint `https://api.deepl.com`. If you're an API Free user, remember to update your requests to use `https://api-free.deepl.com` instead.
+
+```http Example request: download translated document
+POST /v2/document/{document_id}/result HTTP/2
+Host: api.deepl.com
+Authorization: DeepL-Auth-Key [yourAuthKey]
+User-Agent: YourApp/1.2.3
+Content-Length: 83
+Content-Type: application/json
+
+{"document_key":"0CB0054F1C132C1625B392EADDA41CB754A742822F6877173029A6C487E7F60A"}
+```
+
+
+
+### Client libraries and document translation
+
+The examples on this page show how to translate documents with DeepL using the API directly.
+
+DeepL's [client libraries](/docs/getting-started/client-libraries) simplify API document translation by providing a convenience function to upload the document, check translation status and download the translated document with a single function call.
+
+### Document format conversions
+
+By default, the DeepL API returns translated documents in the same format as the input document.
+
+Using the `output_format` parameter during document upload, you can select alternative output formats. For example, you can translate a PDF file and receive the translation as an editable Microsoft Word Document (DOCX), allowing you to make additional changes as necessary.
+
+The range of alternative output formats you can select are indicated in the table below:
+
+| Input document format | Alternative output document formats |
+| --- | --- |
+| PDF | `docx` - Microsoft Word Document |
+| Others | None |
diff --git a/api-reference/document/upload-and-translate-a-document.mdx b/api-reference/document/upload-and-translate-a-document.mdx
index ecedf0c..513c567 100644
--- a/api-reference/document/upload-and-translate-a-document.mdx
+++ b/api-reference/document/upload-and-translate-a-document.mdx
@@ -1,17 +1,4 @@
---
openapi: post /v2/document
title: "Upload and translate a document"
-description: "Upload a document for translation. Returns a document ID and key used to check status and download the result."
----
-
-Document translation is an asynchronous three-step process:
-
-1. **Upload** — Submit the document with `POST /v2/document`. Returns a `document_id` and `document_key`.
-2. **Poll** — Check translation status with `POST /v2/document/{document_id}` until status is `done`.
-3. **Download** — Retrieve the translated file with `POST /v2/document/{document_id}/result`.
-
-See the [Translate documents overview](/api-reference/document) for supported file formats, request parameters, format conversion options, and client library guidance.
-
-
- The uploaded document is automatically removed from the server once the translated document has been downloaded. To retranslate, upload the document again.
-
\ No newline at end of file
+---
\ No newline at end of file
diff --git a/api-reference/glossaries.mdx b/api-reference/glossaries.mdx
new file mode 100644
index 0000000..9aa664e
--- /dev/null
+++ b/api-reference/glossaries.mdx
@@ -0,0 +1,366 @@
+---
+title: "Monolingual glossaries (v2 endpoints)"
+public: true
+sidebarTitle: "Overview"
+description: "Manage glossaries using the v2 endpoints"
+---
+
+
+This page documents `v2` glossary endpoints, legacy endpoints that let you create and manage glossaries for a single language pair.
+
+[See here](/api-reference/multilingual-glossaries) for information on current `v3` endpoints. Using `v3` allows you to create, manage, and edit glossaries with entries in multiple language pairs, while still supporting monolingual functionality. [See here](/api-reference/glossaries/v2-vs-v3-endpoints) for an overview of the difference.
+
+The `/v2/glossary-language-pairs` endpoint is also deprecated. Use [`GET /v3/languages?resource=glossary`](/api-reference/languages/retrieve-supported-languages-by-resource) instead.
+
+
+This page describes how to use the `v2` endpoints to work with _monolingual_ glossaries - glossaries that map phrases in one language to phrases in another language. If you're new to glossaries, we suggest you use `v3` instead.
+
+### Create a glossary
+
+
+
+The example below uses our API Pro endpoint `https://api.deepl.com`. If you're an API Free user, remember to update your requests to use `https://api-free.deepl.com` instead.
+
+```sh Example request: create a glossary
+curl -X POST 'https://api.deepl.com/v2/glossaries' \
+--header 'Authorization: DeepL-Auth-Key [yourAuthKey]' \
+--header 'Content-Type: application/json' \
+--data '{
+ "name": "My Glossary",
+ "source_lang": "en",
+ "target_lang": "de",
+ "entries": "Hello\tGuten Tag",
+ "entries_format": "tsv"
+}'
+```
+```json Example response
+{
+ "glossary_id": "def3a26b-3e84-45b3-84ae-0c0aaf3525f7",
+ "ready": true,
+ "name": "My Glossary",
+ "source_lang": "en",
+ "target_lang": "de",
+ "creation_time": "2021-08-03T14:16:18.329Z",
+ "entry_count": 1
+}
+```
+
+
+The example below uses our API Pro endpoint `https://api.deepl.com`. If you're an API Free user, remember to update your requests to use `https://api-free.deepl.com` instead.
+
+```http Example request: create a glossary
+POST /v2/glossaries HTTP/2
+Host: api.deepl.com
+Authorization: DeepL-Auth-Key [yourAuthKey]
+User-Agent: YourApp/1.2.3
+Content-Length: 112
+Content-Type: application/json
+
+{"name":"My Glossary","source_lang":"en","target_lang":"de","entries":"Hello\tGuten Tag","entries_format":"tsv"}
+```
+
+```json Example response
+{
+ "glossary_id": "def3a26b-3e84-45b3-84ae-0c0aaf3525f7",
+ "ready": true,
+ "name": "My Glossary",
+ "source_lang": "en",
+ "target_lang": "de",
+ "creation_time": "2021-08-03T14:16:18.329Z",
+ "entry_count": 1
+}
+```
+
+
+The following example shows how to create a glossary from an example `csv` file (`glossary.csv`, with 2 example entries) via the command line using [`jq`](https://jqlang.github.io/jq/). Note that you'll need to install `jq` if you haven't already. Installation instructions for various operating systems are available [here](https://jqlang.github.io/jq/download/).
+
+
+
+The example below uses our API Pro endpoint `https://api.deepl.com`. If you're an API Free user, remember to update your requests to use `https://api-free.deepl.com` instead.
+
+
+```sh Create file + example request
+cat >glossary.csv <
+
+The example below uses our API Pro endpoint `https://api.deepl.com`. If you're an API Free user, remember to update your requests to use `https://api-free.deepl.com` instead.
+
+```http Example request: create a glossary
+POST /v2/glossaries HTTP/2
+Host: api.deepl.com
+Authorization: DeepL-Auth-Key [yourAuthKey]
+User-Agent: YourApp/1.2.3
+Content-Length: 112
+Content-Type: application/json
+
+{"name":"My Glossary","source_lang":"en","target_lang":"de","entries":"Hello,Hallo\nWorld,Welt","entries_format":"csv"}
+```
+
+```json Example reponse
+{
+ "glossary_id": "def3a26b-3e84-45b3-84ae-0c0aaf3525f7",
+ "ready": true,
+ "name": "My Glossary",
+ "source_lang": "en",
+ "target_lang": "de",
+ "creation_time": "2021-08-03T14:16:18.329Z",
+ "entry_count": 2
+}
+```
+
+
+
+### List all glossaries
+
+List all glossaries and their meta-information, but not the glossary entries.
+
+
+
+The example below uses our API Pro endpoint `https://api.deepl.com`. If you're an API Free user, remember to update your requests to use `https://api-free.deepl.com` instead.
+
+```sh Example request: list all glossaries
+curl -X GET 'https://api.deepl.com/v2/glossaries' \
+--header 'Authorization: DeepL-Auth-Key [yourAuthKey]'
+```
+
+```json Example response
+{
+ "glossaries": [
+ {
+ "glossary_id": "def3a26b-3e84-45b3-84ae-0c0aaf3525f7",
+ "name": "My Glossary",
+ "ready": true,
+ "source_lang": "EN",
+ "target_lang": "DE",
+ "creation_time": "2021-08-03T14:16:18.329Z",
+ "entry_count": 1
+ }
+ ]
+}
+```
+
+
+The example below uses our API Pro endpoint `https://api.deepl.com`. If you're an API Free user, remember to update your requests to use `https://api-free.deepl.com` instead.
+
+```http Example request: list all glossaries
+GET /v2/glossaries HTTP/2
+Host: api.deepl.com
+Authorization: DeepL-Auth-Key [yourAuthKey]
+User-Agent: YourApp/1.2.3
+```
+```json Example response
+{
+ "glossaries": [
+ {
+ "glossary_id": "def3a26b-3e84-45b3-84ae-0c0aaf3525f7",
+ "name": "My Glossary",
+ "ready": true,
+ "source_lang": "EN",
+ "target_lang": "DE",
+ "creation_time": "2021-08-03T14:16:18.329Z",
+ "entry_count": 1
+ }
+ ]
+}
+```
+
+
+### Retrieve glossary details
+
+Retrieve meta information for a single glossary, omitting the glossary entries.
+
+
+
+The example below uses our API Pro endpoint `https://api.deepl.com`. If you're an API Free user, remember to update your requests to use `https://api-free.deepl.com` instead.
+
+```sh Example request: retrieve glossary details
+curl -X GET 'https://api.deepl.com/v2/glossaries/{glossary_id}' \
+--header 'Authorization: DeepL-Auth-Key [yourAuthKey]'
+```
+```json Example response
+{
+ "glossary_id": "def3a26b-3e84-45b3-84ae-0c0aaf3525f7",
+ "ready": true,
+ "name": "My Glossary",
+ "source_lang": "en",
+ "target_lang": "de",
+ "creation_time": "2021-08-03T14:16:18.329Z",
+ "entry_count": 1
+}
+```
+
+
+The example below uses our API Pro endpoint `https://api.deepl.com`. If you're an API Free user, remember to update your requests to use `https://api-free.deepl.com` instead.
+
+```http Example request: retrieve glossary details
+GET /v2/glossaries/{glossary_id} HTTP/2
+Host: api.deepl.com
+Authorization: DeepL-Auth-Key [yourAuthKey]
+User-Agent: YourApp/1.2.3
+```
+```json Example response
+{
+ "glossary_id": "def3a26b-3e84-45b3-84ae-0c0aaf3525f7",
+ "ready": true,
+ "name": "My Glossary",
+ "source_lang": "en",
+ "target_lang": "de",
+ "creation_time": "2021-08-03T14:16:18.329Z",
+ "entry_count": 1
+}
+```
+
+
+### Retrieve glossary entries
+
+List the entries of a single glossary in the format specified by the `Accept` header.
+
+
+
+
+
+The example below uses our API Pro endpoint `https://api.deepl.com`. If you're an API Free user, remember to update your requests to use `https://api-free.deepl.com` instead.
+
+```sh Example request: retrieve glossary entries
+curl -X GET 'https://api.deepl.com/v2/glossaries/{glossary_id}/entries' \
+--header 'Authorization: DeepL-Auth-Key [yourAuthKey]' \
+--header 'Accept: text/tab-separated-values'
+```
+
+```text Example response
+Hello! Guten Tag!
+```
+
+
+```http Example request: retrieve glossary entries
+GET /v2/glossaries/{glossary_id}/entries HTTP/2
+Host: api.deepl.com
+Authorization: DeepL-Auth-Key [yourAuthKey]
+ 'Accept: text/tab-separated-values'
+User-Agent: YourApp/1.2.3
+```
+
+```text Example response
+Hello! Guten Tag!
+```
+
+
+### Delete a glossary
+
+Deletes the specified glossary.
+
+
+
+The example below uses our API Pro endpoint `https://api.deepl.com`. If you're an API Free user, remember to update your requests to use `https://api-free.deepl.com` instead.
+
+```sh Example request: delete a glossary
+curl -X DELETE 'https://api.deepl.com/v2/glossaries/{glossary_id}' \
+--header 'Authorization: DeepL-Auth-Key [yourAuthKey]'
+```
+
+
+The example below uses our API Pro endpoint `https://api.deepl.com`. If you're an API Free user, remember to update your requests to use `https://api-free.deepl.com` instead.
+
+```http Example request: delete a glossary
+DELETE /v2/glossaries/{glossary_id} HTTP/2
+Host: api.deepl.com
+Authorization: DeepL-Auth-Key [yourAuthKey]
+User-Agent: YourApp/1.2.3
+```
+
+
+
+### Listing language pairs
+The `/glossary-language-pairs` endpoint lists all the language pairs - the source and target languages - that glossaries support.
+
+
+Since DeepL supports many glossary languages, the list of potential pairs is quite long. [This list of glossary languages](/docs/getting-started/supported-languages) may also be useful.
+
+
+
+
+The example below uses our API Pro endpoint `https://api.deepl.com`. If you're an API Free user, remember to update your requests to use `https://api-free.deepl.com` instead.
+
+
+```sh Example request: get glossary language pairs
+curl -X GET 'https://api.deepl.com/v2/glossary-language-pairs' \
+--header 'Authorization: DeepL-Auth-Key [yourAuthKey]'
+```
+
+```json Example response (partial—one language pair)
+{
+ "supported_languages": [
+ {
+ "source_lang": "de",
+ "target_lang": "en"
+ },
+ {
+ "source_lang": "en",
+ "target_lang": "de"
+ }
+ ]
+}
+```
+
+
+The example below uses our API Pro endpoint `https://api.deepl.com`. If you're an API Free user, remember to update your requests to use `https://api-free.deepl.com` instead.
+
+```http Example request: get glossary language pairs
+GET /v2/glossary-language-pairs HTTP/2
+Host: api.deepl.com
+Authorization: DeepL-Auth-Key [yourAuthKey]
+User-Agent: YourApp/1.2.3
+```
+```json Example response (partial—one language pair)
+{
+ "supported_languages": [
+ {
+ "source_lang": "de",
+ "target_lang": "en"
+ },
+ {
+ "source_lang": "en",
+ "target_lang": "de"
+ }
+ ]
+}
+```
+
+
+
+### Editing a v2 glossary
+`v2` glossaries are immutable: once created, the glossary entries for a given glossary ID cannot be modified.
+
+As a workaround for effectively editable glossaries, we suggest to identify glossaries by name instead of ID in your application and then use the following procedure for modifications:
+
+* [download](/api-reference/glossaries#retrieve-glossary-details) and store the current glossary's entries
+* locally modify the glossary entries
+* [delete](/api-reference/glossaries#delete-a-glossary) the existing glossary
+* [create a new glossary](/api-reference/glossaries#create-a-glossary) with the same name
diff --git a/api-reference/glossaries/create-a-glossary.mdx b/api-reference/glossaries/create-a-glossary.mdx
index c8eb129..7498a80 100644
--- a/api-reference/glossaries/create-a-glossary.mdx
+++ b/api-reference/glossaries/create-a-glossary.mdx
@@ -1,10 +1,5 @@
---
openapi: post /v2/glossaries
title: "Create a glossary"
-description: "Learn how to create a v2 monolingual glossary that maps source phrases to target phrases for a single language pair."
playground: none
----
-
-Creates a monolingual glossary that maps source phrases to target phrases for a single language pair. These are legacy `v2` endpoints. For new integrations, use the [`v3` glossary endpoints](/api-reference/multilingual-glossaries), which support multilingual glossaries and editing.
-
-See the [v2 glossary overview](/api-reference/glossaries) for entry formats, supported language pairs, and workarounds for editing v2 glossaries.
\ No newline at end of file
+---
\ No newline at end of file
diff --git a/api-reference/improve-text.mdx b/api-reference/improve-text.mdx
new file mode 100644
index 0000000..f8f6b9a
--- /dev/null
+++ b/api-reference/improve-text.mdx
@@ -0,0 +1,194 @@
+---
+title: "Improve text"
+public: true
+sidebarTitle: "Overview"
+---
+
+ **Introducing DeepL API for Write**
+
+ DeepL API for Write is now generally available via the v2 API endpoint for customers with a DeepL API Pro subscription.
+
+ The supported scope of DeepL API for Write functionality is covered in this documentation page. Please note that the existing provisions applying to customers' DeepL API Pro subscription also apply to DeepL API for Write with [the following additions to the Service Specification](/api-reference/improve-text/deepl-write-api-service-specification-updates).
+
+ [An FAQ](/api-reference/improve-text#frequently-asked-questions) is included at the bottom of this page.
+
+### DeepL API for Write overview
+
+DeepL API for Write is accessible through an HTTP interface and consists of two endpoints:
+
+* [`/write/rephrase`](/api-reference/improve-text/request-text-improvement) — broad text improvement. Fixes spelling and grammar and may also rewrite sentences for clarity, style, or tone.
+* [`/write/correct`](/api-reference/improve-text/correct-text) — corrections-only mode. Fixes spelling and grammar errors with minimal changes to wording. Use this when you want the model to leave the author's voice intact.
+
+Both endpoints:
+
+* Accept both form-encoded (`Content-Type: application/x-www-form-urlencoded`) and JSON-encoded (`Content-Type: application/json`) request bodies
+* Return JSON-encoded responses
+
+The client libraries support all features of the text improvement endpoint. The text improvement feature is currently only available to DeepL API Pro customers and is not yet available in DeepL API Free.
+
+For more detail about request body parameters, see the [Request body descriptions](/api-reference/improve-text#request-body-descriptions) section further down the page.
+
+
+ The total request body size for text improvement requests must not exceed 10 KiB (10 · 1024 bytes). Please split up your text into multiple calls if it exceeds this limit.
+
+
+### Example cURL request and response
+
+*These examples are for demonstration purposes only. In your code, the authentication key should not be hard-coded but instead fetched from a configuration file or environment variable.*
+
+
+
+```sh Example cURL request
+curl -X POST 'https://api.deepl.com/v2/write/rephrase' \
+--header 'Authorization: DeepL-Auth-Key [yourAuthKey]' \
+--header 'Content-Type: application/json' \
+--data '{
+ "text": [
+ "I could relly use sum help with edits on thiss text !"
+ ],
+ "target_lang": "en-US"
+}'
+```
+```json Example response
+{
+ "improvements": [
+ {
+ "text": "I could really use some help with editing this text!",
+ "target_language": "en-US",
+ "detected_source_language": "en"
+ }
+ ]
+}
+```
+
+### Request body descriptions
+
+
+ Text to be improved. Only UTF-8-encoded plain text is supported. Improvements are returned in the same order as they are requested. Each of the parameter values may contain multiple sentences.
+
+
+ The language of the improved text. Currently, the following languages are supported:
+
+ * `de` (German)
+ * `en-GB` (British English)
+ * `en-US` (American English)
+ * `es` (Spanish)
+ * `fr` (French)
+ * `it` (Italian)
+ * `ja` (Japanese)
+ * `ko` (Korean)
+ * `pt-BR` (Brazilian Portuguese)
+ * `pt-PT` (Portuguese)
+ * `zh`/`zh-Hans` (simplified Chinese)
+
+ You can also retrieve supported languages programmatically via GET /v3/languages?resource=write.
+
+ The language of the source texts sent in the `text` parameter must match the target language (translating and improving text simultaneously is not yet supported).
+
+ Note that it is possible to convert text from one variant to another within a language. For example, if American English is sent in an API request with `target_lang` set to `EN-GB`, the submitted text will be improved and also converted to British English.
+
+
+ Changes the writing style of your improvements.
+
+
+ * `simple`
+ * `business`
+ * `academic`
+ * `casual`
+ * `default`
+ * `prefer_simple`
+ * `prefer_business`
+ * `prefer_academic`
+ * `prefer_casual`
+
+ Using the `default`value behaves the same as not sending a `writing_style.`
+
+ Currently supported for the following target languages:
+
+ * `de` (German)
+ * `en-GB` (British English)
+ * `en-US` (American English)
+ * `es` (Spanish)
+ * `fr` (French)
+ * `it` (Italian)
+ * `pt-BR` (Brazilian Portuguese)
+ * `pt-PT` (Portuguese)
+
+
+ Styles prefixed with `prefer_` will fall back to the `default` style when used with a language that does not support styles (this is recommended for cases where no `target_lang` is set), the non-prefixed writing styles (except `default`) will return a HTTP 400 error in that case.
+
+ It’s not possible to include both `writing_style` and `tone` in a request; only one or the other can be included.
+
+ To check writing style support dynamically, call GET /v3/languages?resource=write and look for the writing_style feature key on the target language.
+
+
+ Changes the tone of your improvements.
+
+
+ * `enthusiastic`
+ * `friendly`
+ * `confident`
+ * `diplomatic`
+ * `default`
+ * `prefer_enthusiastic`
+ * `prefer_friendly`
+ * `prefer_confident`
+ * `prefer_diplomatic`
+
+ Using the `default`value behaves the same as not sending a `tone`.
+
+
+ Currently supported for the following target languages:
+
+ * `de` (German)
+ * `en-GB` (British English)
+ * `en-US` (American English)
+ * `es` (Spanish)
+ * `fr` (French)
+ * `it` (Italian)
+ * `pt-BR` (Brazilian Portuguese)
+ * `pt-PT` (Portuguese)
+
+ Tones prefixed with `prefer_` will fall back to the `default` tone when used with a language that does not support tones (this is recommended for cases where no `target_lang` is set), the non-prefixed tones (except `default`) will return a HTTP 400 error in that case.
+
+ It’s not possible to include both `writing_style` and `tone` in a request; only one or the other can be included. To check tone support dynamically, call GET /v3/languages?resource=write and look for the tone feature key on the target language.
+
+
+### Response body descriptions
+
+The `/write/rephrase` endpoint returns a JSON object with Improvements under the `improvements` key, which contains an array of `text`, `target_language`, and `detected_source_language` objects. Improvements are returned in the same order as they are requested.
+
+
+ The improved text
+
+
+ The target language specified by the user.
+
+
+ The detected source language of the text provided in the request.
+
+
+### Frequently asked questions
+
+#### Does Cost Control factor in Write API usage?
+
+Yes. If you set a [Cost Control limit](/docs/best-practices/cost-control), it will be enforced against a *sum of Translate API + Write API characters*. At this time, it is not possible to set separate Translate API and Write API cost control limits.
+
+#### Does the /usage endpoint response include Write API characters?
+
+Yes, the `character_count` field in the `/usage` endpoint response returns a sum of Translate API + Write API characters. You can learn more about the `/usage` endpoint [here](/api-reference/usage-and-quota).
+
+#### Do I access the DeepL Write API with the same API keys from my Pro API subscription?
+
+Yes! The Write API is accessed using the same API keys in [the API Keys tab](https://www.deepl.com/en/your-account/keys) that you use to access all other DeepL API endpoints.
+
+#### Can I see DeepL Write API usage in my reporting?
+
+We've added a new column to the [API key-level usage report](/docs/getting-started/managing-api-keys#get-api-key-level-usage) that breaks out text improvement characters separately. The character counts in the [Usage tab](https://www.deepl.com/your-account/usage) of your API account are a sum of both Translate *and* Write characters; these are not yet broken out separately.
+
+#### Is "Corrections Only" mode available in the API?
+
+Yes. Send your request to [`/write/correct`](/api-reference/improve-text/correct-text). This endpoint fixes spelling and grammar errors with minimal changes to wording, matching the "Corrections Only" mode in the DeepL Translator UI.
+
+
+If you instead send a request to `/write/rephrase` and omit both `writing_style` and `tone`, the API uses its default improvement mode. This corrects grammar and spelling but may also make broader changes than `/write/correct`.
diff --git a/api-reference/improve-text/request-text-improvement.mdx b/api-reference/improve-text/request-text-improvement.mdx
index 56c3cbd..9d7dcc1 100644
--- a/api-reference/improve-text/request-text-improvement.mdx
+++ b/api-reference/improve-text/request-text-improvement.mdx
@@ -1,9 +1,7 @@
---
openapi: post /v2/write/rephrase
title: "Improve text"
-description: "Improve one or more texts by correcting spelling and grammar, with optional rewriting for a target style or tone."
+description: "Improves text by correcting spelling and grammar and rewriting for a target writing style or tone."
---
-The `/v2/write/rephrase` endpoint improves one or more texts by correcting spelling and grammar and rephrasing sentences for clarity. With the optional `writing_style` or `tone` parameters, the rewrite targets a specific style or tone. Its corrections-only counterpart, [`/v2/write/correct`](/api-reference/improve-text/correct-text), fixes mistakes with minimal changes to wording.
-
-See the [Improve text overview](/api-reference/improve-text) for supported languages, request body descriptions, response field descriptions, and frequently asked questions.
\ No newline at end of file
+The `/v2/write/rephrase` endpoint improves one or more texts by correcting spelling and grammar and rephrasing sentences for clarity. With the optional `writing_style` or `tone` parameters, the rewrite targets a specific style or tone. Its corrections-only counterpart, [`/v2/write/correct`](/api-reference/improve-text/correct-text), is limited to fixing mistakes with minimal changes to wording.
diff --git a/api-reference/jobs-voice-translate.mdx b/api-reference/jobs-voice-translate.mdx
new file mode 100644
index 0000000..4ea9418
--- /dev/null
+++ b/api-reference/jobs-voice-translate.mdx
@@ -0,0 +1,369 @@
+---
+title: "Translate Audio Files"
+sidebarTitle: "Overview"
+description: "Translate pre-recorded audio files into plain text transcripts, SRT subtitles, or translated speech audio using asynchronous jobs."
+public: true
+---
+
+
+ **Closed alpha.** This API may change without notice and is only available to select DeepL customers. See [alpha and beta features](/docs/resources/alpha-and-beta-features) for details. To request access, contact your customer success manager.
+
+
+The Voice Translate Job API translates pre-recorded audio files into any combination of three output forms in any of its supported target languages:
+
+- **Plain text transcripts** (`text/plain`)
+- **SRT subtitles** (`application/x-subrip`) — preserves the original timecodes
+- **Translated speech audio** — speech-to-speech in a range of audio and video container formats (see the [Reference](/api-reference/jobs-voice-translate/reference#supported-output-formats) for the full list)
+
+The API processes entire audio files asynchronously. This makes it suitable for pre-recorded content such as podcasts, meeting recordings, or other media files. For live audio, see the [real-time Voice API](/api-reference/voice).
+
+Each job can produce multiple outputs from a single source. For example, one English podcast can be translated into German plain text, French SRT subtitles, and Spanish audio in a single job.
+
+For full request and response schemas, see the [Create Job](/api-reference/jobs-voice-translate/create-voice-translate-job) and [Get Job Status](/api-reference/jobs-voice-translate/get-voice-translate-job-status) endpoint references. For status values, limits, supported formats, and supported languages, see the [Reference](/api-reference/jobs-voice-translate/reference).
+
+## Workflow
+
+Translating an audio file is a four-step process. The examples below use the API Pro endpoint `https://api.deepl.com`. API Free users should use `https://api-free.deepl.com` instead.
+
+
+
+ ### Create Job
+ Make a `POST` request to `/v1/jobs/voice/translate` with file metadata, processing parameters, and translation targets.
+
+ The response includes a `job_id`, an `upload_url`, and an upload `signature` for authenticating the upload. (A separate result `signature` is returned per target later, in step 3.)
+
+
+
+ ```sh Example request
+ curl -X POST 'https://api.deepl.com/v1/jobs/voice/translate' \
+ --header 'Authorization: DeepL-Auth-Key [yourAuthKey]' \
+ --header 'Content-Type: application/json' \
+ --data '{
+ "source_file": {
+ "name": "podcast-episode-42.mp3",
+ "content_type": "audio/mpeg",
+ "content_length": 15728640
+ },
+ "parameters": {
+ "source_language": "en"
+ },
+ "targets": [
+ { "language": "de", "type": "text/plain" },
+ { "language": "es", "type": "audio/pcm;encoding=s16le;rate=16000" },
+ { "language": "fr", "type": "application/x-subrip" }
+ ]
+ }'
+ ```
+
+
+ ```http Example request
+ POST /v1/jobs/voice/translate HTTP/2
+ Host: api.deepl.com
+ Authorization: DeepL-Auth-Key [yourAuthKey]
+ Content-Type: application/json
+
+ {
+ "source_file": {
+ "name": "podcast-episode-42.mp3",
+ "content_type": "audio/mpeg",
+ "content_length": 15728640
+ },
+ "parameters": {
+ "source_language": "en"
+ },
+ "targets": [
+ { "language": "de", "type": "text/plain" },
+ { "language": "es", "type": "audio/pcm;encoding=s16le;rate=16000" },
+ { "language": "fr", "type": "application/x-subrip" }
+ ]
+ }
+ ```
+
+
+
+ ```json Example response
+ {
+ "job_id": "a74d88fb-ed2a-4943-a664-a4512398b994",
+ "upload_url": "https://assets.deepl.com/collections/a74d88fb-.../assets/b1c2d3e4-...",
+ "signature": "eyJhbGciOiJIUzI1NiIs..."
+ }
+ ```
+
+ See the [Create Job endpoint reference](/api-reference/jobs-voice-translate/create-voice-translate-job) for the full request and response schema.
+
+
+ ### Upload File
+ Upload the source audio file to the `upload_url` returned in step 1.
+
+
+
+ ```sh Upload with authorization header (recommended)
+ curl -X PUT '{upload_url}' \
+ --header 'Authorization: DeepL-Signature {signature}' \
+ --header 'Content-Type: application/octet-stream' \
+ --data-binary @podcast-episode-42.mp3
+ ```
+
+
+ ```http Upload with authorization header (recommended)
+ PUT {upload_url} HTTP/2
+ Authorization: DeepL-Signature {signature}
+ Content-Type: application/octet-stream
+
+ [binary audio data]
+ ```
+
+
+
+ A successful upload returns `204 No Content` with an empty body. The `Content-Type: application/octet-stream` on the PUT is just for transport; the asset host stores the body as opaque bytes. The audio MIME type from `source_file.content_type` in the create request is what's used for processing.
+
+ See [Choosing an Authentication Method](#choosing-an-authentication-method) for details on the two upload options.
+
+
+ ### Poll Status
+ Poll `GET /v1/jobs/voice/translate/{job_id}` until every result reaches `complete`, `downloaded`, or `failed`. We recommend polling every 5 seconds.
+
+ The `results` array is parallel to `targets`: `results[i]` is the outcome for `targets[i]`. When a result reaches `complete`, it includes its own `download_url` and result `signature` — distinct from the upload signature returned by the create endpoint, and distinct per target. `complete` becomes `downloaded` only after you fetch the result; it does not transition on its own, so it's safe to stop polling at `complete`.
+
+
+
+ ```sh Example request
+ curl 'https://api.deepl.com/v1/jobs/voice/translate/a74d88fb-ed2a-4943-a664-a4512398b994' \
+ --header 'Authorization: DeepL-Auth-Key [yourAuthKey]'
+ ```
+
+
+ ```http Example request
+ GET /v1/jobs/voice/translate/a74d88fb-ed2a-4943-a664-a4512398b994 HTTP/2
+ Host: api.deepl.com
+ Authorization: DeepL-Auth-Key [yourAuthKey]
+ ```
+
+
+
+ ```json Example response: processing
+ {
+ "job_id": "a74d88fb-ed2a-4943-a664-a4512398b994",
+ "product": "voice",
+ "operation": "translate",
+ "created_at": "2026-10-01T01:03:03.444Z",
+ "updated_at": "2026-10-01T04:03:03.333Z",
+ "usage": { "storage_used": 31457280 },
+ "source_file": {
+ "name": "podcast-episode-42.mp3",
+ "content_type": "audio/mpeg",
+ "content_length": 15728640
+ },
+ "parameters": { "source_language": "en" },
+ "targets": [
+ { "language": "de", "type": "text/plain" },
+ { "language": "es", "type": "audio/pcm;encoding=s16le;rate=16000" },
+ { "language": "fr", "type": "application/x-subrip" }
+ ],
+ "results": [
+ { "status": "processing" },
+ { "status": "processing" },
+ { "status": "processing" }
+ ]
+ }
+ ```
+
+ ```json Example response: complete with mixed results
+ {
+ "job_id": "a74d88fb-ed2a-4943-a664-a4512398b994",
+ "product": "voice",
+ "operation": "translate",
+ "created_at": "2026-10-01T01:03:03.444Z",
+ "updated_at": "2026-10-01T04:03:03.333Z",
+ "usage": { "storage_used": 31457280 },
+ "source_file": {
+ "name": "podcast-episode-42.mp3",
+ "content_type": "audio/mpeg",
+ "content_length": 15728640
+ },
+ "parameters": { "source_language": "en" },
+ "targets": [
+ { "language": "de", "type": "text/plain" },
+ { "language": "es", "type": "audio/pcm;encoding=s16le;rate=16000" },
+ { "language": "fr", "type": "application/x-subrip" }
+ ],
+ "results": [
+ {
+ "status": "complete",
+ "download_url": "https://assets.deepl.com/collections/a74d88fb/assets/c3d4e5f6",
+ "signature": "eyJhbGciOiJIUzI1NiIs..."
+ },
+ {
+ "status": "failed",
+ "error": { "message": "processing failed" }
+ },
+ {
+ "status": "complete",
+ "download_url": "https://assets.deepl.com/collections/a74d88fb/assets/d4e5f6a7",
+ "signature": "eyJhbGciOiJIUzI1NiIs..."
+ }
+ ]
+ }
+ ```
+
+ See the [Get Job Status endpoint reference](/api-reference/jobs-voice-translate/get-voice-translate-job-status) for the full response schema, and the [Reference](/api-reference/jobs-voice-translate/reference#result-status-lifecycle) for the status lifecycle.
+
+
+ ### Download Result
+ Download each completed result using the `download_url` and result `signature` from that result entry in the poll response. Each completed target has its own pair; signatures are not interchangeable across targets, and the upload signature from step 1 cannot be used here.
+
+
+
+ ```sh Download with authorization header (recommended)
+ curl '{download_url}' \
+ --header 'Authorization: DeepL-Signature {signature}' \
+ --output translated-output.txt
+ ```
+
+
+ ```http Download with authorization header (recommended)
+ GET {download_url} HTTP/2
+ Authorization: DeepL-Signature {signature}
+ ```
+
+
+
+ A successful download returns `200 OK` with the translated file as the binary response body.
+
+ After a result is downloaded, its status changes to `downloaded` and the assets are marked for deletion. See [Choosing an Authentication Method](#choosing-an-authentication-method) for details on the two download options.
+
+
+
+## Complete Example
+
+The following Python script runs all four steps end-to-end: it creates a job, uploads the source file, polls until every target reaches a terminal state, and downloads each completed result.
+
+```python complete_example.py
+import os
+import time
+from pathlib import Path
+
+import requests
+
+API_BASE = "https://api.deepl.com"
+AUTH_KEY = os.environ["DEEPL_AUTH_KEY"]
+SOURCE_PATH = Path("podcast-episode-42.mp3")
+
+api_headers = {"Authorization": f"DeepL-Auth-Key {AUTH_KEY}"}
+
+# 1. Create the job
+create_resp = requests.post(
+ f"{API_BASE}/v1/jobs/voice/translate",
+ headers={**api_headers, "Content-Type": "application/json"},
+ json={
+ "source_file": {
+ "name": SOURCE_PATH.name,
+ "content_type": "audio/mpeg",
+ "content_length": SOURCE_PATH.stat().st_size,
+ },
+ "parameters": {"source_language": "en"},
+ "targets": [
+ {"language": "de", "type": "text/plain"},
+ {"language": "es", "type": "audio/pcm;encoding=s16le;rate=16000"},
+ {"language": "fr", "type": "application/x-subrip"},
+ ],
+ },
+)
+create_resp.raise_for_status()
+job = create_resp.json()
+job_id = job["job_id"]
+
+# 2. Upload the source file using the upload signature
+with SOURCE_PATH.open("rb") as f:
+ upload_resp = requests.put(
+ job["upload_url"],
+ headers={
+ "Authorization": f"DeepL-Signature {job['signature']}",
+ "Content-Type": "application/octet-stream",
+ },
+ data=f,
+ )
+upload_resp.raise_for_status()
+
+# 3. Poll until every result is complete, downloaded, or failed
+TERMINAL = {"complete", "downloaded", "failed"}
+while True:
+ status_resp = requests.get(
+ f"{API_BASE}/v1/jobs/voice/translate/{job_id}",
+ headers=api_headers,
+ )
+ status_resp.raise_for_status()
+ status = status_resp.json()
+ if all(r["status"] in TERMINAL for r in status["results"]):
+ break
+ time.sleep(5)
+
+# 4. Download each completed result with its own result signature
+for target, result in zip(status["targets"], status["results"]):
+ if result["status"] != "complete":
+ print(f"{target['language']} ({target['type']}): {result['status']}")
+ continue
+ download_resp = requests.get(
+ result["download_url"],
+ headers={"Authorization": f"DeepL-Signature {result['signature']}"},
+ )
+ download_resp.raise_for_status()
+ suffix = {"text/plain": ".txt", "application/x-subrip": ".srt"}.get(target["type"], ".bin")
+ out_path = Path(f"output-{target['language']}{suffix}")
+ out_path.write_bytes(download_resp.content)
+ print(f"{target['language']}: wrote {out_path}")
+```
+
+Run it with `DEEPL_AUTH_KEY=... python complete_example.py`.
+
+## Choosing an Authentication Method
+
+There are two ways to authenticate uploads and downloads. The default is the `Authorization: DeepL-Signature {signature}` header, which the workflow examples above use. The alternative is a pre-signed URL, opted into per request with `?include=signed_url`.
+
+| **Method** | **How it's used** | **When to use it** |
+| :--------------------------------- | :----------------------------------------------------------------------------- | :------------------------------------------------------------------------------------------------------- |
+| `Authorization` header (default) | Send `Authorization: DeepL-Signature {signature}` on the PUT/GET | Server-to-server flows you control. Don't expose the signature to untrusted clients. |
+| Pre-signed URL (`?include=signed_url`) | Use `signed_upload_url` / `signed_download_url` directly; no auth header needed | Browsers, mobile clients, or any caller that can't set custom headers. |
+
+Both methods use the same time-limited windows: 5 minutes for upload after job creation, 1 hour for download after upload. The `signature` and signed URL stop working when those windows close.
+
+
+ Use the `Authorization` header by default. A leaked signed URL could allow an attacker to upload malicious content to your job or download your results.
+
+
+### Pre-signed URL example
+
+Add `?include=signed_url` to the create or poll request to receive pre-signed URLs alongside the regular ones.
+
+```sh Create with signed URL
+curl -X POST 'https://api.deepl.com/v1/jobs/voice/translate?include=signed_url' \
+--header 'Authorization: DeepL-Auth-Key [yourAuthKey]' \
+--header 'Content-Type: application/json' \
+--data '{ ... }'
+```
+
+```json Response includes signed_upload_url
+{
+ "job_id": "a74d88fb-ed2a-4943-a664-a4512398b994",
+ "upload_url": "https://assets.deepl.com/collections/a74d88fb/assets/b1c2d3e4",
+ "signature": "eyJhbGciOiJIUzI1NiIs...",
+ "signed_upload_url": "https://assets.deepl.com/collections/a74d88fb/assets/b1c2d3e4?X-Signature=eyJhbGciOi..."
+}
+```
+
+```sh Upload using the signed URL (no auth header)
+curl -X PUT '{signed_upload_url}' \
+--header 'Content-Type: application/octet-stream' \
+--data-binary @podcast-episode-42.mp3
+```
+
+The same pattern applies to downloads: pass `?include=signed_url` to the poll request, and each completed result will also include `signed_download_url`.
+
+## Next Steps
+
+Now that you understand how to translate audio files asynchronously:
+
+- **Create a job:** Review the [Create Job endpoint reference](/api-reference/jobs-voice-translate/create-voice-translate-job) for the full request and response schema
+- **Poll job status:** Review the [Get Job Status endpoint reference](/api-reference/jobs-voice-translate/get-voice-translate-job-status) for the full response schema
+- **Look up limits and formats:** See the [Reference](/api-reference/jobs-voice-translate/reference) for status values, limits, supported audio formats, languages, and output formats
+- **Try realtime translation:** Use the [Voice API](/api-reference/voice) for streaming audio translation over WebSocket instead of batch processing
diff --git a/api-reference/jobs-voice-translate/create-voice-translate-job.mdx b/api-reference/jobs-voice-translate/create-voice-translate-job.mdx
index 21c7e58..9da2298 100644
--- a/api-reference/jobs-voice-translate/create-voice-translate-job.mdx
+++ b/api-reference/jobs-voice-translate/create-voice-translate-job.mdx
@@ -1,16 +1,4 @@
---
openapi: post /v1/jobs/voice/translate
title: "Create a voice translation job"
-description: "Create an asynchronous job to translate a pre-recorded audio file into text, SRT subtitles, or translated speech audio."
---
-
-Creates an asynchronous job for translating a pre-recorded audio file. The response includes a `job_id`, an `upload_url`, and an upload `signature` for authenticating the file upload.
-
-Translating an audio file is a four-step process:
-
-1. **Create job** — `POST /v1/jobs/voice/translate` (this endpoint)
-2. **Upload file** — PUT the source audio to the `upload_url` from step 1
-3. **Poll status** — `GET /v1/jobs/voice/translate/{job_id}` until all results reach a terminal state
-4. **Download results** — Fetch each completed result using its `download_url` and result `signature`
-
-See the [Translate Audio Files overview](/api-reference/jobs-voice-translate) for the complete workflow, a runnable end-to-end Python example, authentication method details, and supported formats.
\ No newline at end of file
diff --git a/api-reference/languages.mdx b/api-reference/languages.mdx
new file mode 100644
index 0000000..fb8fc03
--- /dev/null
+++ b/api-reference/languages.mdx
@@ -0,0 +1,387 @@
+---
+title: "Retrieve languages (v2)"
+sidebarTitle: "Overview"
+description: "Reference for the deprecated v2/languages endpoint. Migrate to v3/languages for new integrations."
+---
+
+
+ **`/v2/languages` is deprecated.** Use [`GET /v3/languages`](/api-reference/languages/retrieve-supported-languages-by-resource) instead, which covers all DeepL API resources and provides richer feature information. See the [migration guide](/api-reference/languages/migrate-from-v2-languages) for details.
+
+
+`GET /v2/languages` returns the source and target languages supported for text and document translation. New integrations should use `/v3/languages`, which exposes the same translation languages along with feature support for glossaries, voice, write, and other resources.
+
+For background on how DeepL adds new translation languages and language variants, see [the language release process](/docs/resources/language-release-process). For the auto-generated reference spec for this endpoint, see [Retrieve supported languages](/api-reference/languages/retrieve-supported-languages).
+
+
+
+
+The example below uses our API Pro endpoint `https://api.deepl.com`. If you're an API Free user, remember to update your requests to use `https://api-free.deepl.com` instead.
+
+```sh Example request: supported target languages
+curl -X GET 'https://api.deepl.com/v2/languages?type=target' \
+--header 'Authorization: DeepL-Auth-Key [yourAuthKey]'
+```
+
+```json Example response
+[
+ {
+ "language": "AR",
+ "name": "Arabic",
+ "supports_formality": false
+ },
+ {
+ "language": "BG",
+ "name": "Bulgarian",
+ "supports_formality": false
+ },
+ {
+ "language": "CS",
+ "name": "Czech",
+ "supports_formality": false
+ },
+ {
+ "language": "DA",
+ "name": "Danish",
+ "supports_formality": false
+ },
+ {
+ "language": "DE",
+ "name": "German",
+ "supports_formality": true
+ },
+ {
+ "language": "EL",
+ "name": "Greek",
+ "supports_formality": false
+ },
+ {
+ "language": "EN-GB",
+ "name": "English (British)",
+ "supports_formality": false
+ },
+ {
+ "language": "EN-US",
+ "name": "English (American)",
+ "supports_formality": false
+ },
+ {
+ "language": "ES",
+ "name": "Spanish",
+ "supports_formality": true
+ },
+ {
+ "language": "ES-419",
+ "name": "Spanish (Latin American)",
+ "supports_formality": true
+ },
+ {
+ "language": "ET",
+ "name": "Estonian",
+ "supports_formality": false
+ },
+ {
+ "language": "FI",
+ "name": "Finnish",
+ "supports_formality": false
+ },
+ {
+ "language": "FR",
+ "name": "French",
+ "supports_formality": true
+ },
+ {
+ "language": "HU",
+ "name": "Hungarian",
+ "supports_formality": false
+ },
+ {
+ "language": "ID",
+ "name": "Indonesian",
+ "supports_formality": false
+ },
+ {
+ "language": "IT",
+ "name": "Italian",
+ "supports_formality": true
+ },
+ {
+ "language": "JA",
+ "name": "Japanese",
+ "supports_formality": true
+ },
+ {
+ "language": "KO",
+ "name": "Korean",
+ "supports_formality": false
+ },
+ {
+ "language": "LT",
+ "name": "Lithuanian",
+ "supports_formality": false
+ },
+ {
+ "language": "LV",
+ "name": "Latvian",
+ "supports_formality": false
+ },
+ {
+ "language": "NB",
+ "name": "Norwegian (Bokmål)",
+ "supports_formality": false
+ },
+ {
+ "language": "NL",
+ "name": "Dutch",
+ "supports_formality": true
+ },
+ {
+ "language": "PL",
+ "name": "Polish",
+ "supports_formality": true
+ },
+ {
+ "language": "PT-BR",
+ "name": "Portuguese (Brazilian)",
+ "supports_formality": true
+ },
+ {
+ "language": "PT-PT",
+ "name": "Portuguese (European)",
+ "supports_formality": true
+ },
+ {
+ "language": "RO",
+ "name": "Romanian",
+ "supports_formality": false
+ },
+ {
+ "language": "RU",
+ "name": "Russian",
+ "supports_formality": true
+ },
+ {
+ "language": "SK",
+ "name": "Slovak",
+ "supports_formality": false
+ },
+ {
+ "language": "SL",
+ "name": "Slovenian",
+ "supports_formality": false
+ },
+ {
+ "language": "SV",
+ "name": "Swedish",
+ "supports_formality": false
+ },
+ {
+ "language": "TR",
+ "name": "Turkish",
+ "supports_formality": false
+ },
+ {
+ "language": "UK",
+ "name": "Ukrainian",
+ "supports_formality": false
+ },
+ {
+ "language": "ZH",
+ "name": "Chinese (simplified)",
+ "supports_formality": false
+ },
+ {
+ "language": "ZH-HANS",
+ "name": "Chinese (simplified)",
+ "supports_formality": false
+ },
+ {
+ "language": "ZH-HANT",
+ "name": "Chinese (traditional)",
+ "supports_formality": false
+ }
+]
+```
+
+
+```http Example request: supported target languages
+GET /v2/languages?type=target HTTP/2
+Host: api.deepl.com
+Authorization: DeepL-Auth-Key [yourAuthKey]
+User-Agent: YourApp/1.2.3
+```
+```json Example response
+[
+ {
+ "language": "BG",
+ "name": "Bulgarian",
+ "supports_formality": false
+ },
+ {
+ "language": "CS",
+ "name": "Czech",
+ "supports_formality": false
+ },
+ {
+ "language": "DA",
+ "name": "Danish",
+ "supports_formality": false
+ },
+ {
+ "language": "DE",
+ "name": "German",
+ "supports_formality": true
+ },
+ {
+ "language": "EL",
+ "name": "Greek",
+ "supports_formality": false
+ },
+ {
+ "language": "EN-GB",
+ "name": "English (British)",
+ "supports_formality": false
+ },
+ {
+ "language": "EN-US",
+ "name": "English (American)",
+ "supports_formality": false
+ },
+ {
+ "language": "ES",
+ "name": "Spanish",
+ "supports_formality": true
+ },
+ {
+ "language": "ES-419",
+ "name": "Spanish (Latin American)",
+ "supports_formality": true
+ },
+ {
+ "language": "ET",
+ "name": "Estonian",
+ "supports_formality": false
+ },
+ {
+ "language": "FI",
+ "name": "Finnish",
+ "supports_formality": false
+ },
+ {
+ "language": "FR",
+ "name": "French",
+ "supports_formality": true
+ },
+ {
+ "language": "HU",
+ "name": "Hungarian",
+ "supports_formality": false
+ },
+ {
+ "language": "ID",
+ "name": "Indonesian",
+ "supports_formality": false
+ },
+ {
+ "language": "IT",
+ "name": "Italian",
+ "supports_formality": true
+ },
+ {
+ "language": "JA",
+ "name": "Japanese",
+ "supports_formality": true
+ },
+ {
+ "language": "KO",
+ "name": "Korean",
+ "supports_formality": false
+ },
+ {
+ "language": "LT",
+ "name": "Lithuanian",
+ "supports_formality": false
+ },
+ {
+ "language": "LV",
+ "name": "Latvian",
+ "supports_formality": false
+ },
+ {
+ "language": "NB",
+ "name": "Norwegian (Bokmål)",
+ "supports_formality": false
+ },
+ {
+ "language": "NL",
+ "name": "Dutch",
+ "supports_formality": true
+ },
+ {
+ "language": "PL",
+ "name": "Polish",
+ "supports_formality": true
+ },
+ {
+ "language": "PT-BR",
+ "name": "Portuguese (Brazilian)",
+ "supports_formality": true
+ },
+ {
+ "language": "PT-PT",
+ "name": "Portuguese (European)",
+ "supports_formality": true
+ },
+ {
+ "language": "RO",
+ "name": "Romanian",
+ "supports_formality": false
+ },
+ {
+ "language": "RU",
+ "name": "Russian",
+ "supports_formality": true
+ },
+ {
+ "language": "SK",
+ "name": "Slovak",
+ "supports_formality": false
+ },
+ {
+ "language": "SL",
+ "name": "Slovenian",
+ "supports_formality": false
+ },
+ {
+ "language": "SV",
+ "name": "Swedish",
+ "supports_formality": false
+ },
+ {
+ "language": "TR",
+ "name": "Turkish",
+ "supports_formality": false
+ },
+ {
+ "language": "UK",
+ "name": "Ukrainian",
+ "supports_formality": false
+ },
+ {
+ "language": "ZH",
+ "name": "Chinese (simplified)",
+ "supports_formality": false
+ },
+ {
+ "language": "ZH-HANS",
+ "name": "Chinese (simplified)",
+ "supports_formality": false
+ }
+]
+```
+
+
+### Query parameters
+
+
+Supported values are `source` or `target`. If type parameter is not included, defaults to `source`.
+
diff --git a/api-reference/languages/language-feature-use-cases.mdx b/api-reference/languages/language-feature-use-cases.mdx
new file mode 100644
index 0000000..3575280
--- /dev/null
+++ b/api-reference/languages/language-feature-use-cases.mdx
@@ -0,0 +1,152 @@
+---
+title: 'Common use cases'
+description: "Pseudocode examples for common language and feature lookup patterns using the v3/languages endpoints."
+---
+
+This page shows how to use the `/v3/languages` endpoints for common integration tasks. Examples are written
+as pseudocode and are resource-agnostic unless otherwise noted.
+
+For background on how features and feature dependency types work, see the
+[overview](/api-reference/languages/retrieve-supported-languages-by-resource).
+
+---
+
+## Populate source and target language dropdowns
+
+A single call to `GET /v3/languages` returns all languages for a resource. Filter by `usable_as_source` and
+`usable_as_target` to populate each dropdown separately.
+
+```
+GET /v3/languages?resource=translate_text
+
+languages = response
+
+source_options = languages.filter(l => l.usable_as_source)
+target_options = languages.filter(l => l.usable_as_target)
+
+render source_dropdown(source_options)
+render target_dropdown(target_options)
+```
+
+---
+
+## Show formality options only when supported
+
+`formality` only needs to be supported by the target language. Check the selected target language's `features`
+object — no need to look at the source language.
+
+```
+GET /v3/languages?resource=translate_text
+
+languages = response
+target = languages.find(l => l.lang == selected_target_lang)
+
+if "formality" in target.features:
+ show formality_selector // e.g. ["default", "more", "less"]
+else:
+ hide formality_selector
+```
+
+---
+
+## Check if a glossary can be used for a given language pair
+
+`glossary` must be supported by both languages.
+
+```
+GET /v3/languages?resource=translate_text
+
+languages = response
+
+source = languages.find(l => l.lang == source_lang)
+target = languages.find(l => l.lang == target_lang)
+
+glossary_allowed = "glossary" in source.features
+ and "glossary" in target.features
+```
+
+---
+
+## List target languages that accept glossaries from a given source language
+
+Filter to targets where both the source and target support the `glossary` feature.
+
+```
+GET /v3/languages?resource=translate_text
+
+languages = response
+source_lang = "en"
+
+source = languages.find(l => l.lang == source_lang)
+
+if "glossary" not in source.features:
+ return [] // source doesn't support glossary at all
+
+targets_with_glossary = languages
+ .filter(l => l.usable_as_target)
+ .filter(l => "glossary" in l.features)
+```
+
+---
+
+## Show writing style options for the Write resource
+
+`writing_style` is a target-only feature on the `write` resource. Check the target language's `features` object.
+
+```
+GET /v3/languages?resource=write
+
+languages = response
+target = languages.find(l => l.lang == selected_target_lang)
+
+if "writing_style" in target.features:
+ show writing_style_selector
+else:
+ hide writing_style_selector
+```
+
+---
+
+## Check if style rules are available for a target language
+
+Use `resource=style_rules` to query which languages support style rules. Style rules are target-language only — check
+that the target language is listed in the response. The `style_rules` resource has no additional features, so only
+the language availability needs to be checked.
+
+```
+GET /v3/languages?resource=style_rules
+
+languages = response
+target = languages.find(l => l.lang == selected_target_lang)
+
+if target and target.usable_as_target:
+ show style_rules_selector
+else:
+ hide style_rules_selector
+```
+
+---
+
+## Determine feature support programmatically
+
+Use `/v3/languages/resources` to drive feature checks at runtime — without hardcoding which features need
+target-only or both-language support into your client.
+
+```
+GET /v3/languages/resources
+GET /v3/languages?resource=translate_text
+
+resources = first response
+languages = second response
+
+resource = resources.find(r => r.name == "translate_text")
+source = languages.find(l => l.lang == source_lang)
+target = languages.find(l => l.lang == target_lang)
+
+for feature in resource.features:
+ supported = true
+ if feature.needs_source_support and feature.name not in source.features:
+ supported = false
+ if feature.needs_target_support and feature.name not in target.features:
+ supported = false
+```
diff --git a/api-reference/languages/retrieve-languages-by-resource.mdx b/api-reference/languages/retrieve-languages-by-resource.mdx
index 9fa35ea..be1a0ba 100644
--- a/api-reference/languages/retrieve-languages-by-resource.mdx
+++ b/api-reference/languages/retrieve-languages-by-resource.mdx
@@ -1,84 +1,5 @@
---
openapi: get /v3/languages
title: "Retrieve languages"
-description: "Retrieve supported languages and feature availability for a specific DeepL API resource."
---
-Returns the languages supported for a given DeepL API resource, along with feature availability per language (such as formality, glossary support, transcription, and writing style).
-
-Use the `resource` query parameter to filter results by API product. Supported values include `translate_text`, `translate_document`, `glossary`, `write`, and `voice`.
-
-This endpoint replaces the deprecated [`GET /v2/languages`](/api-reference/languages/retrieve-supported-languages) endpoint. See the [migration guide](/api-reference/languages/migrate-from-v2-languages) for details.
-
-## Common use cases
-
-Examples below are pseudocode showing common integration patterns.
-
-### Populate source and target language dropdowns
-
-```
-GET /v3/languages?resource=translate_text
-
-languages = response
-
-source_options = languages.filter(l => l.usable_as_source)
-target_options = languages.filter(l => l.usable_as_target)
-
-render source_dropdown(source_options)
-render target_dropdown(target_options)
-```
-
-### Show formality options only when supported
-
-`formality` only needs to be supported by the target language. Check the selected target language's `features` object.
-
-```
-GET /v3/languages?resource=translate_text
-
-languages = response
-target = languages.find(l => l.lang == selected_target_lang)
-
-if "formality" in target.features:
- show formality_selector
-else:
- hide formality_selector
-```
-
-### Check if a glossary can be used for a given language pair
-
-`glossary` must be supported by both languages.
-
-```
-GET /v3/languages?resource=translate_text
-
-languages = response
-
-source = languages.find(l => l.lang == source_lang)
-target = languages.find(l => l.lang == target_lang)
-
-glossary_allowed = "glossary" in source.features
- and "glossary" in target.features
-```
-
-### Determine feature support programmatically
-
-Use `/v3/languages/resources` to drive feature checks at runtime without hardcoding which features need target-only or both-language support.
-
-```
-GET /v3/languages/resources
-GET /v3/languages?resource=translate_text
-
-resources = first response
-languages = second response
-
-resource = resources.find(r => r.name == "translate_text")
-source = languages.find(l => l.lang == source_lang)
-target = languages.find(l => l.lang == target_lang)
-
-for feature in resource.features:
- supported = true
- if feature.needs_source_support and feature.name not in source.features:
- supported = false
- if feature.needs_target_support and feature.name not in target.features:
- supported = false
-```
\ No newline at end of file
diff --git a/api-reference/languages/retrieve-supported-languages-by-resource.mdx b/api-reference/languages/retrieve-supported-languages-by-resource.mdx
new file mode 100644
index 0000000..0ff33e9
--- /dev/null
+++ b/api-reference/languages/retrieve-supported-languages-by-resource.mdx
@@ -0,0 +1,246 @@
+---
+title: 'Retrieve supported languages by resource'
+sidebarTitle: 'Overview'
+description: "Learn how to retrieve supported language and feature data across all DeepL API resources"
+---
+
+
+ The `/v3/languages` endpoints replace the deprecated `/v2/languages` and `/v2/glossary-language-pairs` endpoints.
+ If you're currently using either, see the [migration guide](/api-reference/languages/migrate-from-v2-languages) for
+ differences and code examples.
+
+
+We also provide auto-generated API specs from DeepL's OpenAPI file, for use with API clients and code generation tools:
+- [Retrieve languages](/api-reference/languages/retrieve-languages-by-resource)
+- [Retrieve resources](/api-reference/languages/retrieve-resources)
+
+To understand how we'll update these endpoints when we add translation support for a new language or language variant, please see [this article](/docs/resources/language-release-process).
+
+## Resources list
+
+To retrieve language support, decide which DeepL resource you're building for, then call `GET /v3/languages` with
+the appropriate `resource` value. The `resource` parameter is required and identifies which DeepL API resource you
+are querying language support for:
+
+| **Value** | **Description** |
+|---|---|
+| `translate_text` | Text translation via the `/v2/translate` endpoint |
+| `translate_document` | Document translation via the `/v2/document` endpoint |
+| `voice` | Speech transcription and translation via the `/v3/voice` endpoints |
+| `write` | Text improvement via the `/v2/write` endpoints |
+| `glossary` | Glossary management via the `/v2/` and `/v3/glossaries` endpoints |
+| `style_rules` | Style rules management via the `/v3/style_rules` endpoints |
+
+
+ `glossary` and `style_rules` are resource values indicating glossaries and style rules that can be created for that
+ language, and managed via the glossary and style rules management endpoints.
+
+ Support for glossaries and style rules within specific resources (for example text translation) is indicated by the
+ `glossary` and `style_rules` feature value, explained in a later section.
+
+
+## Basic example
+
+Each language in the response includes a `features` object indicating which optional capabilities are available for that
+language — see the [Resource features](#resource-features) section below for details.
+
+The examples below use our API Pro endpoint `https://api.deepl.com`. If you're an API Free user, remember to update
+your requests to use `https://api-free.deepl.com` instead.
+
+The following example responses are truncated; the full API responses can include over 100 languages.
+
+
+
+
+```sh Example request: languages for text translation
+curl -X GET 'https://api.deepl.com/v3/languages?resource=translate_text' \
+--header 'Authorization: DeepL-Auth-Key [yourAuthKey]'
+```
+
+
+
+```http Example request: languages for text translation
+GET /v3/languages?resource=translate_text HTTP/2
+Host: api.deepl.com
+Authorization: DeepL-Auth-Key [yourAuthKey]
+User-Agent: YourApp/1.2.3
+```
+
+
+
+```json Example response
+[
+ {
+ "lang": "de",
+ "name": "German",
+ "usable_as_source": true,
+ "usable_as_target": true,
+ "status": "stable",
+ "features": {
+ "formality": {"status": "stable"},
+ "tag_handling": {"status": "stable"},
+ "glossary": {"status": "stable"}
+ }
+ },
+ {
+ "lang": "en",
+ "name": "English",
+ "usable_as_source": true,
+ "usable_as_target": false,
+ "status": "stable",
+ "features": {
+ "tag_handling": {"status": "stable"},
+ "glossary": {"status": "stable"}
+ }
+ },
+ {
+ "lang": "en-US",
+ "name": "English (American)",
+ "usable_as_source": false,
+ "usable_as_target": true,
+ "status": "stable",
+ "features": {
+ "tag_handling": {"status": "stable"},
+ "glossary": {"status": "stable"}
+ }
+ }
+]
+```
+
+## Language codes
+
+Language codes in the `lang` field follow [BCP 47](https://www.rfc-editor.org/rfc/rfc5646). The base language
+subtag is always present; script, region, and variant subtags are included where needed to distinguish variants. See [Language codes follow BCP 47](/docs/resources/language-release-process#language-codes-follow-bcp-47) for details.
+
+## Resource features
+
+Each language object includes a `features` object indicating which optional capabilities are supported for that language
+with the requested resource. Each key is a feature name; the value is an object with at least a `status` field.
+
+To check whether a feature is supported, check that the key exists in the `features` object:
+
+```text
+// Feature supported:
+"features": { "formality": { "status": "stable" } }
+
+// Feature not supported:
+"features": {}
+```
+
+To use a feature, one or both languages in the pair must support it. For example, for text translation:
+
+- **Target-only**: `formality` only needs to be supported by the target language. Check that `"formality"` is
+ a key in the target language's `features` object.
+- **Source-and-target**: `tag_handling` and `glossary` must be supported by both languages. Check that the
+ feature key is present in *both* the source and target language's `features` objects.
+- **Source-only**: `auto_detection` only needs to be supported by the source language.
+
+In the documentation for API features that are supported for only a subset of languages, we specify
+which language feature key to check, and whether to check the source language, target language, or both.
+
+### Resource feature reference
+
+The table below lists all feature keys that can appear in a language's `features` object.
+
+| **Feature** | **Check language support on** | **Resources** | **Description** |
+|------------------------------|---------------------------|-----------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| `auto_detection` | source | `translate_text`, `translate_document`, `voice`, `write` | Language can be automatically detected as the source language. |
+| `style_rules` | target | `translate_text` | Language supports style rules that guide how DeepL translates text. Used with the `custom_instructions` and `style_id` parameters on the translate endpoint. |
+| `formality` | target | `translate_text`, `translate_document`, `voice` | Language supports formality control — adjusting the output to use formal or informal register. |
+| `glossary` | source + target | `translate_text`, `translate_document`, `voice` | Language can be used with a glossary to enforce specific terminology. Both the source and target language must support this for a glossary to be usable with a given pair. |
+| `tag_handling` | source + target | `translate_text`, `translate_document` | Language supports tag-aware translation, preserving markup structure (e.g. HTML, XML) in the output. |
+| `transcription` | source | `voice` | Language supports transcription from audio to text. |
+| `translated_speech` | target | `voice` | Language supports conversion from translated text to audio output. |
+| `spoken_terms` | source | `voice` | Language supports spoken terms lists that improve transcription of frequently used terms. Used with the `spoken_terms_id` parameter on the voice request session endpoint. |
+| `tone` | target | `write` | Language supports tone selection (e.g. confident, diplomatic, enthusiastic). |
+| `writing_style` | target | `write` | Language supports writing style selection (e.g. academic, casual, business). |
+
+## Filtering by availability
+
+By default, `GET /v3/languages` returns only stable languages and features. Use the `include` query parameter
+to request additional languages and features based on their availability status:
+
+| **Value** | **Effect** |
+|---|---|
+| `beta` | Includes languages and features in beta, in addition to stable |
+| `external` | Includes features that rely on third-party service providers |
+
+Values can be combined with repeated parameters: `?include=beta&include=external`.
+
+The `status` field on each language object and each feature object indicates its availability:
+
+| **Status** | **Meaning** |
+|---|---|
+| `stable` | Generally available |
+| `beta` | Available for testing; may change |
+| `early_access` | Limited availability; may change |
+
+## Retrieving resources programmatically
+
+Use the `/v3/languages/resources` endpoint to retrieve the list of resources and their features programmatically.
+For each feature, the response indicates which languages must support it for the feature to be available —
+source only, target only, or both — allowing clients to determine feature availability for a language pair
+by checking the appropriate `features` objects.
+
+```sh
+curl -X GET 'https://api.deepl.com/v3/languages/resources' \
+--header 'Authorization: DeepL-Auth-Key [yourAuthKey]'
+```
+
+```json Example response (truncated)
+[
+ {
+ "name": "translate_text",
+ "features": [
+ {
+ "name": "formality",
+ "needs_target_support": true
+ },
+ {
+ "name": "style_rules",
+ "needs_target_support": true
+ },
+ {
+ "name": "tag_handling",
+ "needs_source_support": true,
+ "needs_target_support": true
+ },
+ {
+ "name": "glossary",
+ "needs_source_support": true,
+ "needs_target_support": true
+ },
+ {
+ "name": "auto_detection",
+ "needs_source_support": true
+ }
+ ]
+ }
+]
+```
+
+## API stability
+
+The v3 language endpoints are designed to be forward-compatible:
+
+- New feature keys may be added to the `features` object
+- New languages will be added as DeepL support expands
+- Existing fields will not be removed or changed in backwards-incompatible ways
+
+In rare cases, a language may be removed from the default response (for example, if it moves from stable
+to beta). When this happens, it will still be accessible via `?include=beta`. We aim to avoid this, but
+build your integration to handle languages disappearing from the response gracefully.
+
+
+ Build your integration to gracefully handle new BCP 47 `lang` codes and new feature keys in the `features` object. Do not hardcode assumptions about the format of language codes. See [Language codes follow BCP 47](/docs/resources/language-release-process#language-codes-follow-bcp-47) for details.
+
+
+## Best practices
+
+1. **Cache responses**: Language support changes infrequently. Consider caching responses for up to 1 hour.
+
+2. **Check features**: Always check the `features` object on language objects rather than assuming support (e.g. for formality, glossary use, or writing style).
+
+3. **Handle forward compatibility**: New languages and features may be added at any time. Build your integration to dynamically accept new `lang` codes and new keys in the `features` object instead of maintaining a hardcoded allowlist.
+
+4. **Use specific variants**: For target languages, prefer specific regional variants (e.g., `"en-US"`, `"en-GB"`) when the distinction matters to your users.
diff --git a/api-reference/multilingual-glossaries.mdx b/api-reference/multilingual-glossaries.mdx
new file mode 100644
index 0000000..1a51d00
--- /dev/null
+++ b/api-reference/multilingual-glossaries.mdx
@@ -0,0 +1,721 @@
+---
+title: "Glossaries"
+public: true
+sidebarTitle: "Overview"
+description: "Manage and use DeepL glossaries"
+---
+
+
+ This page documents `v3` glossary endpoints, which let you **edit** glossaries and allow for **multilingual** functionality.
+
+ The current`v3` endpoints are used for working with **both multilingual and monolingual** glossaries. Thus, we recommend you start using the `v3` endpoints described below for all glossary needs.
+
+ The previously used [v2 glossary endpoints](/api-reference/glossaries) can only be used with **monolingual** glossaries. [See here](/api-reference/glossaries/v2-vs-v3-endpoints) for more on the difference between `v2` and `v3` glossary endpoints.
+
+
+
+## Overview
+
+The `glossaries` endpoints let you work with [DeepL glossaries](https://support.deepl.com/hc/en-us/articles/360021634540-About-the-glossary), which let you specify specific translations for words or short phrases. Each glossary contains a mapping of source phrases to target phrases. During translation, DeepL intelligently flexes entries to account for case, gender, tense, and other grammar features (if the target language has flexion). You can create glossaries with [any of the languages listed here](/docs/getting-started/supported-languages).
+
+A **glossary** contains (several) **dictionaries**. A **dictionary** is a mapping of source phrases to target phrases for a single language pair, like this:
+
+| French → | Spanish |
+| --------- | --------- |
+| belle | hermosa |
+| delicieux | exquisito |
+| mouse | mouse |
+
+Note that this mapping occurs only in one direction, which is all you need during a single translation. If you wanted your glossary to contain the reverse mapping, so that you could apply the same glossary when translating from French to Spanish and from Spanish to French, you would add a second dictionary:
+
+| Spanish → | French |
+| --------- | --------- |
+| hermosa | belle |
+| exquisito | delicieux |
+| mouse | mouse |
+
+Both glossaries and style rules are unique to each of DeepL's global data centers and are not shared between them. Clients using the `api-us.deepl.com` endpoint will not be able to access glossaries or style rules created in the UI at this time.
+
+
+## Creating glossaries
+
+### Formats
+
+You can format glossary entries as either CSV (comma-separated values) or TSV (tab-separated values). In each case, each entry is a line containing a source phrase and its associated target phrase.
+
+CSV entries for our Spanish → French glossary above would look like this:
+
+```
+hermosa,belle
+exquisito,delicieux
+mouse,mouse
+```
+
+You can also enclose each phrase in quotation marks:
+
+```
+"hermosa","belle"
+"exquisito","delicieux"
+"mouse","mouse"
+```
+
+TSV is similar, except that the source and target phrases are separated by a tab, not a comma.
+
+CSV entries in DeepL glossaries follow standard CSV conventions, such as
+
+- fields containing double quotes or commas must be enclosed in double quotes,
+- if double quotes are used to enclose fields, then a double quote appearing inside a field must be escaped by preceding it with another double quote.
+
+
+ In CSV, you can also include the source and target language after the source and target phrases. If those do not match the language pair for the current dictionary, the entry will be ignored.
+
+
+### Create a glossary
+
+`POST /v3/glossaries`
+
+To create a glossary, send the API an array that contains one or more dictionaries. (As described above, a dictionary is a collection of mappings from source phrases in one language to target phrases in another.)
+
+This example creates a modest glossary with two dictionaries. One maps "Hello" in English to "Guten Tag" in German. The other contains the reverse mapping.
+
+
+
+ The example below uses our API Pro endpoint `https://api.deepl.com`. If you're an API Free user, remember to update your requests to use `https://api-free.deepl.com` instead.
+
+ ```sh Example request: create a glossary
+ curl -X POST 'https://api.deepl.com/v3/glossaries' \
+ --header 'Authorization: DeepL-Auth-Key [yourAuthKey]' \
+ --header 'Content-Type: application/json' \
+ --data '{
+ "name": "My Glossary",
+ "dictionaries": [
+ {
+ "source_lang": "en",
+ "target_lang": "de",
+ "entries": "Hello\tGuten Tag",
+ "entries_format": "tsv"
+ },
+ {
+ "source_lang": "de",
+ "target_lang": "en",
+ "entries": "Guten Tag\tHello",
+ "entries_format": "tsv"
+ }
+ ]
+ }'
+ ```
+
+ ```json Example response
+ {
+ "glossary_id": "def3a26b-3e84-45b3-84ae-0c0aaf3525f7",
+ "ready": true,
+ "name": "My Glossary",
+ "dictionaries": [
+ {
+ "source_lang": "en",
+ "target_lang": "de",
+ "entry_count": 1
+ },
+ {
+ "source_lang": "de",
+ "target_lang": "en",
+ "entry_count": 1
+ }
+ ],
+ "creation_time": "2025-08-03T14:16:18.329Z"
+ }
+ ```
+
+
+ The example below uses our API Pro endpoint `https://api.deepl.com`. If you're an API Free user, remember to update your requests to use `https://api-free.deepl.com` instead.
+
+ ```http Example request: create a glossary
+ POST /v3/glossaries HTTP/2
+ Host: api.deepl.com
+ Authorization: DeepL-Auth-Key [yourAuthKey]
+ User-Agent: YourApp/1.2.3
+ Content-Length: 1234
+ Content-Type: application/json
+
+ {
+ "name": "My Glossary",
+ "dictionaries": [
+ {
+ "source_lang": "en",
+ "target_lang": "de",
+ "entries": "Hello\tGuten Tag",
+ "entries_format": "tsv"
+ },
+ {
+ "source_lang": "de",
+ "target_lang": "en",
+ "entries": "Guten Tag\tHello",
+ "entries_format": "tsv"
+ }
+ ]
+ }
+ ```
+
+
+
+## Using a glossary
+
+`POST /v2/translate`
+
+To use a glossary in a translation request, include its `glossary_id` . You must also specify _both_ the source and target languages, like this:
+
+
+
+ The example below uses our API Pro endpoint `https://api.deepl.com`. If you're an API Free user, remember to update your requests to use `https://api-free.deepl.com` instead.
+
+ ```sh Example request: translate including glossary
+ curl -X POST 'https://api.deepl.com/v2/translate' \
+ --header 'Authorization: DeepL-Auth-Key [yourAuthKey] \
+ --header 'Content-Type: application/json' \
+ --data '{
+ "text": [
+ "Hello"
+ ],
+ "source_lang": "EN",
+ "target_lang": "DE",
+ "glossary_id": [yourGlossaryID]
+ }'
+ ```
+
+ ```json Example response
+ {
+ "translations": [
+ {
+ "detected_source_language": "EN",
+ "text": "Guten Tag"
+ }
+ ]
+ }
+ ```
+
+
+ The example below uses our API Pro endpoint `https://api.deepl.com`. If you're an API Free user, remember to update your requests to use `https://api-free.deepl.com` instead.
+
+ ```http Example request: translate including glossary
+ POST /v2/translate HTTP/2
+ Host: api.deepl.com
+ Authorization: DeepL-Auth-Key [yourAuthKey]
+ User-Agent: YourApp/1.2.3
+ Content-Length: 111
+ Content-Type: application/json
+
+ {
+ "text": [
+ "Hello there"
+ ],
+ "source_lang": "EN",
+ "target_lang": "DE",
+ "glossary_id": [yourGlossaryID]
+ }
+ ```
+
+ ```json Example response
+ {
+ "translations": [
+ {
+ "detected_source_language": "EN",
+ "text": "Guten Tag"
+ }
+ ]
+ }
+ ```
+
+
+
+
+ Currently the `v3` endpoints only handle glossary methods. Use `v2` for all other functionality, including translation.
+
+
+## Retrieving glossaries
+
+### List all glossaries
+
+`GET /v3/glossaries`
+
+Use this endpoint to list all your glossaries, basic information about each glossary's dictionaries, and each glossary's name and creation time. The response will not include any dictionary entries.
+
+
+
+ The example below uses our API Pro endpoint `https://api.deepl.com`. If you're an API Free user, remember to update your requests to use `https://api-free.deepl.com` instead.
+
+ ```sh Example request: list glossaries
+ curl -X GET 'https://api.deepl.com/v3/glossaries' \
+ --header 'Authorization: DeepL-Auth-Key [yourAuthKey]'
+ ```
+
+ ```json Example response
+ {
+ "glossaries": [
+ {
+ "glossary_id": "def3a26b-3e84-45b3-84ae-0c0aaf3525f7",
+ "name": "My Glossary",
+ "dictionaries": [{
+ "source_lang": "en",
+ "target_lang": "de",
+ "entry_count": 1,
+ },
+ {
+ "source_lang": "de",
+ "target_lang": "en",
+ "entry_count": 3,
+ }],
+ "creation_time": "2021-08-03T14:16:18.329Z"
+ }
+ ]
+ }
+ ```
+
+
+ The example below uses our API Pro endpoint `https://api.deepl.com`. If you're an API Free user, remember to update your requests to use `https://api-free.deepl.com` instead.
+
+ ```http Example request: list all glossaries
+ GET /v3/glossaries HTTP/2
+ Host: api.deepl.com
+ Authorization: DeepL-Auth-Key [yourAuthKey]
+ User-Agent: YourApp/1.2.3
+ ```
+
+ ```json Example response
+ {
+ "glossaries": [
+ {
+ "glossary_id": "def3a26b-3e84-45b3-84ae-0c0aaf3525f7",
+ "name": "My Glossary",
+ "dictionaries": [{
+ "source_lang": "en",
+ "target_lang": "de",
+ "entry_count": 1,
+ },
+ {
+ "source_lang": "de",
+ "target_lang": "en",
+ "entry_count": 3,
+ }],
+ "creation_time": "2025-08-03T14:16:18.329Z"
+ }
+ ]
+ }
+ ```
+
+
+
+### Get glossary metadata
+
+`GET /v3/glossaries/{glossary_id}`
+
+Use this endpoint to retrieve basic information about a given glossary's dictionaries, plus the glossary's name and creation time.
+
+
+
+ The example below uses our API Pro endpoint `https://api.deepl.com`. If you're an API Free user, remember to update your requests to use `https://api-free.deepl.com` instead.
+
+ ```sh Example request: retrieve glossary details
+ curl -X GET 'https://api.deepl.com/v3/glossaries/{glossaryId}' \
+ --header 'Authorization: DeepL-Auth-Key [yourAuthKey]'
+ ```
+
+ ```json Example response
+ {
+ "glossary_id": "def3a26b-3e84-45b3-84ae-0c0aaf3525f7",
+ "name": "My Glossary",
+ "dictionaries": [
+ {
+ "source_lang": "en",
+ "target_lang": "de",
+ "entry_count": 1
+ },
+ {
+ "source_lang": "de",
+ "target_lang": "en",
+ "entry_count": 1
+ }
+ ],
+ "creation_time": "2025-08-03T14:16:18.329Z"
+ }
+ ```
+
+
+ The example below uses our API Pro endpoint `https://api.deepl.com`. If you're an API Free user, remember to update your requests to use `https://api-free.deepl.com` instead.
+
+ ```http Example request: retrieve glossary details
+ GET /v3/glossaries/{glossary_id} HTTP/2
+ Host: api.deepl.com
+ Authorization: DeepL-Auth-Key [yourAuthKey]
+ User-Agent: YourApp/1.2.3
+ ```
+
+ ```json Example response
+ {
+ "glossary_id": "def3a26b-3e84-45b3-84ae-0c0aaf3525f7",
+ "name": "My Glossary",
+ "dictionaries": [
+ {
+ "source_lang": "en",
+ "target_lang": "de",
+ "entry_count": 1
+ },
+ {
+ "source_lang": "de",
+ "target_lang": "en",
+ "entry_count": 1
+ }
+ ],
+ "creation_time": "2025-08-03T14:16:18.329Z"
+ }
+ ```
+
+
+
+### Get glossary entries
+
+`GET /v3/glossaries/{glossaryId}/entries?source_lang={language}&target_lang={language}`
+
+Use this endpoint to retrieve the contents of a single glossary dictionary by specifying the dictionary's language pair.
+
+Currently you can only retrieve glossary contents in TSV format.
+
+
+
+ The example below uses our API Pro endpoint `https://api.deepl.com`. If you're an API Free user, remember to update your requests to use `https://api-free.deepl.com` instead.
+
+ ```sh Example request: get glossary entries
+ curl -X GET 'https://api.deepl.com/v3/glossaries/{glossaryId}/entries?source_lang=en&target_lang=de' \
+ --header 'Authorization: DeepL-Auth-Key [yourAuthKey]' \
+ --header 'Content-Type: application/json'
+ ```
+
+ ```json Example response
+ {
+ "dictionaries": [{
+ "source_lang": "en",
+ "target_lang": "de",
+ "entries": "Hello\tGuten Tag",
+ "entries_format": "tsv",
+ }]
+ }
+ ```
+
+
+ The example below uses our API Pro endpoint `https://api.deepl.com`. If you're an API Free user, remember to update your requests to use `https://api-free.deepl.com` instead.
+
+ ```http Example request: get glossary entries
+ GET /v3/glossaries/{glossary_id}/entries HTTP/2
+ Host: api.deepl.com
+ Authorization: DeepL-Auth-Key [yourAuthKey]
+ User-Agent: YourApp/1.2.3
+ ```
+
+ ```json Example response
+ {
+ "dictionaries": [{
+ "source_lang": "en",
+ "target_lang": "de",
+ "entries": "Hello\tGuten Tag",
+ "entries_format": "tsv",
+ }]
+ }
+ ```
+
+
+
+
+ To retrieve the contents of an entire glossary, iterate through each of dictionaries, retrieving the content of each. While we work to provide the ability to retrieve a whole glossary in a single call, [your feedback here](/docs/resources/deepl-developer-community) is valuable as we strive to improve our API.
+
+
+## Editing a glossary
+
+### Add a new dictionary, or replace an existing one
+
+`PUT /v3/glossaries/{glossaryId}/dictionaries`
+
+The `PUT` method acts on a single dictionary of a glossary. It creates a new dictionary in that glossary, or replaces an existing one, without regard to whether that dictionary already exists. If the glossary has no dictionary for a given language pair, add the dictionary to the glossary with the entries provided. If the dictionary already exists, replace it.
+
+Use this method to add a new dictionary to a glossary or replace an existing one. To instead merge a set of entries with an existing dictionary, use [`the PATCH method`](/api-reference/multilingual-glossaries#add-new-entries-to-a-dictionary%2C-or-replace-existing-entries).
+
+
+
+ The example below uses our API Pro endpoint `https://api.deepl.com`. If you're an API Free user, remember to update your requests to use `https://api-free.deepl.com` instead.
+
+ ```sh Example request: replace a dictionary
+ curl -X PUT 'https://api.deepl.com/v3/glossaries/{glossaryId}/dictionaries' \
+ --header 'Authorization: DeepL-Auth-Key [yourAuthKey]' \
+ --header 'Content-Type: application/json' \
+ --data '{
+ "source_lang": "en",
+ "target_lang": "de",
+ "entries": "Hello\tGuten Tag",
+ "entries_format": "tsv"
+ }'
+ ```
+
+ ```json Example response
+ {
+ "source_lang": "en",
+ "target_lang": "de",
+ "entry_count": 1
+ }
+ ```
+
+
+ The example below uses our API Pro endpoint `https://api.deepl.com`. If you're an API Free user, remember to update your requests to use `https://api-free.deepl.com` instead.
+
+ ```http Example request: replace a dictionary
+ PUT /v3/glossaries/{glossaryId}/dictionaries HTTP/2
+ Host: api.deepl.com
+ Authorization: DeepL-Auth-Key [yourAuthKey]
+ User-Agent: YourApp/1.2.3
+ Content-Length: 210
+ Content-Type: application/json
+
+ {"source_lang": "en","target_lang": "de","entries": "Hello\tGuten Tag", "entries_format": "tsv"}
+ ```
+
+ ```json Example response
+ {
+ "source_lang": "en",
+ "target_lang": "de",
+ "entry_count": 1
+ }
+ ```
+
+
+
+### Add new entries to a dictionary, or replace existing entries
+
+`PATCH /v3/glossaries/{glossaryId}`
+
+While the `PUT` method operates on a single dictionary, `PATCH` affects an element of an entire glossary. This element could be a piece of metadata - like the glossary's name - or a dictionary for a particular language pair.
+
+This method returns the glossary's name and metadata on each of its dictionaries.
+
+For example, this `PATCH` changes a glossary's name.
+
+
+
+ The example below uses our API Pro endpoint `https://api.deepl.com`. If you're an API Free user, remember to update your requests to use `https://api-free.deepl.com` instead.
+
+ ```sh Example request: update glossary entries
+ curl -X PATCH 'https://api.deepl.com/v3/glossaries/{glossaryId}' \
+ --header 'Authorization: DeepL-Auth-Key [yourAuthKey]' \
+ --header 'Content-Type: application/json' \
+ --data '{
+ "name": "Gus the glossary"
+ }'
+ ```
+
+ ```json Example response
+ {
+ "glossary_id": "def3a26b-3e84-45b3-84ae-0c0aaf3525f7",
+ "name": "Gus the glossary",
+ "dictionaries": [
+ {
+ "source_lang": "en",
+ "target_lang": "de",
+ "entry_count": 1
+ }
+ ],
+ "creation_time": "2025-08-03T14:16:18.329Z"
+ }
+ ```
+
+
+ The example below uses our API Pro endpoint `https://api.deepl.com`. If you're an API Free user, remember to update your requests to use `https://api-free.deepl.com` instead.
+
+ ```http Example request: update glossary entries
+ PATCH /v3/glossaries/{glossaryId} HTTP/2
+ Host: api.deepl.com
+ Authorization: DeepL-Auth-Key [yourAuthKey]
+ User-Agent: YourApp/1.2.3
+ Content-Length: 147
+ Content-Type: application/json
+
+ {"name": "My updated glossary", "dictionaries": [{"source_lang": "en","target_lang": "de","entries": "Hello\tGuten Tag", "entries_format": "tsv"}]}
+ ```
+
+ ```json Example response
+ {
+ "glossary_id": "def3a26b-3e84-45b3-84ae-0c0aaf3525f7",
+ "name": "My updated glossary",
+ "dictionaries": [
+ {
+ "source_lang": "en",
+ "target_lang": "de",
+ "entry_count": 1
+ }
+ ],
+ "creation_time": "2025-08-03T14:16:18.329Z"
+ }
+ ```
+
+
+
+You can also use `PATCH` to change the contents of a glossary's dictionary for a language pair while taking any existing dictionary for that language pair into account. If the glossary already has a dictionary for the specified language pair, the entries passed here will be merged with the existing dictionary.
+
+Use this method to make changes to an existing dictionary. To replace a dictionary outright, use [the PUT method](./#add-a-new-dictionary-or-replace-an-existing-one).
+
+This example makes two changes. It changes the glossary's name, and it adds a new entry to its German → English dictionary.
+
+
+
+ The example below uses our API Pro endpoint `https://api.deepl.com`. If you're an API Free user, remember to update your requests to use `https://api-free.deepl.com` instead.
+
+ ```sh Example request: update glossary entries
+ curl -X PATCH 'https://api.deepl.com/v3/glossaries/{glossaryId}' \
+ --header 'Authorization: DeepL-Auth-Key [yourAuthKey]' \
+ --header 'Content-Type: application/json' \
+ --data '{
+ "name": "Gertrude the glossary",
+ "dictionaries": [{
+ "source_lang": "en",
+ "target_lang": "de",
+ "entries": "Goodbye\tTschüß",
+ "entries_format": "tsv"
+ }]
+ }'
+ ```
+
+ ```json Example response
+ {
+ "glossary_id": "def3a26b-3e84-45b3-84ae-0c0aaf3525f7",
+ "name": "Gertrude the glossary",
+ "dictionaries": [
+ {
+ "source_lang": "en",
+ "target_lang": "de",
+ "entry_count": 2
+ }
+ ],
+ "creation_time": "2025-08-03T14:16:18.329Z"
+ }
+ ```
+
+
+ The example below uses our API Pro endpoint `https://api.deepl.com`. If you're an API Free user, remember to update your requests to use `https://api-free.deepl.com` instead.
+
+ ```http Example request: update glossary entries
+ PATCH /v3/glossaries/{glossaryId} HTTP/2
+ Host: api.deepl.com
+ Authorization: DeepL-Auth-Key [yourAuthKey]
+ User-Agent: YourApp/1.2.3
+ Content-Length: 147
+ Content-Type: application/json
+
+ {"name": "My updated glossary", "dictionaries": [{"source_lang": "en","target_lang": "de","entries": "Hello\tGuten Tag", "entries_format": "tsv"}]}
+ ```
+
+ ```json Example response
+ {
+ "glossary_id": "def3a26b-3e84-45b3-84ae-0c0aaf3525f7",
+ "name": "My updated glossary",
+ "dictionaries": [
+ {
+ "source_lang": "en",
+ "target_lang": "de",
+ "entry_count": 1
+ }
+ ],
+ "creation_time": "2025-08-03T14:16:18.329Z"
+ }
+ ```
+
+
+
+
+ Currently, a given `PUT` and `PATCH` can make changes to a single dictionary. To change the target phrase for a given source phrase for multiple languages, you need to make multiple API calls. While we work to support multiple dictionaries in future updates, [your feedback here](/docs/resources/deepl-developer-community) is valuable as we work to improve our API.
+
+
+## Deleting glossaries
+
+### Delete a glossary
+
+`DELETE /v3/glossaries/{glossary_id}`
+
+This method deletes the specified glossary in its entirety.
+
+
+
+ The example below uses our API Pro endpoint `https://api.deepl.com`. If you're an API Free user, remember to update your requests to use `https://api-free.deepl.com` instead.
+
+ ```sh Example request: delete a glossary
+ curl -X DELETE 'https://api.deepl.com/v3/glossaries/{glossary_id}' \
+ --header 'Authorization: DeepL-Auth-Key [yourAuthKey]'
+ ```
+
+
+ The example below uses our API Pro endpoint `https://api.deepl.com`. If you're an API Free user, remember to update your requests to use `https://api-free.deepl.com` instead.
+
+ ```http Example request: delete a glossary
+ DELETE /v3/glossaries/{glossary_id} HTTP/2
+ Host: api.deepl.com
+ Authorization: DeepL-Auth-Key [yourAuthKey]
+ User-Agent: YourApp/1.2.3
+ ```
+
+
+
+### Delete a glossary's dictionary
+
+`DELETE /v3/glossaries/{glossary_id}/dictionaries?source_lang={source_lang}&target_lang={target_lang}`
+
+Use this method to delete a dictionary for a specific language pair.
+
+
+
+ The example below uses our API Pro endpoint `https://api.deepl.com`. If you're an API Free user, remember to update your requests to use `https://api-free.deepl.com` instead.
+
+ ```sh Example request: delete a dictionary
+ curl -X DELETE 'https://api.deepl.com/v3/glossaries/{glossary_id}/dictionaries?source_lang={source_lang}&target_lang={target_lang}' \
+ --header 'Authorization: DeepL-Auth-Key [yourAuthKey]'
+ ```
+
+
+ The example below uses our API Pro endpoint `https://api.deepl.com`. If you're an API Free user, remember to update your requests to use `https://api-free.deepl.com` instead.
+
+ ```http Example request: delete a dictionary
+ DELETE /v3/glossaries/{glossary_id}/dictionaries?source_lang={source_lang}&target_lang={target_lang} HTTP/2
+ Host: api.deepl.com
+ Authorization: DeepL-Auth-Key [yourAuthKey]
+ User-Agent: YourApp/1.2.3
+ ```
+
+
+
+## Notes on usage
+
+### Languages supported
+
+The DeepL API supports [these languages for glossaries](/docs/getting-started/supported-languages).
+
+To retrieve supported glossary languages programmatically, call [`GET /v3/languages?resource=glossary`](/api-reference/languages/retrieve-supported-languages-by-resource).
+
+### Language variants
+
+Glossaries apply to languages, not specific language variants. A glossary for a language applies to any variant of that language.
+
+For example, if you create a glossary with target language `EN` , that glossary will apply to `EN-US` and `EN-GB`. A glossary with target language `PT` will apply to `PT-PT` and `PT-BR`.
+
+### Source language detection
+
+Glossaries can not (yet) be used in translation requests that do not set a specific source language. [Your feedback here](/docs/resources/deepl-developer-community) is valuable as we strive to improve our API.
+
+## Restrictions
+
+### Size
+
+A dictionary can contain a maximum of 10 MB. This is true for each dictionary in a glossary. So, if a glossary contains five dictionaries, each if its dictionaries could contain up to 10 MB, for a total of 50 MB.
+
+The name of the glossary, each source phrase, and each target phrase, can contain up to 1024 UTF-8 bytes.
+
+The number of glossaries you can make is [limited by your plan](https://www.deepl.com/en/pro-api).
+
+### Content
+
+- Duplicate source entries are not allowed.
+- Neither the source nor the target entry may be empty.
+- The source and target entries must not contain any C0 or C1 control characters (including, e.g., `\t` or `\n`) or any Unicode newline.
+- Source and target entries must not contain any leading or trailing Unicode whitespace characters.
diff --git a/api-reference/multilingual-glossaries/create-a-glossary.mdx b/api-reference/multilingual-glossaries/create-a-glossary.mdx
index c2c2644..cce6694 100644
--- a/api-reference/multilingual-glossaries/create-a-glossary.mdx
+++ b/api-reference/multilingual-glossaries/create-a-glossary.mdx
@@ -1,9 +1,4 @@
---
openapi: post /v3/glossaries
title: "Create a glossary"
-description: "Create a multilingual glossary containing one or more language-pair dictionaries using the v3 endpoint."
----
-
-Creates a glossary containing one or more dictionaries. Each dictionary maps source phrases to target phrases for a single language pair. A single glossary can contain dictionaries for multiple language pairs.
-
-See the [Glossaries overview](/api-reference/multilingual-glossaries) for entry formats, how to use a glossary in a translation request, and details on editing, deleting, and language support.
\ No newline at end of file
+---
\ No newline at end of file
diff --git a/api-reference/quality-evaluation.mdx b/api-reference/quality-evaluation.mdx
new file mode 100644
index 0000000..616be8c
--- /dev/null
+++ b/api-reference/quality-evaluation.mdx
@@ -0,0 +1,35 @@
+---
+title: "Evaluate translation quality"
+description: "API reference for detecting translation quality issues with the DeepL API."
+---
+
+
+ **Closed alpha.** This API may change without notice and is only available to select DeepL customers. See [alpha and beta features](/docs/resources/alpha-and-beta-features) for details. To request access, contact your customer success manager.
+
+
+## Overview
+
+Identify quality issues with your translations through a two-step process:
+
+1. [**Submit an evaluation job**](/api-reference/quality-evaluation/submit)
+2. [**Poll for the result**](/api-reference/quality-evaluation/poll)
+
+## Limits
+
+| **Limit** | **Value** |
+|---|---:|
+| Segments per request | 500 |
+| Characters per segment (`source` or `target`) | 10,000 |
+
+### Rate limits
+
+| **Endpoint** | **Limit** |
+|---|---|
+| `POST /v1/quality-evaluation` | 100 requests per minute per API key |
+| `GET /v1/quality-evaluation/{job_id}` | 1,000 requests per minute per API key |
+
+Exceeding either limit returns `429 Too Many Requests`.
+
+## Job retention
+
+Job results are retained for 24 hours after the job reaches `done` or `error` state. After that, the `GET` endpoint returns `404 Not Found` for that `job_id`.
diff --git a/api-reference/quality-evaluation/submit.mdx b/api-reference/quality-evaluation/submit.mdx
index 294330e..2aa6349 100644
--- a/api-reference/quality-evaluation/submit.mdx
+++ b/api-reference/quality-evaluation/submit.mdx
@@ -1,21 +1,14 @@
---
openapi: post /v1/quality-evaluation
title: "Submit an evaluation job"
-description: "Submit a batch of translation segments for quality evaluation. Returns a job ID for polling results."
---
-
- **Closed alpha.** This API may change without notice and is only available to select DeepL customers. See [alpha and beta features](/docs/resources/alpha-and-beta-features) for details. To request access, contact your customer success manager.
-
+See the [Quality Evaluation overview](/api-reference/quality-evaluation) for severity values, sub-types, span semantics, and limits.
-This endpoint is asynchronous. After submission, poll `GET /v1/quality-evaluation/{job_id}` to retrieve results once processing is complete.
+### Supported language pairs
-See the [Quality Evaluation overview](/api-reference/quality-evaluation) for severity values, sub-types, span semantics, limits, rate limits, and job retention details.
-
-## Supported language pairs
-
-| **Source language** | **Target languages** |
-|:---|:---|
+| **Source Language** | **Target Languages** |
+|---|---|
| German (`de`) | English (`en-gb`, `en-us`) |
| English (`en`) | German (`de`), Spanish (`es`, `es-419`), French (`fr`), Italian (`it`), Japanese (`ja`), Korean (`ko`) |
| Spanish (`es`) | English (`en-gb`, `en-us`) |
@@ -23,4 +16,4 @@ See the [Quality Evaluation overview](/api-reference/quality-evaluation) for sev
| Italian (`it`) | English (`en-gb`, `en-us`) |
| Japanese (`ja`) | English (`en-gb`, `en-us`), Korean (`ko`), Chinese Simplified (`zh-hans`), Chinese Traditional (`zh-hant`) |
| Korean (`ko`) | English (`en-gb`, `en-us`), Japanese (`ja`) |
-| Chinese (`zh`) | Japanese (`ja`) |
\ No newline at end of file
+| Chinese (`zh`) | Japanese (`ja`) |
diff --git a/api-reference/style-rules.mdx b/api-reference/style-rules.mdx
new file mode 100644
index 0000000..f83d9d5
--- /dev/null
+++ b/api-reference/style-rules.mdx
@@ -0,0 +1,940 @@
+---
+title: "Style rules"
+sidebarTitle: "Overview"
+description: "Manage a shared list of rules for style, formatting, and more"
+---
+
+
+ The Style Rules API is currently available only to Pro API subscribers.
+
+
+## Overview
+
+The style rules feature allows you to select a set of rules to apply when translating text. These rules make changes to your text according to the selected formatting and spelling conventions.
+
+You can create style rules in the UI at [https://deepl.com/custom-rules](https://deepl.com/custom-rules).
+
+Both glossaries and style rules are unique to each of DeepL's global data centers and are not shared between them. Clients using the `api-us.deepl.com` endpoint will not be able to access glossaries or style rules created in the UI at this time.
+
+A **style rule list** contains two types of rules:
+- **Configured rules**: Predefined rules for formatting conventions (e.g., time format, number formatting, style and tone)
+- **Custom instructions**: User-defined instructions for specific styling requirements
+
+Both configured rules and custom instructions are applied during translation to ensure your translations match your style requirements. They work together to provide comprehensive style control over your translated content.
+
+### Limits
+
+- There is no limit to how many predefined rules can be selected per style rule list
+- A maximum of 200 custom instructions can be enabled per style rule list (although this may be adjusted based on plan tiers in the future)
+- Each custom instruction is at most 300 characters
+
+If you need more than 200 custom instructions, consider organizing your rules into multiple style rule lists for different use cases or content types.
+
+## Creating style rules
+
+### Create a style rule list
+
+`POST /v3/style_rules`
+
+Create a new style rule list with configured rules and optional custom instructions.
+
+
+
+ The example below uses our API Pro endpoint `https://api.deepl.com`. If you're an API Free user, remember to update your requests to use `https://api-free.deepl.com` instead.
+
+ ```sh Example request: create a style rule list
+ curl -X POST 'https://api.deepl.com/v3/style_rules' \
+ --header 'Authorization: DeepL-Auth-Key [yourAuthKey]' \
+ --header 'Content-Type: application/json' \
+ --data '{
+ "name": "Technical Documentation Rules",
+ "language": "en",
+ "configured_rules": {
+ "dates_and_times": {
+ "calendar_era": "use_bc_and_ad"
+ },
+ "punctuation": {
+ "periods_in_academic_degrees": "do_not_use"
+ }
+ },
+ "custom_instructions": [
+ {
+ "label": "Tone instruction",
+ "prompt": "Use a friendly, diplomatic tone",
+ "source_language": "en"
+ }
+ ]
+ }'
+ ```
+
+ ```json Example response
+ {
+ "style_id": "a74d88fb-ed2a-4943-a664-a4512398b994",
+ "name": "Technical Documentation Rules",
+ "creation_time": "2024-10-01T12:34:56Z",
+ "updated_time": "2024-10-01T12:34:56Z",
+ "language": "en",
+ "version": 1,
+ "configured_rules": {
+ "dates_and_times": {
+ "calendar_era": "use_bc_and_ad"
+ },
+ "punctuation": {
+ "periods_in_academic_degrees": "do_not_use"
+ }
+ },
+ "custom_instructions": [
+ {
+ "id": "68fdb803-c013-4e67-b62e-1aad0ab519cd",
+ "label": "Tone instruction",
+ "prompt": "Use a friendly, diplomatic tone",
+ "source_language": "en"
+ }
+ ]
+ }
+ ```
+
+
+ The example below uses our API Pro endpoint `https://api.deepl.com`. If you're an API Free user, remember to update your requests to use `https://api-free.deepl.com` instead.
+
+ ```http Example request: create a style rule list
+ POST /v3/style_rules HTTP/2
+ Host: api.deepl.com
+ Authorization: DeepL-Auth-Key [yourAuthKey]
+ User-Agent: YourApp/1.2.3
+ Content-Length: 234
+ Content-Type: application/json
+
+ {
+ "name": "Technical Documentation Rules",
+ "language": "en",
+ "configured_rules": {
+ "dates_and_times": {
+ "calendar_era": "use_bc_and_ad"
+ },
+ "punctuation": {
+ "periods_in_academic_degrees": "do_not_use"
+ }
+ },
+ "custom_instructions": [
+ {
+ "label": "Tone instruction",
+ "prompt": "Use a friendly, diplomatic tone",
+ "source_language": "en"
+ }
+ ]
+ }
+ ```
+
+ ```json Example response
+ {
+ "style_id": "a74d88fb-ed2a-4943-a664-a4512398b994",
+ "name": "Technical Documentation Rules",
+ "creation_time": "2024-10-01T12:34:56Z",
+ "updated_time": "2024-10-01T12:34:56Z",
+ "language": "en",
+ "version": 1,
+ "configured_rules": {
+ "dates_and_times": {
+ "calendar_era": "use_bc_and_ad"
+ },
+ "punctuation": {
+ "periods_in_academic_degrees": "do_not_use"
+ }
+ },
+ "custom_instructions": [
+ {
+ "id": "68fdb803-c013-4e67-b62e-1aad0ab519cd",
+ "label": "Tone instruction",
+ "prompt": "Use a friendly, diplomatic tone",
+ "source_language": "en"
+ }
+ ]
+ }
+ ```
+
+
+
+#### Request body parameters
+
+
+ The name of the style rule list. Maximum length: 1024 characters.
+
+
+ The target language for the style rules. Supported values: `de`, `en`, `es`, `fr`, `it`, `ja`, `ko`, `zh`.
+
+
+ An object containing predefined rules to enable for the style rule list. Rules are organized by category (e.g., `dates_and_times`, `punctuation`). Each category can contain multiple rule options.
+
+
+ An array of custom instruction objects. Each custom instruction must include `label`, `prompt`, and optionally `source_language`. Maximum 200 custom instructions per style rule list. Each prompt is limited to 300 characters.
+
+
+
+ The `version` field in the response increments each time the style rule list is modified (e.g., when rules are updated or custom instructions are added/removed). You can use this field to track changes to your style rules.
+
+
+## Retrieving style rules
+
+### List all style rule lists
+
+`GET /v3/style_rules`
+
+Get all style rule lists and their meta-information.
+
+
+
+ The example below uses our API Pro endpoint `https://api.deepl.com`. If you're an API Free user, remember to update your requests to use `https://api-free.deepl.com` instead.
+
+ ```sh Example request: get all style rule lists
+ curl -X GET 'https://api.deepl.com/v3/style_rules' \
+ --header 'Authorization: DeepL-Auth-Key [yourAuthKey]'
+ ```
+
+ ```json Example response
+ {
+ "style_rules": [
+ {
+ "style_id": "a74d88fb-ed2a-4943-a664-a4512398b994",
+ "name": "Technical Documentation Rules",
+ "creation_time": "2024-10-01T12:34:56Z",
+ "updated_time": "2024-10-03T12:34:56Z",
+ "language": "en",
+ "version": 8
+ }
+ ]
+ }
+ ```
+
+ You can also optionally pass in a `detailed` query parameter to retrieve all configured rules and custom instructions per rule list.
+
+ ```sh Example request: get all style rule lists with details
+ curl -X GET 'https://api.deepl.com/v3/style_rules?detailed=true' \
+ --header 'Authorization: DeepL-Auth-Key [yourAuthKey]'
+ ```
+
+ ```json Example response
+ {
+ "style_rules": [
+ {
+ "style_id": "a74d88fb-ed2a-4943-a664-a4512398b994",
+ "name": "Technical Documentation Rules",
+ "creation_time": "2024-10-01T12:34:56Z",
+ "updated_time": "2024-10-03T12:34:56Z",
+ "language": "en",
+ "version": 8,
+ "configured_rules": {
+ "dates_and_times": {
+ "calendar_era": "use_bc_and_ad"
+ },
+ "punctuation": {
+ "periods_in_academic_degrees": "do_not_use"
+ }
+ },
+ "custom_instructions": [
+ {
+ "id": "68fdb803-c013-4e67-b62e-1aad0ab519cd",
+ "label": "Tone instruction",
+ "prompt": "Use a friendly, diplomatic tone",
+ "source_language": "de"
+ }
+ ]
+ }
+ ]
+ }
+ ```
+
+
+ The example below uses our API Pro endpoint `https://api.deepl.com`. If you're an API Free user, remember to update your requests to use `https://api-free.deepl.com` instead.
+
+ ```http Example request: get all style rule lists
+ GET /v3/style_rules HTTP/2
+ Host: api.deepl.com
+ Authorization: DeepL-Auth-Key [yourAuthKey]
+ User-Agent: YourApp/1.2.3
+ ```
+
+ ```json Example response
+ {
+ "style_rules": [
+ {
+ "style_id": "a74d88fb-ed2a-4943-a664-a4512398b994",
+ "name": "Technical Documentation Rules",
+ "creation_time": "2024-10-01T12:34:56Z",
+ "updated_time": "2024-10-03T12:34:56Z",
+ "language": "en",
+ "version": 8
+ }
+ ]
+ }
+ ```
+
+ You can also optionally pass in a `detailed` query parameter to retrieve all configured rules and custom instructions per rule list.
+
+ ```http Example request: get all style rule lists with details
+ GET /v3/style_rules?detailed=true HTTP/2
+ Host: api.deepl.com
+ Authorization: DeepL-Auth-Key [yourAuthKey]
+ User-Agent: YourApp/1.2.3
+ ```
+
+ ```json Example response
+ {
+ "style_rules": [
+ {
+ "style_id": "a74d88fb-ed2a-4943-a664-a4512398b994",
+ "name": "Technical Documentation Rules",
+ "creation_time": "2024-10-01T12:34:56Z",
+ "updated_time": "2024-10-03T12:34:56Z",
+ "language": "en",
+ "version": 8,
+ "configured_rules": {
+ "dates_and_times": {
+ "calendar_era": "use_bc_and_ad"
+ },
+ "punctuation": {
+ "periods_in_academic_degrees": "do_not_use"
+ }
+ },
+ "custom_instructions": [
+ {
+ "id": "68fdb803-c013-4e67-b62e-1aad0ab519cd",
+ "label": "Tone instruction",
+ "prompt": "Use a friendly, diplomatic tone",
+ "source_language": "de"
+ }
+ ]
+ }
+ ]
+ }
+ ```
+
+
+
+#### Query parameters
+
+
+ Determines if the rule list's `configured_rules` and `custom_instructions` should be included in the response body. If `detailed` parameter is not included, defaults to `false`.
+
+
+ The index of the first page to return. Default: 0 (the first page). Use with `page_size` to get the next page of rule lists.
+
+
+ The maximum number of style rule lists to return. Default: 10. Minimum: 1. Maximum: 25.
+
+
+### Get a style rule list
+
+`GET /v3/style_rules/{style_id}`
+
+Get detailed information for a single style rule list, including all configured rules and custom instructions.
+
+
+
+ The example below uses our API Pro endpoint `https://api.deepl.com`. If you're an API Free user, remember to update your requests to use `https://api-free.deepl.com` instead.
+
+ ```sh Example request: retrieve style rule list
+ curl -X GET 'https://api.deepl.com/v3/style_rules/{style_id}' \
+ --header 'Authorization: DeepL-Auth-Key [yourAuthKey]'
+ ```
+
+ ```json Example response
+ {
+ "style_id": "a74d88fb-ed2a-4943-a664-a4512398b994",
+ "name": "Technical Documentation Rules",
+ "creation_time": "2024-10-01T12:34:56Z",
+ "updated_time": "2024-10-03T12:34:56Z",
+ "language": "en",
+ "version": 8,
+ "configured_rules": {
+ "dates_and_times": {
+ "calendar_era": "use_bc_and_ad"
+ },
+ "punctuation": {
+ "periods_in_academic_degrees": "do_not_use"
+ }
+ },
+ "custom_instructions": [
+ {
+ "id": "68fdb803-c013-4e67-b62e-1aad0ab519cd",
+ "label": "Tone instruction",
+ "prompt": "Use a friendly, diplomatic tone",
+ "source_language": "de"
+ }
+ ]
+ }
+ ```
+
+
+ The example below uses our API Pro endpoint `https://api.deepl.com`. If you're an API Free user, remember to update your requests to use `https://api-free.deepl.com` instead.
+
+ ```http Example request: retrieve style rule list
+ GET /v3/style_rules/{style_id} HTTP/2
+ Host: api.deepl.com
+ Authorization: DeepL-Auth-Key [yourAuthKey]
+ User-Agent: YourApp/1.2.3
+ ```
+
+ ```json Example response
+ {
+ "style_id": "a74d88fb-ed2a-4943-a664-a4512398b994",
+ "name": "Technical Documentation Rules",
+ "creation_time": "2024-10-01T12:34:56Z",
+ "updated_time": "2024-10-03T12:34:56Z",
+ "language": "en",
+ "version": 8,
+ "configured_rules": {
+ "dates_and_times": {
+ "calendar_era": "use_bc_and_ad"
+ },
+ "punctuation": {
+ "periods_in_academic_degrees": "do_not_use"
+ }
+ },
+ "custom_instructions": [
+ {
+ "id": "68fdb803-c013-4e67-b62e-1aad0ab519cd",
+ "label": "Tone instruction",
+ "prompt": "Use a friendly, diplomatic tone",
+ "source_language": "de"
+ }
+ ]
+ }
+ ```
+
+
+
+## Updating style rules
+
+Use `PATCH /v3/style_rules/{style_id}` to update the name of a style rule list, or use `PUT /v3/style_rules/{style_id}/configured_rules` to replace all configured rules.
+
+### Update a style rule list's name
+
+`PATCH /v3/style_rules/{style_id}`
+
+Update the name of a style rule list.
+
+
+
+ The example below uses our API Pro endpoint `https://api.deepl.com`. If you're an API Free user, remember to update your requests to use `https://api-free.deepl.com` instead.
+
+ ```sh Example request: update a style rule list's name
+ curl -X PATCH 'https://api.deepl.com/v3/style_rules/{style_id}' \
+ --header 'Authorization: DeepL-Auth-Key [yourAuthKey]' \
+ --header 'Content-Type: application/json' \
+ --data '{
+ "name": "New Technical Documentation Rules"
+ }'
+ ```
+
+ ```json Example response
+ {
+ "style_id": "a74d88fb-ed2a-4943-a664-a4512398b994",
+ "name": "New Technical Documentation Rules",
+ "creation_time": "2024-10-01T12:34:56Z",
+ "updated_time": "2024-10-01T12:34:56Z",
+ "language": "en",
+ "version": 2,
+ "configured_rules": {
+ "dates_and_times": {
+ "calendar_era": "use_bc_and_ad"
+ },
+ "punctuation": {
+ "periods_in_academic_degrees": "do_not_use"
+ }
+ },
+ "custom_instructions": [
+ {
+ "id": "68fdb803-c013-4e67-b62e-1aad0ab519cd",
+ "label": "Tone instruction",
+ "prompt": "Use a friendly, diplomatic tone",
+ "source_language": "en"
+ }
+ ]
+ }
+ ```
+
+
+ The example below uses our API Pro endpoint `https://api.deepl.com`. If you're an API Free user, remember to update your requests to use `https://api-free.deepl.com` instead.
+
+ ```http Example request: update a style rule list's name
+ PATCH /v3/style_rules/{style_id} HTTP/2
+ Host: api.deepl.com
+ Authorization: DeepL-Auth-Key [yourAuthKey]
+ User-Agent: YourApp/1.2.3
+ Content-Length: 52
+ Content-Type: application/json
+
+ {
+ "name": "New Technical Documentation Rules"
+ }
+ ```
+
+ ```json Example response
+ {
+ "style_id": "a74d88fb-ed2a-4943-a664-a4512398b994",
+ "name": "New Technical Documentation Rules",
+ "creation_time": "2024-10-01T12:34:56Z",
+ "updated_time": "2024-10-01T12:34:56Z",
+ "language": "en",
+ "version": 2,
+ "configured_rules": {
+ "dates_and_times": {
+ "calendar_era": "use_bc_and_ad"
+ },
+ "punctuation": {
+ "periods_in_academic_degrees": "do_not_use"
+ }
+ },
+ "custom_instructions": [
+ {
+ "id": "68fdb803-c013-4e67-b62e-1aad0ab519cd",
+ "label": "Tone instruction",
+ "prompt": "Use a friendly, diplomatic tone",
+ "source_language": "en"
+ }
+ ]
+ }
+ ```
+
+
+
+#### Request body parameters
+
+
+ The new name for the style rule list. Maximum length: 1024 characters.
+
+
+### Replace configured rules
+
+`PUT /v3/style_rules/{style_id}/configured_rules`
+
+Replace all configured rules for a style rule list. Custom instructions are not affected.
+
+
+
+ The example below uses our API Pro endpoint `https://api.deepl.com`. If you're an API Free user, remember to update your requests to use `https://api-free.deepl.com` instead.
+
+ ```sh Example request: replace configured rules
+ curl -X PUT 'https://api.deepl.com/v3/style_rules/{style_id}/configured_rules' \
+ --header 'Authorization: DeepL-Auth-Key [yourAuthKey]' \
+ --header 'Content-Type: application/json' \
+ --data '{
+ "dates_and_times": {
+ "calendar_era": "use_bc_and_ad"
+ },
+ "punctuation": {
+ "periods_in_academic_degrees": "do_not_use"
+ }
+ }'
+ ```
+
+ ```json Example response
+ {
+ "style_id": "a74d88fb-ed2a-4943-a664-a4512398b994",
+ "name": "Technical Documentation Rules",
+ "creation_time": "2024-10-01T12:34:56Z",
+ "updated_time": "2024-10-04T12:34:56Z",
+ "language": "en",
+ "version": 3,
+ "configured_rules": {
+ "dates_and_times": {
+ "calendar_era": "use_bc_and_ad"
+ },
+ "punctuation": {
+ "periods_in_academic_degrees": "do_not_use"
+ }
+ },
+ "custom_instructions": [
+ {
+ "id": "68fdb803-c013-4e67-b62e-1aad0ab519cd",
+ "label": "Tone instruction",
+ "prompt": "Use a friendly, diplomatic tone",
+ "source_language": "en"
+ }
+ ]
+ }
+ ```
+
+
+ The example below uses our API Pro endpoint `https://api.deepl.com`. If you're an API Free user, remember to update your requests to use `https://api-free.deepl.com` instead.
+
+ ```http Example request: replace configured rules
+ PUT /v3/style_rules/{style_id}/configured_rules HTTP/2
+ Host: api.deepl.com
+ Authorization: DeepL-Auth-Key [yourAuthKey]
+ User-Agent: YourApp/1.2.3
+ Content-Length: 145
+ Content-Type: application/json
+
+ {
+ "dates_and_times": {
+ "calendar_era": "use_bc_and_ad"
+ },
+ "punctuation": {
+ "periods_in_academic_degrees": "do_not_use"
+ }
+ }
+ ```
+
+ ```json Example response
+ {
+ "style_id": "a74d88fb-ed2a-4943-a664-a4512398b994",
+ "name": "Technical Documentation Rules",
+ "creation_time": "2024-10-01T12:34:56Z",
+ "updated_time": "2024-10-04T12:34:56Z",
+ "language": "en",
+ "version": 3,
+ "configured_rules": {
+ "dates_and_times": {
+ "calendar_era": "use_bc_and_ad"
+ },
+ "punctuation": {
+ "periods_in_academic_degrees": "do_not_use"
+ }
+ },
+ "custom_instructions": [
+ {
+ "id": "68fdb803-c013-4e67-b62e-1aad0ab519cd",
+ "label": "Tone instruction",
+ "prompt": "Use a friendly, diplomatic tone",
+ "source_language": "en"
+ }
+ ]
+ }
+ ```
+
+
+
+#### Request body parameters
+
+
+ A `ConfiguredRules` object containing the complete set of predefined rules. This replaces all existing configured rules for the style rule list. Rules are organized by category (e.g., `dates_and_times`, `punctuation`).
+
+
+
+ This endpoint replaces the entire configured rules object. Use `PATCH /v3/style_rules/{style_id}` instead if you only want to update the style rule list name.
+
+
+## Deleting style rules
+
+### Delete a style rule list
+
+`DELETE /v3/style_rules/{style_id}`
+
+Delete a style rule list. This operation cannot be undone.
+
+
+
+ The example below uses our API Pro endpoint `https://api.deepl.com`. If you're an API Free user, remember to update your requests to use `https://api-free.deepl.com` instead.
+
+ ```sh Example request: delete style rule list
+ curl -X DELETE 'https://api.deepl.com/v3/style_rules/{style_id}' \
+ --header 'Authorization: DeepL-Auth-Key [yourAuthKey]'
+ ```
+
+ Returns a `204 No Content` status code on successful deletion. The response body will be empty. If the style rule list is not found, a `404` error will be returned.
+
+
+ The example below uses our API Pro endpoint `https://api.deepl.com`. If you're an API Free user, remember to update your requests to use `https://api-free.deepl.com` instead.
+
+ ```http Example request: delete style rule list
+ DELETE /v3/style_rules/{style_id} HTTP/2
+ Host: api.deepl.com
+ Authorization: DeepL-Auth-Key [yourAuthKey]
+ User-Agent: YourApp/1.2.3
+ ```
+
+ Returns a `204 No Content` status code on successful deletion. The response body will be empty. If the style rule list is not found, a `404` error will be returned.
+
+
+
+## Managing custom instructions
+
+### Create a custom instruction
+
+`POST /v3/style_rules/{style_id}/custom_instructions`
+
+Add a new custom instruction to an existing style rule list. The response returns the complete updated style rule list, including the new custom instruction with its generated ID.
+
+
+
+ The example below uses our API Pro endpoint `https://api.deepl.com`. If you're an API Free user, remember to update your requests to use `https://api-free.deepl.com` instead.
+
+ ```sh Example request: create custom instruction
+ curl -X POST 'https://api.deepl.com/v3/style_rules/{style_id}/custom_instructions' \
+ --header 'Authorization: DeepL-Auth-Key [yourAuthKey]' \
+ --header 'Content-Type: application/json' \
+ --data '{
+ "label": "Currency format instruction",
+ "prompt": "Put currency symbols after the numeric amount",
+ "source_language": "en"
+ }'
+ ```
+
+ ```json Example response
+ {
+ "style_id": "a74d88fb-ed2a-4943-a664-a4512398b994",
+ "name": "Technical Documentation Rules",
+ "creation_time": "2024-10-01T12:34:56Z",
+ "updated_time": "2024-10-01T12:34:56Z",
+ "language": "en",
+ "version": 2,
+ "configured_rules": {
+ "dates_and_times": {
+ "calendar_era": "use_bc_and_ad"
+ },
+ "punctuation": {
+ "periods_in_academic_degrees": "do_not_use"
+ }
+ },
+ "custom_instructions": [
+ {
+ "id": "68fdb803-c013-4e67-b62e-1aad0ab519cd",
+ "label": "Tone instruction",
+ "prompt": "Use a friendly, diplomatic tone",
+ "source_language": "en"
+ },
+ {
+ "id": "f4515921-8fdf-4e3a-a981-ad7a6717a8aa",
+ "label": "Currency format instruction",
+ "prompt": "Put currency symbols after the numeric amount",
+ "source_language": "en"
+ }
+ ]
+ }
+ ```
+
+
+ The example below uses our API Pro endpoint `https://api.deepl.com`. If you're an API Free user, remember to update your requests to use `https://api-free.deepl.com` instead.
+
+ ```http Example request: create custom instruction
+ POST /v3/style_rules/{style_id}/custom_instructions HTTP/2
+ Host: api.deepl.com
+ Authorization: DeepL-Auth-Key [yourAuthKey]
+ User-Agent: YourApp/1.2.3
+ Content-Length: 145
+ Content-Type: application/json
+
+ {
+ "label": "Currency format instruction",
+ "prompt": "Put currency symbols after the numeric amount",
+ "source_language": "en"
+ }
+ ```
+
+ ```json Example response
+ {
+ "style_id": "a74d88fb-ed2a-4943-a664-a4512398b994",
+ "name": "Technical Documentation Rules",
+ "creation_time": "2024-10-01T12:34:56Z",
+ "updated_time": "2024-10-01T12:34:56Z",
+ "language": "en",
+ "version": 2,
+ "configured_rules": {
+ "dates_and_times": {
+ "calendar_era": "use_bc_and_ad"
+ },
+ "punctuation": {
+ "periods_in_academic_degrees": "do_not_use"
+ }
+ },
+ "custom_instructions": [
+ {
+ "id": "68fdb803-c013-4e67-b62e-1aad0ab519cd",
+ "label": "Tone instruction",
+ "prompt": "Use a friendly, diplomatic tone",
+ "source_language": "en"
+ },
+ {
+ "id": "f4515921-8fdf-4e3a-a981-ad7a6717a8aa",
+ "label": "Currency format instruction",
+ "prompt": "Put currency symbols after the numeric amount",
+ "source_language": "en"
+ }
+ ]
+ }
+ ```
+
+
+
+#### Request body parameters
+
+
+ A short descriptive label for the custom instruction. Maximum length: 100 characters.
+
+
+ The instruction text that defines the style requirement. Maximum length: 300 characters.
+
+
+ Optional source language code for the custom instruction (e.g., `en`, `de`, `fr`).
+
+
+### Get a custom instruction
+
+`GET /v3/style_rules/{style_id}/custom_instructions/{instruction_id}`
+
+Get details for a specific custom instruction within a style rule list.
+
+
+
+ The example below uses our API Pro endpoint `https://api.deepl.com`. If you're an API Free user, remember to update your requests to use `https://api-free.deepl.com` instead.
+
+ ```sh Example request: retrieve custom instruction
+ curl -X GET 'https://api.deepl.com/v3/style_rules/{style_id}/custom_instructions/{instruction_id}' \
+ --header 'Authorization: DeepL-Auth-Key [yourAuthKey]'
+ ```
+
+ ```json Example response
+ {
+ "id": "f4515921-8fdf-4e3a-a981-ad7a6717a8aa",
+ "label": "Tone instruction",
+ "prompt": "Use a friendly, diplomatic tone",
+ "source_language": "de"
+ }
+ ```
+
+
+ The example below uses our API Pro endpoint `https://api.deepl.com`. If you're an API Free user, remember to update your requests to use `https://api-free.deepl.com` instead.
+
+ ```http Example request: retrieve custom instruction
+ GET /v3/style_rules/{style_id}/custom_instructions/{instruction_id} HTTP/2
+ Host: api.deepl.com
+ Authorization: DeepL-Auth-Key [yourAuthKey]
+ User-Agent: YourApp/1.2.3
+ ```
+
+ ```json Example response
+ {
+ "id": "f4515921-8fdf-4e3a-a981-ad7a6717a8aa",
+ "label": "Tone instruction",
+ "prompt": "Use a friendly, diplomatic tone",
+ "source_language": "de"
+ }
+ ```
+
+
+
+### Replace a custom instruction
+
+`PUT /v3/style_rules/{style_id}/custom_instructions/{instruction_id}`
+
+Replace an existing custom instruction within a style rule list. All fields must be provided.
+
+
+
+ The example below uses our API Pro endpoint `https://api.deepl.com`. If you're an API Free user, remember to update your requests to use `https://api-free.deepl.com` instead.
+
+ ```sh Example request: replace custom instruction
+ curl -X PUT 'https://api.deepl.com/v3/style_rules/{style_id}/custom_instructions/{instruction_id}' \
+ --header 'Authorization: DeepL-Auth-Key [yourAuthKey]' \
+ --header 'Content-Type: application/json' \
+ --data '{
+ "label": "Updated currency instruction",
+ "prompt": "Put currency symbols after the numeric amount",
+ "source_language": "en"
+ }'
+ ```
+
+ ```json Example response
+ {
+ "id": "f4515921-8fdf-4e3a-a981-ad7a6717a8aa",
+ "label": "Updated currency instruction",
+ "prompt": "Put currency symbols after the numeric amount",
+ "source_language": "en"
+ }
+ ```
+
+
+ The example below uses our API Pro endpoint `https://api.deepl.com`. If you're an API Free user, remember to update your requests to use `https://api-free.deepl.com` instead.
+
+ ```http Example request: replace custom instruction
+ PUT /v3/style_rules/{style_id}/custom_instructions/{instruction_id} HTTP/2
+ Host: api.deepl.com
+ Authorization: DeepL-Auth-Key [yourAuthKey]
+ User-Agent: YourApp/1.2.3
+ Content-Length: 145
+ Content-Type: application/json
+
+ {
+ "label": "Updated currency instruction",
+ "prompt": "Put currency symbols after the numeric amount",
+ "source_language": "en"
+ }
+ ```
+
+ ```json Example response
+ {
+ "id": "f4515921-8fdf-4e3a-a981-ad7a6717a8aa",
+ "label": "Updated currency instruction",
+ "prompt": "Put currency symbols after the numeric amount",
+ "source_language": "en"
+ }
+ ```
+
+
+
+#### Request body parameters
+
+
+ The updated label for the custom instruction. Maximum length: 100 characters.
+
+
+ The updated instruction text. Maximum length: 300 characters.
+
+
+ Optional source language code for the custom instruction (e.g., `en`, `de`, `fr`).
+
+
+### Delete a custom instruction
+
+`DELETE /v3/style_rules/{style_id}/custom_instructions/{instruction_id}`
+
+Delete a specific custom instruction from a style rule list. This operation cannot be undone.
+
+
+
+ The example below uses our API Pro endpoint `https://api.deepl.com`. If you're an API Free user, remember to update your requests to use `https://api-free.deepl.com` instead.
+
+ ```sh Example request: delete custom instruction
+ curl -X DELETE 'https://api.deepl.com/v3/style_rules/{style_id}/custom_instructions/{instruction_id}' \
+ --header 'Authorization: DeepL-Auth-Key [yourAuthKey]'
+ ```
+
+ Returns a `204 No Content` status code on successful deletion. The response body will be empty. If the custom instruction is not found, a `404` error will be returned.
+
+
+ The example below uses our API Pro endpoint `https://api.deepl.com`. If you're an API Free user, remember to update your requests to use `https://api-free.deepl.com` instead.
+
+ ```http Example request: delete custom instruction
+ DELETE /v3/style_rules/{style_id}/custom_instructions/{instruction_id} HTTP/2
+ Host: api.deepl.com
+ Authorization: DeepL-Auth-Key [yourAuthKey]
+ User-Agent: YourApp/1.2.3
+ ```
+
+ Returns a `204 No Content` status code on successful deletion. The response body will be empty. If the custom instruction is not found, a `404` error will be returned.
+
+
+
+## Using style rules
+
+### In translation requests
+
+To use a style rule list in a translation request, include its `style_id` parameter in your translation call. For more information on using style rules in translations, see the [translation documentation](/api-reference/translate).
+
+```sh Example: translate with style rules
+curl -X POST 'https://api.deepl.com/v2/translate' \
+--header 'Authorization: DeepL-Auth-Key [yourAuthKey]' \
+--header 'Content-Type: application/json' \
+--data '{
+ "text": ["Das Treffen ist um 15:00 Uhr"],
+ "source_lang": "DE",
+ "target_lang": "EN",
+ "style_id": "a74d88fb-ed2a-4943-a664-a4512398b994"
+}'
+```
+
+
+ All `model_type` values are supported with style rules.
+
diff --git a/api-reference/style-rules/list-all-style-rules.mdx b/api-reference/style-rules/list-all-style-rules.mdx
index 9ccae68..874c1e0 100644
--- a/api-reference/style-rules/list-all-style-rules.mdx
+++ b/api-reference/style-rules/list-all-style-rules.mdx
@@ -1,9 +1,4 @@
---
openapi: get /v3/style_rules
title: "Get all style rule lists"
-description: "List all style rule lists for your account, with optional detail on configured rules and custom instructions."
----
-
-Returns all style rule lists associated with your account. By default, the response includes only metadata (name, language, version, timestamps). Pass `?detailed=true` to include each list's configured rules and custom instructions.
-
-See the [Style rules overview](/api-reference/style-rules) for how to create, update, and use style rule lists in translation requests.
\ No newline at end of file
+---
\ No newline at end of file
diff --git a/api-reference/translate.mdx b/api-reference/translate.mdx
new file mode 100644
index 0000000..3ec778c
--- /dev/null
+++ b/api-reference/translate.mdx
@@ -0,0 +1,537 @@
+---
+title: "Translate Text"
+sidebarTitle: "Overview"
+description: "API reference for translating text with the DeepL API."
+public: true
+---
+
+The text-translation API currently consists of a single endpoint, `translate`, which is described below.
+
+For details on model selection, see the [`model_type` parameter](#about-the-model_type-parameter).
+
+To learn more about context in DeepL API translations, see our [context parameter guide](/docs/learning-how-tos/examples-and-guides/how-to-use-context-parameter).
+
+For more detail about request body parameters, see the [Request Body Descriptions](/api-reference/translate#request-body-descriptions) section further down on the page.
+
+See [Translation memories](/docs/learning-how-tos/examples-and-guides/how-to-use-translation-memories) for a guide on using translation memories in your translations.
+
+We also provide a spec that is auto-generated from DeepL's OpenAPI file. [You can find it here](/api-reference/translate/request-translation).
+
+
+The total request body size for text translation requests must not exceed 128 KiB (128 · 1024 bytes). Please split up your text into multiple calls if it exceeds this limit.
+
+
+
+
+The examples below use our API Pro endpoint `https://api.deepl.com`. If you're an API Free user, remember to update your requests to use `https://api-free.deepl.com` instead.
+
+```sh Example request: text translation (without glossary)
+curl -X POST 'https://api.deepl.com/v2/translate' \
+--header 'Authorization: DeepL-Auth-Key [yourAuthKey]' \
+--header 'Content-Type: application/json' \
+--data '{
+ "text": [
+ "Hello, world!"
+ ],
+ "target_lang": "DE"
+}'
+```
+
+```sh Example request: text translation (with glossary)
+curl -X POST 'https://api.deepl.com/v2/translate' \
+--header 'Authorization: DeepL-Auth-Key [yourAuthKey]' \
+--header 'Content-Type: application/json' \
+--data '{
+ "text": [
+ "Hello, world!"
+ ],
+ "target_lang": "DE",
+ "source_lang": "EN",
+ "glossary_id": "[yourGlossaryId]"
+}'
+```
+
+```json Example response
+{
+ "translations": [
+ {
+ "detected_source_language": "EN",
+ "text": "Hallo, Welt!"
+ }
+ ]
+}
+```
+
+
+The examples below use our API Pro endpoint `https://api.deepl.com`. If you're an API Free user, remember to update your requests to use `https://api-free.deepl.com` instead.
+
+```http Example request: text translation (without glossary)
+POST /v2/translate HTTP/2
+Host: api.deepl.com
+Authorization: DeepL-Auth-Key [yourAuthKey]
+User-Agent: YourApp/1.2.3
+Content-Length: 45
+Content-Type: application/json
+
+{"text":["Hello, world!"],"target_lang":"DE"}
+```
+
+```http Example request: text translation (with glossary)
+POST /v2/translate HTTP/2
+Host: api.deepl.com
+Authorization: DeepL-Auth-Key [yourAuthKey]
+User-Agent: YourApp/1.2.3
+Content-Length: 97
+Content-Type: application/json
+
+{"text":["Hello, world!"],"target_lang":"DE","source_lang":"EN","glossary_id":"[yourGlossaryId]"}
+```
+
+```json Example response
+{
+ "translations": [
+ {
+ "detected_source_language": "EN",
+ "text": "Hallo, Welt!"
+ }
+ ]
+}
+```
+
+
+```py Example request: text translation (without glossary)
+import deepl
+
+auth_key = "f63c02c5-f056-..." # Replace with your key
+deepl_client = deepl.DeepLClient(auth_key)
+
+result = deepl_client.translate_text("Hello, world!", target_lang="FR")
+print(result.text) # "Bonjour, le monde !"
+```
+
+
+```php Example request: text translation (without glossary)
+$authKey = "f63c02c5-f056-..."; // Replace with your key
+$deeplClient = new DeepL\DeepLClient($authKey);
+
+$result = $deeplClient->translateText('Hello, world!', null, 'fr');
+echo $result->text; // Bonjour, le monde!
+```
+
+
+```cs Example request: text translation (without glossary)
+var authKey = "f63c02c5-f056-..."; // Replace with your key
+var deeplClient = new DeepLClient(authKey);
+
+// Translate text into a target language, in this case, French:
+var translatedText = await deeplClient.TranslateTextAsync(
+ "Hello, world!",
+ LanguageCode.English,
+ LanguageCode.French);
+Console.WriteLine(translatedText); // "Bonjour, le monde !"
+// Note: printing or converting the result to a string uses the output text.
+```
+
+
+```javascript Example request: text translation (without glossary)
+import * as deepl from 'deepl-node';
+
+const authKey = "f63c02c5-f056-..."; // Replace with your key
+const deeplClient = new deepl.DeepLClient(authKey);
+
+(async () => {
+ const result = await deeplClient.translateText('Hello, world!', null, 'fr');
+ console.log(result.text); // Bonjour, le monde !
+})();
+```
+
+
+```java Example request: text translation (without glossary)
+import com.deepl.api.*;
+
+class Example {
+ DeepLClient deeplClient;
+
+ public Example() throws Exception {
+ String authKey = "f63c02c5-f056-..."; // Replace with your key
+ deeplClient = new DeepLClient(authKey);
+ TextResult result =
+ deeplClient.translateText("Hello, world!", null, "fr");
+ System.out.println(result.getText()); // "Bonjour, le monde !"
+ }
+}
+```
+
+
+
+These examples are for demonstration purposes only. In production code, the authentication key should not be hard-coded but instead fetched from a configuration file or environment variable.
+
+Note that we do not include examples for our client libraries in every single section of this reference, but our client libraries *do* support all use cases shown on this page.
+
+
+ Please note that the Translate API is intended to be used for translation between different languages, but requests with the same source and target language are still counted toward billing.
+
+ If trying to convert between variants of the same language (e.g. `EN-US` to `EN-GB`), please refer to [this guide](/docs/learning-how-tos/examples-and-guides/translating-between-variants). Translating between variants of the same language will result in no change to the text.
+
+
+### Request Body Descriptions
+
+
+ Text to be translated. Only UTF-8-encoded plain text is supported. The parameter may be specified multiple times and translations are returned in the same order as they are requested. Each of the parameter values may contain multiple sentences. Up to 50 texts can be sent for translation in one request.
+
+
+ Each text in the array is translated independently — texts do not share context with each other. If one text provides context that would help translate another (e.g. a headline and its article body), either combine them into a single text or use the context parameter to provide shared context.
+
+
+
+ Language of the text to be translated. If omitted, the API will attempt to detect the language of the text and translate it. You can find supported source languages here.
+
+
+ The language into which the text should be translated. You can find supported target languages here.
+
+
+ The context parameter makes it possible to include additional context that can influence a translation but is not translated itself. This additional context can potentially improve translation quality when translating short, low-context source texts such as product names on an e-commerce website, article headlines on a news website, or UI elements.
+
+ For example:
+
+ - When translating a product name, you might pass the product description as context.
+ - When translating a news article headline, you might pass the first few sentences or a summary of the article as context.
+
+
+ For best results, we recommend sending a few complete sentences of context in the same language as the source text. There is no size limit for the context parameter itself, but the request body size limit of 128 KiB still applies to all text translation requests.
+
+ If you send a request with multiple text parameters, the context parameter will be applied to each one.
+
+ Characters included in the context parameter will not be counted toward billing (i.e., there is no additional cost for using the context parameter, and only characters sent in the text parameter(s) will be counted toward billing for text translation even when the context parameter is included in a request).
+
+ See How to Use the Context Parameter Effectively for examples and best practices.
+
+
+ Specifies which DeepL model should be used for translation.
+
+ Possible values:
+ - `latency_optimized`: Optimizes for the lowest latency (default parameter value)
+ - `quality_optimized`: Optimizes for the highest translation quality
+ - `prefer_quality_optimized`: Same as `quality_optimized`
+
+ When the `model_type` parameter is set, the response includes a `model_type_used` field indicating which model was used.
+
+ See [About the model_type parameter](#about-the-model_type-parameter) for more details.
+
+
+ Sets whether the translation engine should first split the input into sentences. For text translations where tag_handling is not set to html, the default value is 1, meaning the engine splits on punctuation and on newlines.
+
+ For text translations where tag_handling=html, the default value is nonewlines, meaning the engine splits on punctuation only, ignoring newlines.
+
+ The use of nonewlines as the default value for text translations where tag_handling=html is new behavior that was implemented in November 2022, when HTML handling was moved out of beta.
+
+ Possible values are:
+
+ 0 - no splitting at all; whole input is treated as one sentence1 (default when tag_handling is not set to html) - splits on punctuation and on newlinesnonewlines (default when tag_handling=html) - splits on punctuation only, ignoring newlines
+
+ For applications that send one sentence per text parameter, we recommend setting split_sentences to 0, in order to prevent the engine from splitting the sentence unintentionally.
+
+ Please note that newlines will split sentences when split_sentences=1. We recommend cleaning files so they don't contain breaking sentences or setting the parameter split_sentences to nonewlines.
+
+ Please note that this value may be overridden by the translation engine. When overridden, a value of:
+
+ 0 will be used if tag_handling is not enablednonewlines will be used if tag_handling is enabled
+
+ ...as these settings yield the best quality.
+
+
+ Sets whether the translation engine should respect the original formatting, even if it would usually correct some aspects.
+ The formatting aspects affected by this setting include:
+
+ - Punctuation at the beginning and end of the sentence
+ - Upper/lower case at the beginning of the sentence
+
+
+
+ Note: for requests sent as URL-encoded forms, boolean values should be specified as "1" or "0".
+
+
+
+ Sets whether the translated text should lean towards formal or informal language. This feature currently only works for target languages DE (German), FR (French), IT (Italian), ES (Spanish), ES-419 (Latin American Spanish), NL (Dutch), PL (Polish), PT-BR and PT-PT (Portuguese), JA (Japanese), and RU (Russian). Learn more about the plain/polite feature for Japanese ↗️. To check formality support dynamically, call GET /v3/languages?resource=translate_text and look for the formality feature key on the target language.
+
+ Setting this parameter with a target language that does not support formality will fail, unless one of the prefer_... options are used. Possible options are:
+
+ default (default)more - for a more formal languageless - for a more informal languageprefer_more - for a more formal language if available, otherwise fallback to default formalityprefer_less - for a more informal language if available, otherwise fallback to default formality
+
+
+ Specify the glossary to use for the translation.
+
+ Important: This requires the source_lang parameter to be set and the language pair of the glossary has to match the language pair of the request.
+
+ Cannot be used together with glossary_ids.
+
+ To check glossary support for a language pair, call GET /v3/languages?resource=translate_text and verify the glossary feature key is present on both the source and target language.
+
+
+ Specify up to 5 glossaries to use for the translation, as an array of glossary IDs. Each glossary's matching terms are applied to the translation.
+
+ Important: This requires the source_lang parameter to be set, and every listed glossary must contain a dictionary for the requested language pair.
+
+ Cannot be used together with glossary_id.
+
+
+
+ Specify the style rule list to use for the translation which can be used to customize translations according to the selected formatting and style conventions.
+
+ The target language has to match the language of the style rule list.
+
+
+
+
+ Specify a list of instructions to customize the translation behavior. Up to 10 custom instructions can be specified, each with a maximum of 300 characters.
+
+
+ The target language must be `de`, `en`, `es`, `fr`, `it`, `ja`, `ko`, `zh` or any variants of these languages.
+
+ You can find best practices on how to write custom instructions [here](/docs/best-practices/custom-instructions).
+
+ To check language support dynamically, call GET /v3/languages?resource=translate_text and check for the style_rules feature key on the target language.
+
+
+ The [translation memory](/api-reference/translation-memory/list-translation-memories) to use for the translation. The value should be the UUID of a translation memory associated with your account.
+
+
+ The minimum matching percentage required for a translation memory segment to be applied (recommended to be 75% or higher). Accepts values from 0 to 100. Default: `75`.
+
+
+ When true, the response will include an additional key-value pair with the key billed_characters and a value that is an integer showing the number of characters from the request that will be counted by DeepL for billing purposes.
+
+ For example: "billed_characters": 42
+
+ At some point in the future, we intend to include billed_characters in the API response by default, at which point it will be necessary to set show_billed_characters to false in order for an API response not to include billed_characters. We will notify users in advance of making this change.
+
+ For requests sent as URL-encoded forms, boolean values should be specified as "1" or "0".
+
+
+
+ Sets which kind of tags should be handled. Options currently available:
+
+ To check tag handling support for a language pair, call GET /v3/languages?resource=translate_text and check the tag_handling feature key is present on both the source and target language.
+
+
+ Select which version of the tag handling algorithm should be used. See tag handling v2.
+
+ v2: Use the improved v2 algorithm.v1: Use the previous v1 algorithm.
+ When `tag_handling` is set, the response includes a `tag_handling_version` field showing which version was applied, including the default when you don't specify one.
+
+
+ The automatic detection of the XML structure won't yield best results in all XML files. You can disable this automatic mechanism altogether by setting the outline_detection parameter to false and selecting the tags that should be considered structure tags. This will split sentences using the splitting_tags parameter.
+
+ In the example below, we achieve the same results as the automatic engine by disabling automatic detection with outline_detection=false and setting the parameters manually to tag_handling=xml, split_sentences=nonewlines, and splitting_tags=par,title.
+
+ ```markup Example request
+
+
+ A document's title
+
+
+ This is the first sentence. Followed by a second one.
+ This is the third sentence.
+
+
+ ```
+
+ ```markup Example response
+
+
+ Der Titel eines Dokuments
+
+
+ Das ist der erste Satz. Gefolgt von einem zweiten.
+ Dies ist der dritte Satz.
+
+
+ ```
+
+ While this approach is slightly more complicated, it allows for greater control over the structure of the translation output.
+
+
+ Note: For requests sent as URL-encoded forms, boolean values should be specified as "1" or "0".
+
+
+
+ Comma-separated list of XML tags which never split sentences. Learn more
+
+
+ Comma-separated list of XML tags which always cause splits. Learn more
+
+
+ Comma-separated list of XML tags that indicate text not to be translated. Learn more
+
+
+
+### About the model\_type parameter
+
+The `model_type` parameter lets a user specify if they would like to optimize for speed until a request is served (latency) or translation quality. This is done on a best-effort basis by DeepL, not every language pair and feature must behave differently depending on this parameter.
+Currently, the DeepL translation API defaults to `latency_optimized` if no `model_type` is included in the request. All features and language pairs are compatible with all `model_type` values.
+Note that the API intentionally does not allow the user to specify a model, but rather their goal, so that the DeepL backend can choose the most suitable model for the user (this avoids users constantly having to update their code with new model versions and learning many different models name and their specifics).
+
+As of December 2025, all source and target languages are supported by next-gen models. Please note that DeepL reserves the right to quietly change which model serves e.g. a `model_type=quality_optimized` request, as long as we think it is a net benefit to the user (e.g. no significant latency increase, but a quality increase, or a significant latency reduction with no or only very slight decrease in quality).
+
+The `/languages` endpoint has not yet been updated to include information about `model_type` support, but we expect to make such a change in the future.
+
+### Multiple Sentences
+
+The translation function will (by default) try to split the text into sentences before translating. Splitting normally works on punctuation marks (e.g. "." or ";"), though you should not assume that every period will be handled as a sentence separator. This means that you can send multiple sentences as a value of the *text* parameter. The translation function will separate the sentences and return the whole translated paragraph.
+
+In some cases, the sentence splitting functionality may cause issues by splitting sentences where there is actually only one sentence. This is especially the case if you're using special/uncommon character sequences which contain punctuation. In this case, you can disable sentence splitting altogether by setting the parameter *split\_sentences* to *0*. Please note that this will cause overlong sentences to be cut off, as the DeepL API cannot translate overly long sentences. In this case, you should split the sentences manually before submitting them for translation.
+
+
+
+The example below uses our API Pro endpoint `https://api.deepl.com`. If you're an API Free user, remember to update your requests to use `https://api-free.deepl.com` instead.
+
+```sh Example request: multiple sentences
+curl -X POST 'https://api.deepl.com/v2/translate' \
+--header 'Authorization: DeepL-Auth-Key [yourAuthKey]' \
+--header 'Content-Type: application/json' \
+--data '{
+ "text": [
+ "The table is green. The chair is black."
+ ],
+ "target_lang": "DE"
+}'
+```
+
+```json Example response
+{
+ "translations": [
+ {
+ "detected_source_language": "EN",
+ "text": "Der Tisch ist grün. Der Stuhl ist schwarz."
+ }
+ ]
+}
+```
+
+
+
+The example below uses our API Pro endpoint `https://api.deepl.com`. If you're an API Free user, remember to update your requests to use `https://api-free.deepl.com` instead.
+
+```http Example request: multiple sentences
+POST /v2/translate HTTP/2
+Host: api.deepl.com
+Authorization: DeepL-Auth-Key [yourAuthKey]
+User-Agent: YourApp/1.2.3
+Content-Length: 71
+Content-Type: application/json
+
+{"text": ["The table is green. The chair is black."],"target_lang":"DE"}
+```
+
+```json Example response
+{
+ "translations": [
+ {
+ "detected_source_language": "EN",
+ "text": "Der Tisch ist grün. Der Stuhl ist schwarz."
+ }
+ ]
+}
+```
+
+
+
+### Translating Large Volumes of Text
+
+There are a few methods to translate larger volumes of text:
+
+* If your text is contiguous, you can submit whole paragraphs to be translated in one request and with one text parameter. Prior to translation, your text will be split into sentences and translated accordingly.
+* The translate function can take several text parameters and will return translations of each such parameter separately in the same order as they are requested (see example below). Each of the parameter values may contain multiple sentences. Up to 50 texts can be sent for translation per request.
+* You can make parallel requests by calling the translate function from several threads/processes.
+
+
+
+The example below uses our API Pro endpoint `https://api.deepl.com`. If you're an API Free user, remember to update your requests to use `https://api-free.deepl.com` instead.
+
+```sh Example request: large volumes of text
+curl -X POST 'https://api.deepl.com/v2/translate' \
+--header 'Authorization: DeepL-Auth-Key [yourAuthKey]' \
+--header 'Content-Type: application/json' \
+--data '{
+ "text": [
+ "This is the first sentence.",
+ "This is the second sentence.",
+ "This is the third sentence."
+ ],
+ "target_lang": "DE"
+}'
+```
+
+```json Example response
+{
+ "translations": [
+ {
+ "detected_source_language": "EN",
+ "text": "Das ist der erste Satz."
+ },
+ {
+ "detected_source_language": "EN",
+ "text": "Das ist der zweite Satz."
+ },
+ {
+ "detected_source_language": "EN",
+ "text": "Dies ist der dritte Satz."
+ }
+ ]
+}
+```
+
+
+
+The example below uses our API Pro endpoint `https://api.deepl.com`. If you're an API Free user, remember to update your requests to use `https://api-free.deepl.com` instead.
+
+```http Example request: large volumes of text
+POST /v2/translate HTTP/2
+Host: api.deepl.com
+Authorization: DeepL-Auth-Key [yourAuthKey]
+User-Agent: YourApp/1.2.3
+Content-Length: 120
+Content-Type: application/json
+
+{"text":["This is the first sentence.","This is the second sentence.","This is the third sentence."],"target_lang":"DE"}
+```
+
+```json Example response
+{
+ "translations": [
+ {
+ "detected_source_language": "EN",
+ "text": "Das ist der erste Satz."
+ },
+ {
+ "detected_source_language": "EN",
+ "text": "Das ist der zweite Satz."
+ },
+ {
+ "detected_source_language": "EN",
+ "text": "Dies ist der dritte Satz."
+ }
+ ]
+}
+```
+
+
+
+### In-Text Markup
+
+You should take precaution with uncommon characters you may have embedded in your texts. Uncommon character sequences, which may be recognized markers within your system, might get translated or removed, resulting in a corrupted structure. In this case, it is advisable to either split the text so that there is no need to send markers, or to convert your markers to XML tags and enable [XML handling](/docs/xml-and-html-handling/xml) or [HTML handling](/docs/xml-and-html-handling/html).
diff --git a/api-reference/translate/request-translation.mdx b/api-reference/translate/request-translation.mdx
index 51c57cb..8827085 100644
--- a/api-reference/translate/request-translation.mdx
+++ b/api-reference/translate/request-translation.mdx
@@ -1,9 +1,5 @@
---
openapi: post /v2/translate
title: "Translate text"
-description: "Translate one or more texts into a target language, with optional glossary, style, formality, and tag-handling controls."
----
-
-Translates up to 50 texts per request into the specified target language. Source language detection is automatic when `source_lang` is omitted.
-
-See the [Translate text overview](/api-reference/translate) for request body descriptions, model selection guidance, sentence splitting behavior, tag handling, and examples for translating large volumes of text.
\ No newline at end of file
+description: ""
+---
\ No newline at end of file
diff --git a/api-reference/usage-and-quota.mdx b/api-reference/usage-and-quota.mdx
new file mode 100644
index 0000000..f7c3dbb
--- /dev/null
+++ b/api-reference/usage-and-quota.mdx
@@ -0,0 +1,79 @@
+---
+title: "Retrieve usage and quota"
+public: true
+sidebarTitle: "Overview"
+description: "API reference for retrieving usage and quota for the current billing period with the DeepL API."
+---
+Retrieve usage information **within the current billing period** together with the corresponding account limits. For **Pro API users**, the `/usage`endpoint returns the following:
+
+* Text and document translation characters consumed in the current billing period in total _and_ for the API key used to make the request
+* Text improvement (`/write`) characters consumed in the current billing period in total _and_ for the API key used to make the request
+* Total characters consumed in the current billing period by the API key used to make the request
+* The key-level character limit for the API key used to make the request, if applicable (if a [key-level usage limit](../docs/getting-started/managing-api-keys#set-api-key-level-usage-limits) is set, it will be reflected in the `api_key_character_limit` field in the response; `1000000000000` will be returned if no key-level limit is set)
+* The current billing period start timestamp
+* The current billing period end timestamp
+* Total characters consumed in the current billing period
+* Subscription-level character limit that applies to the current billing period (if [Cost Control](../docs/best-practices/cost-control.md) is set, it will be reflected in the `character_limit` field in the response; `1000000000000` will be returned if no limit is set)
+
+An example request and response is shown below.
+
+
+Note that responses for Free API and Pro Classic users only contain `character_count` and `character_limit`.
+
+
+The value in the `character_count`field includes both text and document translations as well as text improvement (DeepL API for Write) characters. Characters are counted based on the source text length in Unicode code points, so for example "A", "Δ", "あ", and "深" are each counted as a single character.
+
+We also provide a spec that is auto-generated from DeepL's OpenAPI file. [You can find it here](/api-reference/usage-and-quota/check-usage-and-limits).
+
+
+
+The example below uses our API Pro endpoint `https://api.deepl.com`. If you're an API Free user, remember to update your requests to use `https://api-free.deepl.com` instead.
+
+```bash Example request: check usage and limits
+curl -X GET 'https://api.deepl.com/v2/usage' \
+--header 'Authorization: DeepL-Auth-Key [yourAuthKey]'
+```
+
+```json Example response
+{
+ "products": [
+ {
+ "product_type": "write",
+ "api_key_character_count": 1000000,
+ "character_count": 1250000
+ },
+ {
+ "product_type": "translate",
+ "api_key_character_count": 880000,
+ "character_count": 900000
+ }
+ ],
+ "api_key_character_count": 1880000,
+ "api_key_character_limit": 0,
+ "start_time": "2025-04-24T14:58:02Z",
+ "end_time": "2025-05-24T14:58:02Z",
+ "character_count": 2150000,
+ "character_limit": 20000000
+}
+```
+
+
+The example below uses our API Pro endpoint `https://api.deepl.com`. If you're an API Free user, remember to update your requests to use `https://api-free.deepl.com` instead.
+
+```http Example request: check usage and limits
+GET /v2/usage HTTP/2
+Host: api.deepl.com
+Authorization: DeepL-Auth-Key [yourAuthKey]
+User-Agent: YourApp/1.2.3
+```
+
+```json Example response
+{
+ "character_count": 180118,
+ "character_limit": 1250000
+}
+```
+
+
+
+If you are looking for general API limitations, please see [here](/docs/resources/usage-limits).
diff --git a/api-reference/usage-and-quota/check-usage-and-limits.mdx b/api-reference/usage-and-quota/check-usage-and-limits.mdx
index 5d186de..eedd165 100644
--- a/api-reference/usage-and-quota/check-usage-and-limits.mdx
+++ b/api-reference/usage-and-quota/check-usage-and-limits.mdx
@@ -1,9 +1,4 @@
---
openapi: get /v2/usage
title: "Check usage and limits"
-description: "Retrieve character usage and account limits for the current billing period."
----
-
-Returns character usage and limits for the current billing period. For Pro API accounts, the response breaks down usage by product (`translate`, `write`) and by API key.
-
-See the [Usage and quota overview](/api-reference/usage-and-quota) for field descriptions, plan-specific response differences, and an example response.
\ No newline at end of file
+---
\ No newline at end of file
diff --git a/api-reference/voice.mdx b/api-reference/voice.mdx
new file mode 100644
index 0000000..75fff3d
--- /dev/null
+++ b/api-reference/voice.mdx
@@ -0,0 +1,401 @@
+---
+title: "Translate Speech in Realtime"
+sidebarTitle: "Overview"
+description: "API reference for real-time voice transcription and translation with the DeepL Voice API."
+public: true
+---
+
+The Voice API provides real-time voice transcription and translation services using a WebSocket connection.
+
+
+ The Voice API provides **speech-to-text** capabilities: real-time transcription and text translation of spoken audio. These features are available to all customers with a paid DeepL API subscription.
+
+ **Speech-to-speech** (producing translated TTS output) is a separate capability currently in closed beta and not included in standard API subscriptions.
+
+ Please note that the existing provisions applying to customers' DeepL API Enterprise subscription also apply to
+ DeepL Voice API speech to text with the following applicable additions to the
+ [Terms and Conditions, the Service Specification and the Data
+ Processing Agreement](/api-reference/voice/deepl-voice-api-service-specification-updates)
+ (as new sub-processors have been added to serve specific languages for the Voice API).
+
+
+## Overview
+
+The Voice API provides a way to open WebSocket connections to transcribe and translate audio data. With each connection, you can:
+
+* Send a single audio stream
+* Receive transcripts in the source language
+* Receive translations in multiple target languages
+* closed beta Receive translated speech
+
+The API uses a two-step flow:
+1. [**Request a streaming URL**](/api-reference/voice/request-session) via POST request
+2. [**Stream audio and text**](/api-reference/voice/websocket-streaming) via WebSocket
+
+## Getting Started
+
+To start using the Voice API:
+
+1. Ensure you have a DeepL API Pro account with Voice API access
+2. Review the [Request Session](/api-reference/voice/request-session) documentation
+3. Review the [WebSocket Streaming](/api-reference/voice/websocket-streaming) documentation
+4. Choose your audio format and configuration
+5. Implement the two-step flow in your application
+
+## Supported Languages
+
+We support a wide range of source and target languages (see below). However, while translation is always provided by
+DeepL, for some languages we use external service partners to provide transcription and translated speech.
+All source languages can be translated into any target language.
+
+
+| **Language** | **Transcription** | **Translation** | closed beta
Translated Speech |
+| :------------------------------------- | :---------------: | :-------------: | :------------------------------------------------------------: |
+| Arabic | ⎋ | ✓ | ⎋ |
+| Bengali | ⎋ | ✓ | — |
+| Bulgarian | ⎋ | ✓ | ⎋ |
+| Chinese (Simplified/Traditional) | ✓ | ✓ | ✓ |
+| Croatian | ⎋ | ✓ | — |
+| Czech | ✓ | ✓ | ⎋ |
+| Danish | ⎋ | ✓ | ⎋ |
+| Dutch | ✓ | ✓ | ✓ |
+| English (American/British) | ✓ | ✓ | ✓ |
+| Estonian | ⎋ | ✓ | — |
+| Finnish | ⎋ | ✓ | ⎋ |
+| French | ✓ | ✓ | ✓ |
+| German | ✓ | ✓ | ✓ |
+| Greek | ⎋ | ✓ | ⎋ |
+| Hebrew | ⎋ | ✓ | — |
+| Hindi beta | ⎋ | ✓ | ⎋ |
+| Hungarian | ⎋ | ✓ | ⎋ |
+| Indonesian | ✓ | ✓ | ⎋ |
+| Irish | ⎋ | ✓ | — |
+| Italian | ✓ | ✓ | ✓ |
+| Japanese | ✓ | ✓ | ✓ |
+| Korean | ✓ | ✓ | ✓ |
+| Latvian | ⎋ | ✓ | — |
+| Lithuanian | ⎋ | ✓ | — |
+| Malay beta | ⎋ | ✓ | ⎋ |
+| Maltese | ⎋ | ✓ | — |
+| Norwegian Bokmål | ⎋ | ✓ | ⎋ |
+| Polish | ✓ | ✓ | ✓ |
+| Portuguese (Brazil/Portugal) | ✓ | ✓ | ✓ |
+| Romanian | ✓ | ✓ | ⎋ |
+| Russian | ✓ | ✓ | ✓ |
+| Slovak | ⎋ | ✓ | ⎋ |
+| Slovenian | ⎋ | ✓ | — |
+| Spanish | ✓ | ✓ | ✓ |
+| Swedish | ✓ | ✓ | ✓ |
+| Thai | ⎋ | ✓ | — |
+| Tagalog | ⎋ | ✓ | — |
+| Tamil beta | ⎋ | ✓ | ⎋ |
+| Turkish | ✓ | ✓ | ✓ |
+| Ukrainian | ✓ | ✓ | ⎋ |
+| Vietnamese | ⎋ | ✓ | ⎋ |
+
+✓ provided by DeepL / ⎋ provided by an external service partner / — not available
+
+
+
+ Transcription provided by external service partners (marked with ⎋) cannot yet auto-detect the source language,
+ which you must therefore specify explicitly.
+
+
+To retrieve supported languages and feature availability programmatically, call [`GET /v3/languages?resource=voice`](/api-reference/languages/retrieve-supported-languages-by-resource) and check for the `transcription` and `translated_speech` feature keys. The external flag on these features indicates if they are provided by an external service partner.
+
+## Supported Audio Formats
+
+The API supports various common combinations of streaming codecs and containers with a single channel (mono) audio stream.
+For a detailed list of supported input audio formats, please refer to
+[Source Media Content Type](/api-reference/voice/request-session#body-source-media-content-type).
+For supported output audio formats refer to
+[Target Media Content Type](/api-reference/voice/request-session#body-target-media-content-type).
+
+| **Audio Codec** | **Audio Container** | **Recommended Bitrate** |
+| :--------------------------- | :---------------------------------- | :--------------------------------------------------- |
+| **PCM** | **-** | **256 kbps (16kHz), default recommendation** |
+| **OPUS** | **Matroska / MPEG-TS / Ogg / WebM** | **32 kbps, recommended for low bandwidth scenarios** |
+| AAC | Matroska / MPEG-TS | 96 kbps |
+| FLAC | FLAC / Matroska / Ogg | 256 kbps (16kHz) |
+| MP3 | MPEG / Matroska | 128 kbps |
+
+
+## Customization
+
+Two optional features let you tailor transcription and translation to your domain:
+
+* beta **Spoken terms** — Improve transcription of frequently used terms like company-specific terminology, acronyms, product names, and team member names. Manage in [DeepL Home](https://www.deepl.com/en/voice/spoken-terms); management via API coming soon.
+* **Glossaries** — Enforce specific translations for terms in the target language. Manage in [DeepL Home](https://www.deepl.com/en/glossary) or programmatically with the [Glossaries API](/api-reference/multilingual-glossaries).
+
+## Connecting
+
+The Voice API uses a two-step flow to initiate a session.
+
+
+
+ Make a POST request `v3/voice/realtime` to obtain an ephemeral streaming URL and authentication token. The response will look like this:
+
+ ```json
+ {
+ "streaming_url": "wss://api.deepl.com/v3/voice/realtime/connect",
+ "token": "VGhpcyBpcyBhIGZha2UgdG9rZW4K",
+ "session_id": "4f911080-cfe2-41d4-8269-0e6ec15a0354"
+ }
+ ```
+
+ This step handles:
+ * Authentication and authorization
+ * Main configuration options (audio formats, languages, glossaries, spoken terms, message encoding, etc.)
+
+
+ URL and token are valid for one-time use only.
+
+
+ See the [Request Session](/api-reference/voice/request-session) documentation for details.
+
+
+ Use the received URL to establish a WebSocket connection to `wss://api.deepl.com/v3/voice/realtime/connect?token=VGhpcyBpcyBhIGZha2UgdG9rZW4K`.
+ This step handles exchanging messages on the WebSocket connection:
+ * Sending audio data
+ * Receiving transcripts, translations, and translated speech in real-time
+
+ Messages are sent as TEXT frames (JSON) or BINARY frames (MessagePack), depending on the `message_format` configured in Step 1.
+
+
+ Once a WebSocket connection is established, you must send audio data to prevent connection closure within 30 seconds.
+
+
+ See the [WebSocket Streaming](/api-reference/voice/websocket-streaming) documentation for details.
+
+
+
+
+The following sequence diagram shows the complete flow.
+```mermaid
+sequenceDiagram
+ participant Client
+ participant Voice API
+
+ Note over Client,Voice API: Step 1: Request Session (POST)
+
+ Client->>Voice API: Configuration options
+ Voice API->>Client: Streaming URL and token
+
+ Note over Client,Voice API: Step 2: Start Streaming (WebSocket)
+
+ Client->>Voice API: Establish WebSocket connection
using the streaming URL
+
+ Note over Client,Voice API: WebSocket Connection Established
+
+ Client<<->>Voice API: Bidirectional message exchange:
Send audio, receive transcripts,
translations, and speech
+
+ Note over Client,Voice API: Stream Closed
+```
+
+
+## Streaming Audio and Text
+
+**Sending Source Audio**
+
+Continuously send audio using [source media chunk](/api-reference/voice/websocket-streaming) messages.
+Use smaller chunks to get a lower latency. The recommended chunk duration is 50-250 milliseconds for optimal performance.
+Send an [end of source media](/api-reference/voice/websocket-streaming) message to signal that the
+audio stream is complete and to finalize the processing.
+
+**Receiving Transcripts and Translations**
+
+As the audio is processed, transcripts and translations are delivered incrementally in real-time via
+[source transcript updates](/api-reference/voice/websocket-streaming) and
+[target transcript updates](/api-reference/voice/websocket-streaming):
+
+* **Concluded segments** - Finalized text that will not change. These segments are sent once and remain fixed.
+* **Tentative segments** - Preliminary text that may be refined as more audio context becomes available. These segments may be updated in subsequent messages.
+
+Applications typically merge finalized content into the complete transcript and can display tentative content as
+provisional that will be updated.
+
+ closed beta **Receiving Translated Speech**
+
+Translated speech is delivered incrementally as speech-only audio via
+[target media chunks](/api-reference/voice/websocket-streaming). To save on bandwidth,
+the audio stream contains only synthesized speech without silence or padding. Depending on the
+source audio content there will be pauses w/o data delivered.
+
+Using the text and audio duration information in the response, you are able to mark currently spoken text in the
+received translations or subtitle audio output.
+
+
+The following sequence diagram shows the detailed message exchange during streaming.
+```mermaid
+sequenceDiagram
+ participant Client
+ participant Voice API
+
+ Note over Client,Voice API: WebSocket Connection Established
+
+ par
+ loop Send audio data
+ Client->>Voice API: source_media_chunk
+ end
+ and
+ loop Receive updates
+ Voice API-->>Client: source_transcript_update
+ end
+ and Per target language
+ loop Receive updates
+ Voice API-->>Client: target_transcript_update
+ end
+ and Per target language
+ loop Receive translated speech
+ Voice API-->>Client: target_media_chunk
+ end
+ end
+
+ Client->>Voice API: end_of_source_media
+
+ par
+ loop Final updates
+ Voice API-->>Client: source_transcript_update
+ end
+ and Per target language
+ loop Final updates
+ Voice API-->>Client: target_transcript_update
+ end
+ and Per target language
+ loop Final audio chunks
+ Voice API-->>Client: target_media_chunk
+ end
+ end
+
+ Voice API-->>Client: end_of_source_transcript
+
+ Voice API-->>Client: end_of_target_transcript
(once per target language)
+
+ Voice API-->>Client: end_of_target_media
(once per target language)
+
+ Voice API-->>Client: end_of_stream
+
+ Note over Client,Voice API: Stream Closed
+```
+`par` means parallel execution and `loop` means looped execution.
+
+
+## Reconnecting
+
+Network connections are inherently unreliable.
+Disconnections are unavoidable and must be planned for.
+In case your connection gets disconnected, request a new authentication token to pick up where you left off.
+Make a GET request `v3/voice/realtime?token=`.
+The response will look like this:
+
+```json
+{
+ "streaming_url": "wss://api.deepl.com/v3/voice/realtime/connect",
+ "token": "VGhpcyBpcyBhIGZha2UgdG9rZW4K",
+ "session_id": "4f911080-cfe2-41d4-8269-0e6ec15a0354"
+}
+```
+
+Use the received URL and token to establish a new WebSocket connection.
+Should another reconnection become necessary, repeat the procedure.
+
+See the [Reconnect Session](/api-reference/voice/reconnect-session) documentation for details.
+
+
+Always use the latest authentication token to request a new authentication token.
+The use of outdated tokens will invalidate your session for security reasons.
+
+
+
+If you still have an active connection, requesting a reconnection token will disconnect you.
+
+
+## Message Encoding
+
+The Voice API supports two message encoding formats for WebSocket communication.
+For best developer experience, we recommend starting with the default JSON format
+and later switch to MessagePack if you need better performance.
+
+
+ WebSocket messages must be sent as TEXT frames when using JSON format, and as BINARY frames when using MessagePack format. Sending the wrong frame type will result in connection errors.
+
+
+**JSON (Default)**
+
+This format is human-readable and easy to debug.
+Messages are JSON-encoded and sent as **TEXT** WebSocket frames.
+Fields with binary data (such as audio chunks) are base64-encoded strings.
+
+**MessagePack**
+
+This format offers better bandwidth and performance characteristics.
+Messages are [MessagePack](https://msgpack.org/)-encoded and sent as **BINARY** WebSocket frames. **Messages must be encoded as maps with string keys, not arrays** - ensure your MessagePack library is configured correctly.
+Fields with binary data (such as audio chunks) contain raw binary data instead of base64-encoded strings.
+Compared to JSON, MessagePack typically reduces bandwidth usage by 25-30% and improves message
+encoding/decoding speed by 2x-4x.
+
+
+MessagePack messages **must be encoded as maps with string keys**,
+not as arrays. The message structure must match the JSON schema exactly, with all field names
+preserved as string keys (e.g., `{"source_media_chunk": {"data": }}`). Array-based encoding is not supported.
+
+Ensure your MessagePack library is configured to encode objects as maps rather than arrays.
+Some libraries default to array encoding for performance - check your library's documentation for the correct configuration.
+
+
+
+
+```javascript JSON
+// Raw binary audio data
+const audioData = getAudioChunk();
+
+// Base64 encode the audio data
+const base64Audio = btoa(audioData);
+
+const message = {
+ source_media_chunk: {
+ data: base64Audio
+ }
+};
+
+// Send as TEXT frame
+websocket.send(JSON.stringify(message));
+```
+
+```javascript MessagePack
+import { pack } from 'msgpackr';
+
+// Raw binary audio data
+const audioData = getAudioChunk();
+
+const message = {
+ source_media_chunk: {
+ data: audioData // No base64 encoding needed
+ }
+};
+
+// Send as BINARY frame
+websocket.send(pack(message));
+```
+
+
+
+## Usage Examples
+
+You can find a reference usage example for python at our
+[Github repository for the DeepL Python Library](https://github.com/DeepLcom/deepl-python/tree/main/examples/voice/cli).
+There's no integration of the Voice API in the official DeepL SDKs yet, but you can use any WebSocket client library
+to interact with the API.
+
+## Limitations and Constraints
+
+* Maximum 5 translation targets per session (including translated speech targets)
+* Maximum 1 translated speech target per session
+* Audio chunk size: should not exceed 100 kilobyte or 1 second duration
+* Recommended chunk duration: 50-250 milliseconds for low latency
+* Audio stream speed: maximum 2x real-time
+* Timeout: If no data is received for 30 seconds, the session will be terminated
+* Maximum connection duration: After 1 hour, the connection will be closed. You can establish a new connection by [reconnecting](/api-reference/voice/reconnect-session) to the session.
+* Using any given token more than once to establish a WebSocket connection will terminate the associated session immediately for security reasons.
+
+If you need more translation targets or translated speech targets than these limits allow, open multiple concurrent sessions over the same source audio.
diff --git a/api-reference/voice/request-session.mdx b/api-reference/voice/request-session.mdx
index 98e079c..ffbf9b2 100644
--- a/api-reference/voice/request-session.mdx
+++ b/api-reference/voice/request-session.mdx
@@ -1,11 +1,4 @@
---
openapi: post /v3/voice/realtime
title: "Request Session"
-description: "Request an ephemeral streaming URL and authentication token to initiate a Voice API WebSocket session."
---
-
-Initiates a Voice API session and returns a one-time `streaming_url` and `token` for establishing a WebSocket connection. This is step 1 of the two-step Voice API flow.
-
-Use the returned `streaming_url` and `token` to connect to the WebSocket endpoint described in the [WebSocket Streaming](/api-reference/voice/websocket-streaming) reference.
-
-See the [Voice API overview](/api-reference/voice) for the complete connection flow, supported audio formats, language support, message encoding options, and reconnection guidance.
\ No newline at end of file
diff --git a/docs.json b/docs.json
index c8da049..fbf6e41 100644
--- a/docs.json
+++ b/docs.json
@@ -159,6 +159,7 @@
{
"group": "Translate Text",
"pages": [
+ "api-reference/translate",
"api-reference/translate/request-translation"
],
"drilldown": false
@@ -166,6 +167,7 @@
{
"group": "Translate Documents",
"pages": [
+ "api-reference/document",
"api-reference/document/upload-and-translate-a-document",
"api-reference/document/check-document-status",
"api-reference/document/download-translated-document"
@@ -181,6 +183,7 @@
{
"group": "Glossaries",
"pages": [
+ "api-reference/multilingual-glossaries",
"api-reference/multilingual-glossaries/list-language-pairs-supported-by-glossaries",
"api-reference/multilingual-glossaries/create-a-glossary",
"api-reference/multilingual-glossaries/list-all-glossaries",
@@ -194,6 +197,7 @@
"group": "Glossaries v2",
"tag": "DEPRECATED",
"pages": [
+ "api-reference/glossaries",
"api-reference/glossaries/v2-vs-v3-endpoints",
"api-reference/glossaries/create-a-glossary",
"api-reference/glossaries/list-all-glossaries",
@@ -209,6 +213,7 @@
{
"group": "Style Rules",
"pages": [
+ "api-reference/style-rules",
"api-reference/style-rules/list-all-style-rules",
"api-reference/style-rules/create-style-rule",
"api-reference/style-rules/get-style-rule",
@@ -234,6 +239,7 @@
{
"group": "Voice",
"pages": [
+ "api-reference/voice",
"api-reference/voice/request-session",
"api-reference/voice/websocket-streaming",
"api-reference/voice/reconnect-session"
@@ -243,6 +249,7 @@
"group": "Translate Audio Files",
"hidden": true,
"pages": [
+ "api-reference/jobs-voice-translate",
"api-reference/jobs-voice-translate/create-voice-translate-job",
"api-reference/jobs-voice-translate/get-voice-translate-job-status",
"api-reference/jobs-voice-translate/reference"
@@ -251,6 +258,7 @@
{
"group": "Write",
"pages": [
+ "api-reference/improve-text",
"api-reference/improve-text/request-text-improvement",
"api-reference/improve-text/correct-text"
]
@@ -258,15 +266,18 @@
{
"group": "Languages",
"pages": [
+ "api-reference/languages/retrieve-supported-languages-by-resource",
+ "api-reference/languages/language-feature-use-cases",
"api-reference/languages/retrieve-languages-by-resource",
"api-reference/languages/retrieve-resources",
+ "api-reference/languages/migrate-from-v2-languages",
"api-reference/languages/v3-languages-changelog",
{
"group": "v2 Languages",
"tag": "DEPRECATED",
"pages": [
- "api-reference/languages/retrieve-supported-languages",
- "api-reference/languages/migrate-from-v2-languages"
+ "api-reference/languages",
+ "api-reference/languages/retrieve-supported-languages"
],
"drilldown": false
}
@@ -275,6 +286,7 @@
{
"group": "Admin",
"pages": [
+ "api-reference/admin-api",
"api-reference/admin-api/managing-admin-keys",
{
"group": "Managing Developer Keys",
@@ -291,6 +303,7 @@
{
"group": "Usage & Quota",
"pages": [
+ "api-reference/usage-and-quota",
"api-reference/usage-and-quota/check-usage-and-limits"
],
"drilldown": false
@@ -332,14 +345,8 @@
{
"title": "Resources",
"items": [
- {
- "label": "API Status",
- "href": "https://api-status.deepl.com"
- },
- {
- "label": "DeepL Status",
- "href": "https://www.deeplstatus.com"
- }
+ { "label": "API Status", "href": "https://api-status.deepl.com" },
+ { "label": "DeepL Status", "href": "https://www.deeplstatus.com" }
]
}
],
@@ -352,9 +359,7 @@
},
"api": {
"examples": {
- "languages": [
- "curl"
- ],
+ "languages": ["curl"],
"defaults": "required"
},
"playground": {
@@ -369,7 +374,7 @@
"redirects": [
{
"source": "/api-reference/languages/retrieve-supported-languages-by-product",
- "destination": "/api-reference/languages/retrieve-languages-by-resource"
+ "destination": "/api-reference/languages/retrieve-supported-languages-by-resource"
},
{
"source": "/api-reference/languages/retrieve-products",
@@ -571,4 +576,4 @@
}
}
]
-}
+}
\ No newline at end of file
diff --git a/docs/getting-started/about.mdx b/docs/getting-started/about.mdx
index 39f199c..c0ead69 100644
--- a/docs/getting-started/about.mdx
+++ b/docs/getting-started/about.mdx
@@ -1,6 +1,5 @@
---
title: "About"
-description: "Learn what the DeepL API offers, including translation, writing assistance, and voice capabilities, and how to choose the right plan to get started."
public: false
mode: "wide"
---
@@ -11,28 +10,26 @@ mode: "wide"
alt="Animated DeepL banner"
/>
-The DeepL API provides programmatic access to DeepL's language AI, making it possible to bring high-quality translation and writing capabilities directly into your applications and workflows.
+The DeepL API provides programmatic access to DeepL’s language AI technology, making it possible to bring high quality translation capabilities directly to your websites and applications.
-## Common use cases
+## Common use cases for the DeepL API:
-- **Website localization**: Translate websites and expand to new markets at scale, including dynamic content in e-commerce and news media.
-- **Company communications**: Integrate translation into systems like Confluence and SharePoint so global teams can communicate across language barriers with [maximum data security](https://www.deepl.com/pro-data-security/).
-- **Multilingual products**: Translate chat conversations in real time, localize user-generated content, or embed translation as a core product feature.
+- **Website translation**: Localize websites and expand to new markets efficiently and at scale—even in sectors like e-commerce and news media with a large catalog of dynamic content.
+- **Company communications**: Integrate DeepL’s translation technology into your company’s systems such as Confluence and SharePoint. Enable your global teams to communicate seamlessly and with [maximum data security](https://www.deepl.com/pro-data-security/).
+- **Building multilingual products**: Translate chat conversations to connect users across language barriers in real time. Localize comments and product reviews with the click of a button. Make translation one of your differentiating features—however you imagine it.
-Many leading computer-assisted translation (CAT) tool providers have [integrated DeepL into their software](https://support.deepl.com/hc/articles/360019358599-CAT-tools-supported). To develop a DeepL plugin for your CAT tool, [contact DeepL support](https://support.deepl.com/hc/en-us/requests/new).
+In addition, many leading computer-assisted translation (CAT) tool providers have [integrated DeepL’s technology into their software](https://support.deepl.com/hc/articles/360019358599-CAT-tools-supported). This lets translators benefit from DeepL’s high-quality neural translations within their favorite translation tool. If you would like to develop a DeepL plugin for your CAT tool, [please contact us at here](https://support.deepl.com/hc/en-us/requests/new).
-## Key capabilities
+## Why the DeepL API?
-- **Text and document translation**: Translate plain text or full documents in formats including DOCX, PPTX, XLSX, PDF, HTML, IDML, XLIFF, XML, JSON, DITA, and MIF. See the [document translation reference](/api-reference/document/upload-and-translate-a-document).
-- **Writing assistance**: Improve grammar, spelling, and style with the [Write API](/api-reference/improve-text/request-text-improvement).
-- **Voice translation**: Transcribe and translate spoken audio in real time with the [Voice API](/api-reference/voice/request-session).
-- **Customization**: Apply [glossaries](/api-reference/multilingual-glossaries/create-a-glossary) to enforce specific term translations, or use [style rules](/api-reference/style-rules/list-all-style-rules) to control formatting and tone.
-- **Data security**: On paid plans, texts are not stored on persistent storage and are not used to train DeepL's models. DeepL adheres to EU data protection law and ISO 27001. [Learn more](https://www.deepl.com/pro-data-security/).
+- **High-quality text and document translations**: DeepL [consistently outperforms the competition](https://www.deepl.com/quality.html) in translation quality—and not only for text translation. The API also supports [many document, publishing, and localization formats](/api-reference/document) including DOCX, PPTX, XLSX, PDF, HTML, IDML, XLIFF, XML, JSON, DITA, and MIF.
+- **Maximum data security**: With DeepL API paid plans, texts aren’t saved on persistent storage and aren’t used to train our models. And DeepL adheres strictly to EU data protection laws and ISO 27001. [Learn more about data security at DeepL](https://www.deepl.com/pro-data-security/).
+- **Customization with glossaries**: [Specify your own translations for words and phrases](/api-reference/multilingual-glossaries), and customize your translations consistently and at scale.
To access the DeepL API, [sign up for a plan](https://www.deepl.com/en/pro#api).
---
-**Intended purpose**
+**Intended Purpose of the DeepL API**
-The DeepL API is intended to translate or otherwise process general documents or other content in accordance with the documentation. It is not intended for high-risk applications as defined in [Article 6 of the EU AI Act](https://artificialintelligenceact.eu/article/6/) (including any applicable delegated acts adopted by the European Commission).
\ No newline at end of file
+DeepL API is intended to translate or otherwise process general documents or other content provided by the Customer in accordance with the documentation. DeepL API is not intended for any high-risk applications as defined in [Article 6 of the EU AI Act](https://artificialintelligenceact.eu/article/6/) (including any applicable delegated acts adopted by the European Commission on the basis of this provision).
From 48dd1371acaa14229a2a686c26a200d7ee19bf44 Mon Sep 17 00:00:00 2001
From: Shir Goldberg <3937986+shirgoldbird@users.noreply.github.com>
Date: Wed, 8 Jul 2026 11:01:02 -0400
Subject: [PATCH 8/8] docs: add generated pages from pipeline run
20260707-215756-retire-translate-overview
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit
Generated 2 pages for: learning-how-tos, translate
- api-reference/translate/request-translation.mdx: Retire api-reference/translate.mdx overview page. Route unique content to appropriate docs/ pages per Diataxis. The endpoint page api-reference/translate/request-translation.mdx should stay as a clean openapi stub.
## Target: api-reference/translate/request-translation.mdx
Keep this as a clean OpenAPI stub. It should only contain the frontmatter with `openapi: post /v2/translate`, a title, and optionally a brief one-sentence description. Remove any narrative content, parameter descriptions, or code examples. Current content is already correct — preserve it as-is.
## Target: docs/learning-how-tos/examples-and-guides/translating-text.mdx
Create a new How-to page titled 'How to Translate Text'. This is the primary destination for the narrative and example content from api-reference/translate.mdx. Include the following sections:
1. **Overview / intro**: A brief intro explaining the /v2/translate endpoint is used for text translation, with a note that the request body must not exceed 128 KiB and to split text across multiple calls if needed.
2. **Basic translation examples** (cURL, HTTP, Python, PHP, C#, Node.js, Java tabs): Port the multi-tab code examples verbatim — both the 'without glossary' and 'with glossary' variants. Include the note that auth keys should not be hard-coded in production.
3. **Same-source-and-target-language warning**: Include the Info callout that same-language requests are still billed, and link to the translating-between-variants guide.
4. **About the model_type parameter**: Port the entire 'About the model_type parameter' section as-is, explaining latency_optimized vs quality_optimized, the best-effort nature, the December 2025 language coverage note, and the note about /languages endpoint future updates.
5. **Multiple Sentences**: Port the 'Multiple Sentences' section with its explanation and cURL/HTTP code examples.
6. **Translating Large Volumes of Text**: Port the 'Translating Large Volumes of Text' section with its three bullet-point strategies and cURL/HTTP code examples.
7. **In-Text Markup**: Port the 'In-Text Markup' section explaining the risk of embedded markers and the recommendation to use XML/HTML handling.
Add links back to api-reference/translate/request-translation for the OpenAPI spec reference, and forward links to docs/xml-and-html-handling/xml, docs/xml-and-html-handling/html, and docs/learning-how-tos/examples-and-guides/how-to-use-context-parameter where referenced.
## Target: docs/best-practices/translating-large-volumes.mdx
Create a new Best Practices page titled 'Translating Large Volumes of Text'. This is an extraction and expansion of the 'Translating Large Volumes of Text' section from api-reference/translate.mdx. Include: the three strategies (submitting whole paragraphs, multiple text parameters up to 50 per request, parallel requests), the code examples showing the multi-text array request/response. Cross-link from docs/learning-how-tos/examples-and-guides/translating-text.mdx to this page. This page is a best-practices / how-to focused on batching and throughput.
## Content to discard
- Intro sentence 'The text-translation API currently consists of a single endpoint' — generic boilerplate restating what the nav already shows.
- Forward links to 'Request Body Descriptions' section on the same page — the section is being moved to the OpenAPI spec rendering on request-translation.mdx.
- All ParamField/request body parameter definitions (text, source_lang, target_lang, context, model_type, split_sentences, preserve_formatting, formality, glossary_id, glossary_ids, style_id, custom_instructions, translation_memory_id, translation_memory_threshold, show_billed_characters, tag_handling, tag_handling_version, outline_detection, non_splitting_tags, splitting_tags, ignore_tags) — these are duplicated by the OpenAPI spec auto-rendering on api-reference/translate/request-translation.mdx and must not be re-documented in narrative pages.
- Note 'we do not include examples for client libraries in every section but they do support all use cases' — generic boilerplate.
- Link 'You can find the auto-generated spec here' pointing to request-translation — self-referential nav boilerplate.
- docs/learning-how-tos/examples-and-guides/translating-text.mdx: Retire api-reference/translate.mdx overview page. Route unique content to appropriate docs/ pages per Diataxis. The endpoint page api-reference/translate/request-translation.mdx should stay as a clean openapi stub.
## Target: api-reference/translate/request-translation.mdx
Keep this as a clean OpenAPI stub. It should only contain the frontmatter with `openapi: post /v2/translate`, a title, and optionally a brief one-sentence description. Remove any narrative content, parameter descriptions, or code examples. Current content is already correct — preserve it as-is.
## Target: docs/learning-how-tos/examples-and-guides/translating-text.mdx
Create a new How-to page titled 'How to Translate Text'. This is the primary destination for the narrative and example content from api-reference/translate.mdx. Include the following sections:
1. **Overview / intro**: A brief intro explaining the /v2/translate endpoint is used for text translation, with a note that the request body must not exceed 128 KiB and to split text across multiple calls if needed.
2. **Basic translation examples** (cURL, HTTP, Python, PHP, C#, Node.js, Java tabs): Port the multi-tab code examples verbatim — both the 'without glossary' and 'with glossary' variants. Include the note that auth keys should not be hard-coded in production.
3. **Same-source-and-target-language warning**: Include the Info callout that same-language requests are still billed, and link to the translating-between-variants guide.
4. **About the model_type parameter**: Port the entire 'About the model_type parameter' section as-is, explaining latency_optimized vs quality_optimized, the best-effort nature, the December 2025 language coverage note, and the note about /languages endpoint future updates.
5. **Multiple Sentences**: Port the 'Multiple Sentences' section with its explanation and cURL/HTTP code examples.
6. **Translating Large Volumes of Text**: Port the 'Translating Large Volumes of Text' section with its three bullet-point strategies and cURL/HTTP code examples.
7. **In-Text Markup**: Port the 'In-Text Markup' section explaining the risk of embedded markers and the recommendation to use XML/HTML handling.
Add links back to api-reference/translate/request-translation for the OpenAPI spec reference, and forward links to docs/xml-and-html-handling/xml, docs/xml-and-html-handling/html, and docs/learning-how-tos/examples-and-guides/how-to-use-context-parameter where referenced.
## Target: docs/best-practices/translating-large-volumes.mdx
Create a new Best Practices page titled 'Translating Large Volumes of Text'. This is an extraction and expansion of the 'Translating Large Volumes of Text' section from api-reference/translate.mdx. Include: the three strategies (submitting whole paragraphs, multiple text parameters up to 50 per request, parallel requests), the code examples showing the multi-text array request/response. Cross-link from docs/learning-how-tos/examples-and-guides/translating-text.mdx to this page. This page is a best-practices / how-to focused on batching and throughput.
## Content to discard
- Intro sentence 'The text-translation API currently consists of a single endpoint' — generic boilerplate restating what the nav already shows.
- Forward links to 'Request Body Descriptions' section on the same page — the section is being moved to the OpenAPI spec rendering on request-translation.mdx.
- All ParamField/request body parameter definitions (text, source_lang, target_lang, context, model_type, split_sentences, preserve_formatting, formality, glossary_id, glossary_ids, style_id, custom_instructions, translation_memory_id, translation_memory_threshold, show_billed_characters, tag_handling, tag_handling_version, outline_detection, non_splitting_tags, splitting_tags, ignore_tags) — these are duplicated by the OpenAPI spec auto-rendering on api-reference/translate/request-translation.mdx and must not be re-documented in narrative pages.
- Note 'we do not include examples for client libraries in every section but they do support all use cases' — generic boilerplate.
- Link 'You can find the auto-generated spec here' pointing to request-translation — self-referential nav boilerplate.
---
.../retrieve-languages-by-resource.mdx | 6 +
.../translate/request-translation.mdx | 2 +-
docs.json | 23 +-
.../examples-and-guides/translating-text.mdx | 349 ++++++++++++++++++
4 files changed, 374 insertions(+), 6 deletions(-)
create mode 100644 docs/learning-how-tos/examples-and-guides/translating-text.mdx
diff --git a/api-reference/languages/retrieve-languages-by-resource.mdx b/api-reference/languages/retrieve-languages-by-resource.mdx
index be1a0ba..4201100 100644
--- a/api-reference/languages/retrieve-languages-by-resource.mdx
+++ b/api-reference/languages/retrieve-languages-by-resource.mdx
@@ -1,5 +1,11 @@
---
openapi: get /v3/languages
title: "Retrieve languages"
+description: "Retrieve supported languages and feature availability for a specific DeepL API resource."
---
+Returns the languages supported for a given DeepL API resource, along with feature availability per language (such as formality, glossary support, transcription, and writing style).
+
+Use the `resource` query parameter to filter results by API product. Supported values include `translate_text`, `translate_document`, `glossary`, `write`, and `voice`.
+
+This endpoint replaces the deprecated [`GET /v2/languages`](/api-reference/languages/retrieve-supported-languages) endpoint. See the [migration guide](/api-reference/languages/migrate-from-v2-languages) for details.
diff --git a/api-reference/translate/request-translation.mdx b/api-reference/translate/request-translation.mdx
index 8827085..a58724d 100644
--- a/api-reference/translate/request-translation.mdx
+++ b/api-reference/translate/request-translation.mdx
@@ -1,5 +1,5 @@
---
openapi: post /v2/translate
title: "Translate text"
-description: ""
+description: "Translate one or more text strings into a target language."
---
\ No newline at end of file
diff --git a/docs.json b/docs.json
index fbf6e41..951cb47 100644
--- a/docs.json
+++ b/docs.json
@@ -94,6 +94,12 @@
"docs/retrieving-usage-data"
]
},
+ {
+ "group": "learning-how-tos",
+ "pages": [
+ "docs/learning-how-tos/examples-and-guides/translating-text"
+ ]
+ },
{
"group": "Going to Production",
"pages": [
@@ -159,7 +165,6 @@
{
"group": "Translate Text",
"pages": [
- "api-reference/translate",
"api-reference/translate/request-translation"
],
"drilldown": false
@@ -345,8 +350,14 @@
{
"title": "Resources",
"items": [
- { "label": "API Status", "href": "https://api-status.deepl.com" },
- { "label": "DeepL Status", "href": "https://www.deeplstatus.com" }
+ {
+ "label": "API Status",
+ "href": "https://api-status.deepl.com"
+ },
+ {
+ "label": "DeepL Status",
+ "href": "https://www.deeplstatus.com"
+ }
]
}
],
@@ -359,7 +370,9 @@
},
"api": {
"examples": {
- "languages": ["curl"],
+ "languages": [
+ "curl"
+ ],
"defaults": "required"
},
"playground": {
@@ -576,4 +589,4 @@
}
}
]
-}
\ No newline at end of file
+}
diff --git a/docs/learning-how-tos/examples-and-guides/translating-text.mdx b/docs/learning-how-tos/examples-and-guides/translating-text.mdx
new file mode 100644
index 0000000..276b903
--- /dev/null
+++ b/docs/learning-how-tos/examples-and-guides/translating-text.mdx
@@ -0,0 +1,349 @@
+---
+title: "How to Translate Text"
+description: "Send text translation requests to the DeepL API, with examples for glossaries, multiple sentences, large volumes, and in-text markup."
+public: true
+---
+
+The `/v2/translate` endpoint translates one or more text strings into a target language. The total request body size must not exceed 128 KiB (128 · 1024 bytes). If your content exceeds this limit, split it across multiple requests.
+
+For the full parameter reference, see the [Translate text API reference](/api-reference/translate/request-translation).
+
+## Basic translation
+
+The examples below show a minimal translation request — with and without a glossary. Use the tabs to switch between cURL, HTTP, and SDK examples.
+
+
+ The examples below use the API Pro endpoint `https://api.deepl.com`. If you're on the API Free plan, use `https://api-free.deepl.com` instead. Glossary examples are shown in full for the cURL and HTTP tabs. For SDK languages (Python, PHP, C#, Node.js, Java), only the non-glossary case is shown here; see the [SDK-specific glossary guide](/docs/learning-how-tos/examples-and-guides/using-glossaries) for glossary usage with each SDK.
+
+
+
+
+```sh Example request: text translation (without glossary)
+curl -X POST 'https://api.deepl.com/v2/translate' \
+--header 'Authorization: DeepL-Auth-Key [yourAuthKey]' \
+--header 'Content-Type: application/json' \
+--data '{
+ "text": [
+ "Hello, world!"
+ ],
+ "target_lang": "DE"
+}'
+```
+
+```sh Example request: text translation (with glossary)
+curl -X POST 'https://api.deepl.com/v2/translate' \
+--header 'Authorization: DeepL-Auth-Key [yourAuthKey]' \
+--header 'Content-Type: application/json' \
+--data '{
+ "text": [
+ "Hello, world!"
+ ],
+ "target_lang": "DE",
+ "source_lang": "EN",
+ "glossary_id": "[yourGlossaryId]"
+}'
+```
+
+```json Example response
+{
+ "translations": [
+ {
+ "detected_source_language": "EN",
+ "text": "Hallo, Welt!"
+ }
+ ]
+}
+```
+
+
+```http Example request: text translation (without glossary)
+POST /v2/translate HTTP/2
+Host: api.deepl.com
+Authorization: DeepL-Auth-Key [yourAuthKey]
+User-Agent: YourApp/1.2.3
+Content-Length: 45
+Content-Type: application/json
+
+{"text":["Hello, world!"],"target_lang":"DE"}
+```
+
+```http Example request: text translation (with glossary)
+POST /v2/translate HTTP/2
+Host: api.deepl.com
+Authorization: DeepL-Auth-Key [yourAuthKey]
+User-Agent: YourApp/1.2.3
+Content-Length: 97
+Content-Type: application/json
+
+{"text":["Hello, world!"],"target_lang":"DE","source_lang":"EN","glossary_id":"[yourGlossaryId]"}
+```
+
+```json Example response
+{
+ "translations": [
+ {
+ "detected_source_language": "EN",
+ "text": "Hallo, Welt!"
+ }
+ ]
+}
+```
+
+
+```py Example request: text translation (without glossary)
+import deepl
+
+auth_key = "f63c02c5-f056-..." # Replace with your key
+deepl_client = deepl.DeepLClient(auth_key)
+
+result = deepl_client.translate_text("Hello, world!", target_lang="FR")
+print(result.text) # Output: Bonjour, le monde !
+```
+
+`translate_text()` returns a `TextResult` object. The key fields are:
+
+- `result.text` — the translated string
+- `result.detected_source_lang` — the source language detected by the API (e.g., `"EN"`)
+
+
+```php Example request: text translation (without glossary)
+$authKey = "f63c02c5-f056-..."; // Replace with your key
+$deeplClient = new DeepL\DeepLClient($authKey);
+
+$result = $deeplClient->translateText('Hello, world!', null, 'fr');
+echo $result->text; // Output: Bonjour, le monde!
+```
+
+`translateText()` returns a `TextResult` object. The key fields are:
+
+- `$result->text` — the translated string
+- `$result->detectedSourceLang` — the source language detected by the API (e.g., `"EN"`)
+
+
+```cs Example request: text translation (without glossary)
+var authKey = "f63c02c5-f056-..."; // Replace with your key
+var deeplClient = new DeepLClient(authKey);
+
+var translatedText = await deeplClient.TranslateTextAsync(
+ "Hello, world!",
+ LanguageCode.English,
+ LanguageCode.French);
+Console.WriteLine(translatedText); // Output: Bonjour, le monde !
+```
+
+`TranslateTextAsync()` returns a `TextResult` object. The key fields are:
+
+- `translatedText.Text` — the translated string
+- `translatedText.DetectedSourceLanguageCode` — the source language detected by the API (e.g., `"EN"`)
+
+
+```javascript Example request: text translation (without glossary)
+import * as deepl from 'deepl-node';
+
+const authKey = "f63c02c5-f056-..."; // Replace with your key
+const deeplClient = new deepl.DeepLClient(authKey);
+
+(async () => {
+ const result = await deeplClient.translateText('Hello, world!', null, 'fr');
+ console.log(result.text); // Output: Bonjour, le monde !
+})();
+```
+
+`translateText()` returns a `TextResult` object. The key fields are:
+
+- `result.text` — the translated string
+- `result.detectedSourceLang` — the source language detected by the API (e.g., `"en"`)
+
+
+```java Example request: text translation (without glossary)
+import com.deepl.api.*;
+
+class Example {
+ DeepLClient deeplClient;
+
+ public Example() throws Exception {
+ String authKey = "f63c02c5-f056-..."; // Replace with your key
+ deeplClient = new DeepLClient(authKey);
+ TextResult result =
+ deeplClient.translateText("Hello, world!", null, "fr");
+ System.out.println(result.getText()); // Output: Bonjour, le monde !
+ }
+}
+```
+
+`translateText()` returns a `TextResult` object. The key fields are:
+
+- `result.getText()` — the translated string
+- `result.getDetectedSourceLanguage()` — the source language detected by the API (e.g., `"en"`)
+
+
+
+In production code, do not hard-code your authentication key. Fetch it from an environment variable or configuration file instead.
+
+## Optimizing for speed or quality
+
+Set `model_type` to `latency_optimized` for real-time applications or `quality_optimized` for high-quality batch jobs. This is handled on a best-effort basis — not every language pair or feature will behave differently depending on this setting. When `model_type` is set, the response includes a `model_type_used` field indicating which model was actually used.
+
+```sh Example request: quality-optimized translation
+curl -X POST 'https://api.deepl.com/v2/translate' \
+--header 'Authorization: DeepL-Auth-Key [yourAuthKey]' \
+--header 'Content-Type: application/json' \
+--data '{
+ "text": [
+ "Hello, world!"
+ ],
+ "target_lang": "DE",
+ "model_type": "quality_optimized"
+}'
+```
+
+
+ `prefer_quality_optimized` is a legacy alias for `quality_optimized` and behaves identically. For new integrations, use `quality_optimized` instead. For the full list of accepted values, see the [Translate text API reference](/api-reference/translate/request-translation).
+
+
+## Multiple sentences
+
+By default, the translation engine splits input text into sentences before translating, using punctuation marks as delimiters. You can send a full paragraph as a single `text` value and the engine will split, translate, and reassemble it automatically.
+
+In some cases, sentence splitting may produce incorrect results — for example, if your text contains unusual character sequences that include punctuation. You can disable splitting by setting `split_sentences` to `0`. Note that disabling splitting may cause very long sentences to be cut off; if this is a concern, split the sentences manually before sending them.
+
+Avoid sending requests where source and target language are the same — they are still billed.
+
+
+ The Translate API is intended for translation between different languages, but requests where the source and target language are the same are still counted toward billing.
+
+ If you want to convert between variants of the same language (for example, `EN-US` to `EN-GB`), see [Translating Between Language Variants](/docs/learning-how-tos/examples-and-guides/translating-between-variants). Translating between variants of the same language results in no change to the text.
+
+
+
+
+```sh Example request: multiple sentences
+curl -X POST 'https://api.deepl.com/v2/translate' \
+--header 'Authorization: DeepL-Auth-Key [yourAuthKey]' \
+--header 'Content-Type: application/json' \
+--data '{
+ "text": [
+ "The table is green. The chair is black."
+ ],
+ "target_lang": "DE"
+}'
+```
+
+```json Example response
+{
+ "translations": [
+ {
+ "detected_source_language": "EN",
+ "text": "Der Tisch ist grün. Der Stuhl ist schwarz."
+ }
+ ]
+}
+```
+
+
+```http Example request: multiple sentences
+POST /v2/translate HTTP/2
+Host: api.deepl.com
+Authorization: DeepL-Auth-Key [yourAuthKey]
+User-Agent: YourApp/1.2.3
+Content-Length: 71
+Content-Type: application/json
+
+{"text": ["The table is green. The chair is black."],"target_lang":"DE"}
+```
+
+```json Example response
+{
+ "translations": [
+ {
+ "detected_source_language": "EN",
+ "text": "Der Tisch ist grün. Der Stuhl ist schwarz."
+ }
+ ]
+}
+```
+
+
+
+## Translating large volumes of text
+
+There are three strategies for translating larger volumes of text:
+
+- **Submit whole paragraphs.** If your text is contiguous, send it as a single `text` value. The engine splits it into sentences, translates them, and returns the complete translated paragraph.
+- **Use multiple `text` values per request.** A single request can include up to 50 text strings. The API returns translations in the same order they were sent.
+- **Make parallel requests.** Call the translate function from multiple threads or processes simultaneously.
+
+
+
+
+```sh Example request: multiple text strings
+curl -X POST 'https://api.deepl.com/v2/translate' \
+--header 'Authorization: DeepL-Auth-Key [yourAuthKey]' \
+--header 'Content-Type: application/json' \
+--data '{
+ "text": [
+ "This is the first sentence.",
+ "This is the second sentence.",
+ "This is the third sentence."
+ ],
+ "target_lang": "DE"
+}'
+```
+
+```json Example response
+{
+ "translations": [
+ {
+ "detected_source_language": "EN",
+ "text": "Das ist der erste Satz."
+ },
+ {
+ "detected_source_language": "EN",
+ "text": "Das ist der zweite Satz."
+ },
+ {
+ "detected_source_language": "EN",
+ "text": "Dies ist der dritte Satz."
+ }
+ ]
+}
+```
+
+
+```http Example request: multiple text strings
+POST /v2/translate HTTP/2
+Host: api.deepl.com
+Authorization: DeepL-Auth-Key [yourAuthKey]
+User-Agent: YourApp/1.2.3
+Content-Length: 120
+Content-Type: application/json
+
+{"text":["This is the first sentence.","This is the second sentence.","This is the third sentence."],"target_lang":"DE"}
+```
+
+```json Example response
+{
+ "translations": [
+ {
+ "detected_source_language": "EN",
+ "text": "Das ist der erste Satz."
+ },
+ {
+ "detected_source_language": "EN",
+ "text": "Das ist der zweite Satz."
+ },
+ {
+ "detected_source_language": "EN",
+ "text": "Dies ist der dritte Satz."
+ }
+ ]
+}
+```
+
+
+
+## In-text markup
+
+Take care with custom markers or delimiters embedded in your text. Unusual character sequences that contain punctuation or symbols may be translated or removed by the engine, corrupting your markup structure.
+
+If your text contains embedded markers, either strip them out before sending, or convert them to XML or HTML tags and enable [XML handling](/docs/xml-and-html-handling/xml) or [HTML handling](/docs/xml-and-html-handling/html) so the engine preserves them during translation.
\ No newline at end of file