openapi: 3.0.3 info: title: DeepL API Documentation description: The DeepL API provides programmatic access to DeepL’s language AI technology. termsOfService: https://www.deepl.com/pro-license contact: name: DeepL - Contact us url: https://www.deepl.com/contact-us version: 3.9.0 externalDocs: description: DeepL Pro - Plans and pricing url: https://www.deepl.com/pro#developer servers: - url: https://api.deepl.com description: DeepL API Pro - url: https://api-free.deepl.com description: DeepL API Free tags: - name: TranslateText description: |- The text-translation API currently consists of a single endpoint, `translate`, which is described below. To learn more about context in DeepL API translations, we recommend [this article](https://www.deepl.com/docs-api/general/working-with-context). - name: TranslateDocuments description: |- The document translation API allows you to translate whole documents and supports the following file types and extensions: * `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, version 2.1 * `srt` - SRT Document * `jpeg / jpg / png` - Image Please note that with every submitted document of type .pptx, .docx, .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. Translating a document usually involves three types of HTTP requests: - [upload](https://www.deepl.com/docs-api/documents/translate-document) the document to be translated, - periodically [check the status](https://www.deepl.com/docs-api/documents/get-document-status) of the document translation, - once the status call reports `done`, [download](https://www.deepl.com/docs-api/documents/download-document) the translated document. To learn more about context in DeepL API translations, we recommend [this article](https://www.deepl.com/docs-api/general/working-with-context). - name: RephraseText description: |- The `rephrase` endpoint is used to make corrections and adjustments to texts based on style or tone. For more details, visit [this documentation page](https://developers.deepl.com/docs/api-reference/improve-text) - name: ManageMultilingualGlossaries description: |- The *glossary* functions allow you to create, inspect, edit and delete glossaries. Glossaries created with the glossary function can be used in translate requests by specifying the `glossary_id` parameter. A glossary contains (several) dictionaries. A dictionary is a mapping of source phrases to target phrases for a single language pair. If you encounter issues, please let us know at support@DeepL.com. Currently you can create glossaries with any of the languages DeepL supports. The maximum size limit for a glossary is 10 MiB = 10485760 bytes and each source/target text, as well as the name of the glossary, is limited to 1024 UTF-8 bytes. A total of 1000 glossaries are allowed per account. When creating a dictionary with target language `EN`, `PT`, or `ZH`, it's not necessary to specify a variant (e.g. `EN-US`, `EN-GB`, `PT-PT`, `PT-BR`, or `ZH-HANS`). Dictionaries with target language `EN` can be used in translations with either English variant. Similarly `PT`, and `ZH` dictionaries can be used in translations with their corresponding variants. (When you provide the ID of a glossary to a translation, the appropriate dictionary is automatically applied. Currently glossaries can not yet be used with source language detection.) Glossaries created via the DeepL API are now unified with glossaries created via the DeepL website and DeepL apps. Please only use the v3 glossary API in conjunction with multilingual or edited glossaries from the website. - name: ManageGlossaries description: |- Please note that this is the spec for the (old) v2 glossary endpoint. We recommend users switch to the newer v3 glossary endpoints, which support editability and multilinguality. The *glossary* functions allow you to create, inspect, and delete glossaries. Glossaries created with the glossary function can be used in translate requests by specifying the `glossary_id` parameter. If you encounter issues, please let us know at support@DeepL.com. Currently you can create glossaries with any of the languages DeepL supports. The maximum size limit for a glossary is 10 MiB = 10485760 bytes and each source/target text, as well as the name of the glossary, is limited to 1024 UTF-8 bytes. A total of 1000 glossaries are allowed per account. When creating a glossary with target language `EN`, `PT`, or `ZH`, it's not necessary to specify a variant (e.g. `EN-US`, `EN-GB`, `PT-PT`, `PT-BR`, or `ZH-HANS`). Glossaries with target language `EN` can be used in translations with either English variant. Similarly `PT`, and `ZH` glossaries can be used in translations with their corresponding variants. Note that on the v2 API, 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](https://www.deepl.com/docs-api/glossaries/get-glossary-entries) and store the current glossary's entries, - locally modify the glossary entries, - [delete](https://www.deepl.com/docs-api/glossaries/delete-glossary) the existing glossary, - [create a new glossary](https://www.deepl.com/docs-api/glossaries/create-glossary) with the same name. - name: MetaInformation description: Information about API usage and value ranges - name: StyleRules description: |- The *style rules* functions allow you to create, inspect, edit and delete style rules. Style rules can be used in translate requests by specifying the `style_id` parameter, allowing 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. If you encounter issues, please let us know at support@DeepL.com. - name: VoiceAPI description: |- The Voice API provides real-time voice transcription and translation services. Use a two-step flow: first request a streaming URL via REST, then establish a WebSocket connection for streaming audio and receiving transcriptions. paths: /v2/translate: post: tags: - TranslateText summary: Request Translation operationId: translateText description: |- The translate function. The total request body size must not exceed 128 KiB (128 · 1024 bytes). Please split up your text into multiple calls if it exceeds this limit. requestBody: required: true content: application/json: schema: type: object required: - text - target_lang properties: text: description: |- 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. type: array items: type: string example: Hello, World! source_lang: $ref: '#/components/schemas/SourceLanguage' target_lang: $ref: '#/components/schemas/TargetLanguage' context: $ref: '#/components/schemas/Context' show_billed_characters: $ref: '#/components/schemas/ShowBilledCharacters' split_sentences: $ref: '#/components/schemas/SplitSentencesOption' preserve_formatting: $ref: '#/components/schemas/PreserveFormattingOption' formality: $ref: '#/components/schemas/Formality' model_type: $ref: '#/components/schemas/ModelType' glossary_id: allOf: - $ref: '#/components/schemas/GlossaryId' - description: |- 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. type: string custom_instructions: description: |- 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. **Important:** The target language must be `de`, `en`, `es`, `fr`, `it`, `ja`, `ko`, `zh` or any variants of these languages. **Note:** Any request with the `custom_instructions` parameter enabled will default to use the `quality_optimized` model type. Requests combining `custom_instructions` and `model_type: latency_optimized` will be rejected. type: array items: type: string example: "Use a friendly, diplomatic tone" enable_beta_languages: description: |- Enables 81 additional beta languages. See the full list at https://developers.deepl.com/docs/getting-started/supported-languages#beta-languages. **Note:** Any request with the `enable_beta_languages` parameter enabled will use `quality_optimized` models. Requests combining `enable_beta_languages: true` and `model_type: latency_optimized` will be rejected. Beta languages do not support formality or glossaries. type: boolean default: false tag_handling: $ref: '#/components/schemas/TagHandlingOption' outline_detection: $ref: '#/components/schemas/OutlineDetectionOption' non_splitting_tags: $ref: '#/components/schemas/NonSplittingTagList' splitting_tags: $ref: '#/components/schemas/SplittingTagList' ignore_tags: $ref: '#/components/schemas/IgnoreTagList' application/x-www-form-urlencoded: examples: Basic: summary: Basic Example value: text: - Hello, world! target_lang: DE Glossary: summary: Using a Glossary value: text: - Hello, world! target_lang: DE source_lang: EN glossary_id: '[yourGlossaryId]' MultipleSentences: summary: Multiple Sentences value: text: - The table is green. The chair is black. target_lang: DE LargeVolumes: summary: Large Volumes of Text value: text: - This is the first sentence. - This is the second sentence. - This is the third sentence. target_lang: DE schema: type: object required: - text - target_lang properties: text: description: 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. type: array items: type: string source_lang: $ref: '#/components/schemas/SourceLanguage' target_lang: $ref: '#/components/schemas/TargetLanguage' context: $ref: '#/components/schemas/Context' show_billed_characters: $ref: '#/components/schemas/ShowBilledCharacters' split_sentences: $ref: '#/components/schemas/SplitSentencesOption' preserve_formatting: $ref: '#/components/schemas/PreserveFormattingOptionStr' formality: $ref: '#/components/schemas/Formality' model_type: $ref: '#/components/schemas/ModelType' glossary_id: allOf: - $ref: '#/components/schemas/GlossaryId' description: 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. tag_handling: $ref: '#/components/schemas/TagHandlingOption' tag_handling_version: $ref: '#/components/schemas/TagHandlingVersionOption' outline_detection: $ref: '#/components/schemas/OutlineDetectionOptionStr' non_splitting_tags: $ref: '#/components/schemas/NonSplittingTagCommaSeparatedList' splitting_tags: $ref: '#/components/schemas/SplittingTagCommaSeparatedList' ignore_tags: $ref: '#/components/schemas/IgnoreTagCommaSeparatedList' encoding: text: style: form explode: true responses: 200: description: The translate function returns a JSON representation of the translations in the order the text parameters have been specified. headers: X-Trace-ID: $ref: '#/components/headers/X-Trace-ID' content: application/json: schema: type: object properties: translations: type: array minItems: 1 items: type: object properties: detected_source_language: allOf: - $ref: '#/components/schemas/SourceLanguage' description: The language detected in the source text. It reflects the value of the `source_lang` parameter, when specified. text: description: The translated text. type: string billed_characters: description: Number of characters counted by DeepL for billing purposes. Only present if the show_billed_characters parameter is set to true. type: integer model_type_used: description: Indicates the translation model used. Only present if model_type parameter is included in the request. type: string example: quality_optimized examples: Basic: value: translations: - detected_source_language: EN text: Hallo, Welt! billed_characters: 42 Glossary: value: translations: - text: Hallo, Welt! MultipleSentences: value: translations: - detected_source_language: EN text: Der Tisch ist grün. Der Stuhl ist schwarz. LargeVolumes: value: 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. 400: $ref: '#/components/responses/BadRequest' 403: $ref: '#/components/responses/Forbidden' 404: $ref: '#/components/responses/NotFound' 413: $ref: '#/components/responses/PayloadTooLarge' 414: $ref: '#/components/responses/URITooLong' 429: $ref: '#/components/responses/TooManyRequests' 456: $ref: '#/components/responses/QuotaExceeded' 500: $ref: '#/components/responses/InternalServerError' 504: $ref: '#/components/responses/ServiceUnavailable' 529: $ref: '#/components/responses/TooManyRequests' security: - auth_header: [] /v2/document: post: tags: - TranslateDocuments summary: Upload and Translate a Document operationId: translateDocument description: |- 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](https://www.deepl.com/docs-api/documents/get-document-status) and to [download the translated document](https://www.deepl.com/docs-api/documents/download-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. The maximum upload limit for documents is [available here](https://support.deepl.com/hc/articles/360020582359-Document-formats) and may vary based on API plan and document type. 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. requestBody: required: true content: multipart/form-data: examples: Basic: summary: Basic Document Translation value: target_lang: DE file: '@document.docx' Glossary: summary: Using a Glossary value: source_lang: EN target_lang: DE file: '@document.docx' glossary_id: '[yourGlossaryId]' schema: type: object required: - target_lang - file properties: source_lang: $ref: '#/components/schemas/SourceLanguage' target_lang: $ref: '#/components/schemas/TargetLanguage' file: type: string format: binary description: |- 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, version 2.1 * `srt` - SRT Document * `jpeg / jpg / png` - Image filename: type: string description: The name of the uploaded file. Can be used as an alternative to including the file name in the file part's content disposition. output_format: type: string description: |- File extension of desired format of translated file, for example: `docx`. 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](https://www.deepl.com/docs-api/documents/format-conversions) for the permitted combinations. formality: $ref: '#/components/schemas/Formality' glossary_id: $ref: '#/components/schemas/GlossaryId' responses: 200: description: The document function returns a JSON object containing the ID and encryption key assigned to the uploaded document. Once received by the server, uploaded documents are immediately encrypted using a uniquely generated encryption key. This key is not persistently stored on the server. Therefore, it must be stored by the client and sent back to the server with every subsequent request that refers to this particular document. headers: X-Trace-ID: $ref: '#/components/headers/X-Trace-ID' content: application/json: schema: type: object properties: document_id: description: A unique ID assigned to the uploaded document and the translation process. Must be used when referring to this particular document in subsequent API requests. type: string document_key: description: A unique key that is used to encrypt the uploaded document as well as the resulting translation on the server side. Must be provided with every subsequent API request regarding this particular document. type: string example: document_id: 04DE5AD98A02647D83285A36021911C6 document_key: 0CB0054F1C132C1625B392EADDA41CB754A742822F6877173029A6C487E7F60A 400: $ref: '#/components/responses/BadRequest' 403: $ref: '#/components/responses/Forbidden' 404: $ref: '#/components/responses/NotFound' 413: $ref: '#/components/responses/PayloadTooLarge' 429: $ref: '#/components/responses/TooManyRequests' 456: $ref: '#/components/responses/QuotaExceeded' 500: $ref: '#/components/responses/InternalServerError' 504: $ref: '#/components/responses/ServiceUnavailable' 529: $ref: '#/components/responses/TooManyRequests' security: - auth_header: [] /v2/document/{document_id}: post: tags: - TranslateDocuments summary: Check Document Status description: |- Retrieve the current status of a document translation process. If the translation is still in progress, the estimated time remaining is also included in the response. operationId: getDocumentStatus parameters: - $ref: '#/components/parameters/DocumentID' requestBody: required: true content: application/x-www-form-urlencoded: schema: $ref: '#/components/schemas/DocumentKey' examples: basic: summary: Basic value: document_key: 0CB0054F1C132C1625B392EADDA41CB754A742822F6877173029A6C487E7F60A application/json: schema: $ref: '#/components/schemas/DocumentKey' responses: 200: description: The document status request returns a JSON object containing the document ID that was used in the request as well as string indicating the current status of the translation process. While the translation is running, the estimated number of seconds remaining until the process is done is also included in the response. headers: X-Trace-ID: $ref: '#/components/headers/X-Trace-ID' content: application/json: schema: type: object required: - document_id - status properties: document_id: description: A unique ID assigned to the uploaded document and the requested translation process. The same ID that was used when requesting the translation status. type: string status: description: |- A short description of the state the document translation process is currently in. Possible values are: * `queued` - the translation job is waiting in line to be processed * `translating` - the translation is currently ongoing * `done` - the translation is done and the translated document is ready for download * `error` - an irrecoverable error occurred while translating the document type: string enum: - queued - translating - done - error seconds_remaining: description: |- Estimated number of seconds until the translation is done. This parameter is only included while `status` is `"translating"`. type: integer billed_characters: description: The number of characters billed to your account. The characters will only be billed after a successful download request. type: integer error_message: description: |- A short description of the error, if available. Note that the content is subject to change. This parameter may be included if an error occurred during translation. type: string examples: translating: summary: Translating value: document_id: 04DE5AD98A02647D83285A36021911C6 status: translating seconds_remaining: 20 done: summary: Done value: document_id: 04DE5AD98A02647D83285A36021911C6 status: done billed_characters: 1337 queued: summary: Queued value: document_id: 04DE5AD98A02647D83285A36021911C6 status: queued error: summary: Error value: document_id: 04DE5AD98A02647D83285A36021911C6 status: error message: Source and target language are equal. 400: $ref: '#/components/responses/BadRequest' 403: $ref: '#/components/responses/Forbidden' 404: $ref: '#/components/responses/NotFound' 413: $ref: '#/components/responses/PayloadTooLarge' 429: $ref: '#/components/responses/TooManyRequests' 456: $ref: '#/components/responses/QuotaExceeded' 500: $ref: '#/components/responses/InternalServerError' 504: $ref: '#/components/responses/ServiceUnavailable' 529: $ref: '#/components/responses/TooManyRequests' security: - auth_header: [] /v2/document/{document_id}/result: post: tags: - TranslateDocuments summary: Download Translated Document operationId: downloadDocument description: |- 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. parameters: - $ref: '#/components/parameters/DocumentID' requestBody: required: true content: application/x-www-form-urlencoded: schema: $ref: '#/components/schemas/DocumentKey' examples: basic: summary: Basic value: document_key: 0CB0054F1C132C1625B392EADDA41CB754A742822F6877173029A6C487E7F60A application/json: schema: $ref: '#/components/schemas/DocumentKey' responses: 200: description: The document is provided as a download. There is no other data included in the response besides the document data. The content type used in the response corresponds to the document type. headers: X-Trace-ID: $ref: '#/components/headers/X-Trace-ID' content: application/octet-stream: schema: type: string format: binary examples: OK: summary: OK description: binary document data 400: $ref: '#/components/responses/BadRequest' 403: $ref: '#/components/responses/Forbidden' 404: $ref: '#/components/responses/NotFound404DocTransDownload' 413: $ref: '#/components/responses/PayloadTooLarge' 429: $ref: '#/components/responses/TooManyRequests' 456: $ref: '#/components/responses/QuotaExceeded' 500: $ref: '#/components/responses/InternalServerError' 503: $ref: '#/components/responses/ServiceUnavailable503DocTransDownload' 504: $ref: '#/components/responses/ServiceUnavailable' 529: $ref: '#/components/responses/TooManyRequests' security: - auth_header: [] /v2/glossary-language-pairs: get: tags: - ManageGlossaries summary: List Language Pairs Supported by Glossaries description: Retrieve the list of language pairs supported by the glossary feature. operationId: listGlossaryLanguages responses: 200: description: A JSON object containing the language pairs in its `supported_languages` property. headers: X-Trace-ID: $ref: '#/components/headers/X-Trace-ID' content: application/json: schema: type: object properties: supported_languages: type: array description: The list of supported languages items: type: object required: - source_lang - target_lang properties: source_lang: description: The language in which the source texts in the glossary are specified. type: string target_lang: description: The language in which the target texts in the glossary are specified. type: string example: supported_languages: - source_lang: de target_lang: en - source_lang: en target_lang: de 401: $ref: '#/components/responses/Unauthorized' 403: $ref: '#/components/responses/Forbidden' 429: $ref: '#/components/responses/TooManyRequests' 500: $ref: '#/components/responses/InternalServerError' 503: $ref: '#/components/responses/ServiceUnavailable' 529: $ref: '#/components/responses/TooManyRequests' security: - auth_header: [] /v3/glossaries: post: tags: - ManageMultilingualGlossaries summary: Create a Glossary operationId: createMultilingualGlossary requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CreateMultilingualGlossaryParameters' examples: Basic: value: 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 application/x-www-form-urlencoded: schema: $ref: '#/components/schemas/CreateMultilingualGlossaryParameters' responses: 201: description: The function for creating a glossary returns a JSON object containing the ID of the newly created glossary and a boolean flag that indicates if the created glossary can already be used in translate requests. headers: X-Trace-ID: $ref: '#/components/headers/X-Trace-ID' content: application/json: schema: $ref: '#/components/schemas/MultilingualGlossary' 400: $ref: '#/components/responses/BadRequestGlossaries' 401: $ref: '#/components/responses/Unauthorized' 403: $ref: '#/components/responses/Forbidden' 413: $ref: '#/components/responses/PayloadTooLarge' 429: $ref: '#/components/responses/TooManyRequests' 456: $ref: '#/components/responses/QuotaExceededGlossaries' 500: $ref: '#/components/responses/InternalServerError' 503: $ref: '#/components/responses/ServiceUnavailable' 529: $ref: '#/components/responses/TooManyRequests' security: - auth_header: [] get: tags: - ManageMultilingualGlossaries summary: List all Glossaries operationId: listMultilingualGlossaries description: List all glossaries and their meta-information, but not the glossary entries. responses: 200: description: JSON object containing a the glossaries. headers: X-Trace-ID: $ref: '#/components/headers/X-Trace-ID' content: application/json: schema: type: object properties: glossaries: type: array items: $ref: '#/components/schemas/MultilingualGlossary' example: 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: 2 creation_time: '2021-08-03T14:16:18.329Z' 401: $ref: '#/components/responses/Unauthorized' 403: $ref: '#/components/responses/Forbidden' 429: $ref: '#/components/responses/TooManyRequests' 500: $ref: '#/components/responses/InternalServerError' 503: $ref: '#/components/responses/ServiceUnavailable' 529: $ref: '#/components/responses/TooManyRequests' security: - auth_header: [] /v3/glossaries/{glossary_id}: get: tags: - ManageMultilingualGlossaries summary: Retrieve Glossary Details description: Retrieve meta information for a single glossary, omitting the glossary entries. operationId: getMultilingualGlossary parameters: - $ref: '#/components/parameters/GlossaryID' responses: 200: description: JSON object containing the glossary meta-information. headers: X-Trace-ID: $ref: '#/components/headers/X-Trace-ID' content: application/json: schema: $ref: '#/components/schemas/MultilingualGlossary' example: glossary_id: def3a26b-3e84-45b3-84ae-0c0aaf3525f7 name: My Glossary dictionaries: - source_lang: EN target_lang: DE creation_time: '2021-08-03T14:16:18.329Z' entry_count: 1 - source_lang: DE target_lang: EN creation_time: '2021-08-03T14:16:18.429Z' entry_count: 2 401: $ref: '#/components/responses/Unauthorized' 403: $ref: '#/components/responses/ForbiddenGlossaries' 404: $ref: '#/components/responses/NotFound' 429: $ref: '#/components/responses/TooManyRequests' 500: $ref: '#/components/responses/InternalServerError' 503: $ref: '#/components/responses/ServiceUnavailable' 529: $ref: '#/components/responses/TooManyRequests' security: - auth_header: [] patch: tags: - ManageMultilingualGlossaries summary: Edit glossary details description: Edit glossary details, such as name or a dictionary for a source and target language. operationId: patchMultilingualGlossary parameters: - $ref: '#/components/parameters/GlossaryID' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/PatchMultilingualGlossaryParameters' examples: Basic: value: name: My Glossary dictionaries: - source_lang: en target_lang: de entries: "Hello\tGuten Tag" entries_format: tsv application/x-www-form-urlencoded: schema: $ref: '#/components/schemas/PatchMultilingualGlossaryParameters' responses: 200: description: JSON object containing the glossary meta-information. headers: X-Trace-ID: $ref: '#/components/headers/X-Trace-ID' content: application/json: schema: $ref: '#/components/schemas/MultilingualGlossary' example: glossary_id: def3a26b-3e84-45b3-84ae-0c0aaf3525f7 name: My Glossary dictionaries: - source_lang: EN target_lang: DE creation_time: '2021-08-03T14:16:18.329Z' entry_count: 1 - source_lang: DE target_lang: EN creation_time: '2021-08-03T14:16:18.429Z' entry_count: 2 400: $ref: '#/components/responses/BadRequestGlossaries' 401: $ref: '#/components/responses/Unauthorized' 403: $ref: '#/components/responses/ForbiddenGlossaries' 404: $ref: '#/components/responses/NotFound' 413: $ref: '#/components/responses/PayloadTooLarge' 429: $ref: '#/components/responses/TooManyRequests' 456: $ref: '#/components/responses/QuotaExceededGlossaries' 500: $ref: '#/components/responses/InternalServerError' 503: $ref: '#/components/responses/ServiceUnavailable' 529: $ref: '#/components/responses/TooManyRequests' security: - auth_header: [] delete: tags: - ManageMultilingualGlossaries summary: Delete a Glossary description: Deletes the specified glossary. operationId: deleteMultilingualGlossary parameters: - $ref: '#/components/parameters/GlossaryID' responses: 204: description: Returns no content upon success. headers: X-Trace-ID: $ref: '#/components/headers/X-Trace-ID' 400: $ref: '#/components/responses/BadRequestGlossaries' 401: $ref: '#/components/responses/Unauthorized' 403: $ref: '#/components/responses/ForbiddenGlossaries' 404: $ref: '#/components/responses/NotFound' 429: $ref: '#/components/responses/TooManyRequests' 500: $ref: '#/components/responses/InternalServerError' 503: $ref: '#/components/responses/ServiceUnavailable' 529: $ref: '#/components/responses/TooManyRequests' security: - auth_header: [] /v3/glossaries/{glossary_id}/entries: get: tags: - ManageMultilingualGlossaries summary: Retrieve Glossary Entries operationId: getMultilingualGlossaryEntries description: List the entries of a single glossary in tsv format. parameters: - $ref: '#/components/parameters/GlossaryID' - name: source_lang in: query required: true schema: $ref: '#/components/schemas/GlossarySourceLanguage' - name: target_lang in: query required: true schema: $ref: '#/components/schemas/GlossaryTargetLanguage' responses: 200: description: The entries in tsv, wrapped in a JSON object. headers: X-Trace-ID: $ref: '#/components/headers/X-Trace-ID' content: application/json: schema: $ref: '#/components/schemas/GlossaryDictionary' 400: $ref: '#/components/responses/BadRequestGlossaries' 401: $ref: '#/components/responses/Unauthorized' 403: $ref: '#/components/responses/ForbiddenGlossaries' 404: $ref: '#/components/responses/NotFound' 429: $ref: '#/components/responses/TooManyRequests' 500: $ref: '#/components/responses/InternalServerError' 503: $ref: '#/components/responses/ServiceUnavailable' 529: $ref: '#/components/responses/TooManyRequests' security: - auth_header: [] /v3/glossaries/{glossary_id}/dictionaries: delete: tags: - ManageMultilingualGlossaries summary: Deletes the dictionary associated with the given language pair with the given glossary ID. operationId: deleteDictionary parameters: - $ref: '#/components/parameters/GlossaryID' - name: source_lang in: query required: true schema: $ref: '#/components/schemas/GlossarySourceLanguage' - name: target_lang in: query required: true schema: $ref: '#/components/schemas/GlossaryTargetLanguage' responses: 204: description: Returns no content upon success. headers: X-Trace-ID: $ref: '#/components/headers/X-Trace-ID' 400: $ref: '#/components/responses/BadRequestGlossaries' 401: $ref: '#/components/responses/Unauthorized' 403: $ref: '#/components/responses/ForbiddenGlossaries' 404: $ref: '#/components/responses/NotFound' 429: $ref: '#/components/responses/TooManyRequests' 500: $ref: '#/components/responses/InternalServerError' 503: $ref: '#/components/responses/ServiceUnavailable' 529: $ref: '#/components/responses/TooManyRequests' security: - auth_header: [] put: tags: - ManageMultilingualGlossaries summary: "Replaces or creates a dictionary in the glossary with the specified entries." operationId: replaceDictionary parameters: - $ref: '#/components/parameters/GlossaryID' requestBody: description: "The dictionary to insert into (or overwrite in) the multilingual glossary." content: application/json: schema: $ref: '#/components/schemas/MultilingualGlossaryEntries' application/x-www-form-urlencoded: schema: $ref: '#/components/schemas/PutMultilingualGlossaryParameters' responses: 200: description: JSON object containing the dictionary meta-information. headers: X-Trace-ID: $ref: '#/components/headers/X-Trace-ID' content: application/json: schema: $ref: '#/components/schemas/MultilingualGlossaryEntriesInformation' example: source_lang: EN target_lang: DE entry_count: 1 400: $ref: '#/components/responses/BadRequestGlossaries' 401: $ref: '#/components/responses/Unauthorized' 403: $ref: '#/components/responses/ForbiddenGlossaries' 404: $ref: '#/components/responses/NotFound' 413: $ref: '#/components/responses/PayloadTooLarge' 429: $ref: '#/components/responses/TooManyRequests' 456: $ref: '#/components/responses/QuotaExceededGlossaries' 500: $ref: '#/components/responses/InternalServerError' 503: $ref: '#/components/responses/ServiceUnavailable' 529: $ref: '#/components/responses/TooManyRequests' security: - auth_header: [] /v2/glossaries: post: tags: - ManageGlossaries summary: Create a Glossary operationId: createGlossary requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CreateGlossaryParameters' examples: Basic: value: name: My Glossary source_lang: en target_lang: de entries: "Hello\tGuten Tag" entries_format: tsv application/x-www-form-urlencoded: schema: $ref: '#/components/schemas/CreateGlossaryParameters' responses: 201: description: The function for creating a glossary returns a JSON object containing the ID of the newly created glossary and a boolean flag that indicates if the created glossary can already be used in translate requests. headers: X-Trace-ID: $ref: '#/components/headers/X-Trace-ID' content: application/json: schema: $ref: '#/components/schemas/MonolingualGlossary' 400: $ref: '#/components/responses/BadRequestGlossaries' 401: $ref: '#/components/responses/Unauthorized' 403: $ref: '#/components/responses/Forbidden' 413: $ref: '#/components/responses/PayloadTooLarge' 429: $ref: '#/components/responses/TooManyRequests' 456: $ref: '#/components/responses/QuotaExceededGlossaries' 500: $ref: '#/components/responses/InternalServerError' 503: $ref: '#/components/responses/ServiceUnavailable' 529: $ref: '#/components/responses/TooManyRequests' security: - auth_header: [] get: tags: - ManageGlossaries summary: List all Glossaries operationId: listGlossaries description: List all glossaries and their meta-information, but not the glossary entries. responses: 200: description: JSON object containing a the glossaries. headers: X-Trace-ID: $ref: '#/components/headers/X-Trace-ID' content: application/json: schema: type: object properties: glossaries: type: array items: $ref: '#/components/schemas/MonolingualGlossary' example: 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 401: $ref: '#/components/responses/Unauthorized' 403: $ref: '#/components/responses/Forbidden' 429: $ref: '#/components/responses/TooManyRequests' 500: $ref: '#/components/responses/InternalServerError' 503: $ref: '#/components/responses/ServiceUnavailable' 529: $ref: '#/components/responses/TooManyRequests' security: - auth_header: [] /v2/glossaries/{glossary_id}: get: tags: - ManageGlossaries summary: Retrieve Glossary Details description: Retrieve meta information for a single glossary, omitting the glossary entries. operationId: getGlossary parameters: - $ref: '#/components/parameters/GlossaryID' responses: 200: description: JSON object containing the glossary meta-information. headers: X-Trace-ID: $ref: '#/components/headers/X-Trace-ID' content: application/json: schema: $ref: '#/components/schemas/MonolingualGlossary' example: 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 400: $ref: '#/components/responses/BadRequestGlossaries' 401: $ref: '#/components/responses/Unauthorized' 403: $ref: '#/components/responses/ForbiddenGlossaries' 404: $ref: '#/components/responses/NotFound' 429: $ref: '#/components/responses/TooManyRequests' 500: $ref: '#/components/responses/InternalServerError' 503: $ref: '#/components/responses/ServiceUnavailable' 529: $ref: '#/components/responses/TooManyRequests' security: - auth_header: [] delete: tags: - ManageGlossaries summary: Delete a Glossary description: Deletes the specified glossary. operationId: deleteGlossary parameters: - $ref: '#/components/parameters/GlossaryID' responses: 204: description: Returns no content upon success. headers: X-Trace-ID: $ref: '#/components/headers/X-Trace-ID' 400: $ref: '#/components/responses/BadRequestGlossaries' 401: $ref: '#/components/responses/Unauthorized' 403: $ref: '#/components/responses/ForbiddenGlossaries' 404: $ref: '#/components/responses/NotFound' 429: $ref: '#/components/responses/TooManyRequests' 500: $ref: '#/components/responses/InternalServerError' 503: $ref: '#/components/responses/ServiceUnavailable' 529: $ref: '#/components/responses/TooManyRequests' security: - auth_header: [] /v2/glossaries/{glossary_id}/entries: get: tags: - ManageGlossaries summary: Retrieve Glossary Entries operationId: getGlossaryEntries description: List the entries of a single glossary in the format specified by the `Accept` header. parameters: - $ref: '#/components/parameters/GlossaryID' - name: Accept in: header schema: type: string enum: - text/tab-separated-values default: text/tab-separated-values description: The requested format of the returned glossary entries. Currently, supports only `text/tab-separated-values`. examples: tsv: summary: Tab-separated Values value: in: header Accept: text/tab-separated-values responses: 200: description: The entries in the requested format. headers: X-Trace-ID: $ref: '#/components/headers/X-Trace-ID' content: text/tab-separated-values: example: "Hello!\tGuten Tag!" 400: $ref: '#/components/responses/BadRequestGlossaries' 401: $ref: '#/components/responses/Unauthorized' 403: $ref: '#/components/responses/ForbiddenGlossaries' 404: $ref: '#/components/responses/NotFound' 415: $ref: '#/components/responses/UnsupportedMediaTypeGlossaries' 429: $ref: '#/components/responses/TooManyRequests' 500: $ref: '#/components/responses/InternalServerError' 503: $ref: '#/components/responses/ServiceUnavailable' 529: $ref: '#/components/responses/TooManyRequests' security: - auth_header: [] /v2/write/rephrase: post: tags: - RephraseText summary: Request text improvement operationId: rephraseText requestBody: required: true content: application/json: schema: type: object required: - text properties: text: description: Text to be improved. Only UTF-8-encoded plain text is supported. Improvements are returned in the same order as they are requested. type: array items: type: string example: this is a example sentence to imprve target_lang: $ref: '#/components/schemas/TargetLanguageWrite' writing_style: $ref: '#/components/schemas/WritingStyle' tone: $ref: '#/components/schemas/WritingTone' application/x-www-form-urlencoded: schema: type: object required: - text properties: text: description: Text to be improved. Only UTF-8-encoded plain text is supported. Improvements are returned in the same order as they are requested. type: array items: type: string example: this is a example sentence to imprve target_lang: $ref: '#/components/schemas/TargetLanguageWrite' writing_style: $ref: '#/components/schemas/WritingStyle' tone: $ref: '#/components/schemas/WritingTone' responses: 200: description: Successful text improvement. headers: X-Trace-ID: $ref: '#/components/headers/X-Trace-ID' content: application/json: schema: type: object properties: improvements: type: array minItems: 1 items: type: object properties: detected_source_language: description: The language detected in the source text. type: string example: en text: description: The improved text. type: string example: This is a sample sentence to improve. security: - auth_header: [] /v2/usage: get: tags: - MetaInformation summary: Check Usage and Limits description: |- Retrieve usage information within the current billing period together with the corresponding account limits. Usage is returned for: - translated characters - translated documents - translated documents, team totals (for team accounts only) Character usage includes both text and document translations, and is measured by the source text length in Unicode code points, so for example "A", "Δ", "あ", and "深" are each counted as a single character. Document usage only includes document translations, and is measured in individual documents. Depending on the user account type, some usage types will be omitted. Character usage is only included for developer accounts. Document usage is only included for non-developer accounts, and team-combined document usage is only included for non-developer team accounts. operationId: getUsage responses: 200: description: The account's usage and limits. headers: X-Trace-ID: $ref: '#/components/headers/X-Trace-ID' content: application/json: schema: $ref: '#/components/schemas/UsageResponse' examples: free: summary: Response for API users not on the Pro plan value: character_count: 180118 character_limit: 1250000 pro: summary: Response for API Pro users value: character_count: 5947223 character_limit: 1000000000000 products: - product_type: write billing_unit: characters api_key_unit_count: 0 account_unit_count: 5643 api_key_character_count: 0 character_count: 5643 - product_type: translate billing_unit: characters api_key_unit_count: 636 account_unit_count: 5941580 api_key_character_count: 636 character_count: 5941580 - product_type: speech_to_text billing_unit: milliseconds api_key_unit_count: 1800000 account_unit_count: 1800000 api_key_character_count: 0 character_count: 0 api_key_character_count: 636 api_key_character_limit: 1000000000000 speech_to_text_milliseconds_count: 1800000 speech_to_text_milliseconds_limit: 36000000 start_time: '2025-05-13T09:18:42Z' end_time: '2025-06-13T09:18:42Z' 400: $ref: '#/components/responses/BadRequest' 403: $ref: '#/components/responses/Forbidden' 404: $ref: '#/components/responses/NotFound' 413: $ref: '#/components/responses/PayloadTooLarge' 429: $ref: '#/components/responses/TooManyRequests' 456: $ref: '#/components/responses/QuotaExceeded' 500: $ref: '#/components/responses/InternalServerError' 504: $ref: '#/components/responses/ServiceUnavailable' 529: $ref: '#/components/responses/TooManyRequests' security: - auth_header: [] /v2/languages: get: tags: - MetaInformation summary: Retrieve Supported Languages description: |- Retrieve the list of languages that are currently supported for translation, either as source or target language, respectively. operationId: getLanguages parameters: - name: type in: query description: |- Sets whether source or target languages should be listed. Possible options are: * `source` (default): For languages that can be used in the `source_lang` parameter of [translate](https://www.deepl.com/docs-api/translate-text/translate-text) requests. * `target`: For languages that can be used in the `target_lang` parameter of [translate](https://www.deepl.com/docs-api/translate-text/translate-text) requests. schema: type: string enum: - source - target default: source examples: target: summary: Target Languages value: in: query type: target responses: 200: description: JSON array where each item represents a supported language. headers: X-Trace-ID: $ref: '#/components/headers/X-Trace-ID' content: application/json: schema: type: array items: type: object required: - language - name properties: language: description: The language code of the given language. type: string name: description: Name of the language in English. type: string supports_formality: description: Denotes formality support in case of a target language listing. type: boolean example: - 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: HE name: Hebrew supports_formality: false - 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: TH name: Thai supports_formality: false - language: TR name: Turkish supports_formality: false - language: UK name: Ukrainian supports_formality: false - language: VI name: Vietnamese 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 400: $ref: '#/components/responses/BadRequest' 403: $ref: '#/components/responses/Forbidden' 404: $ref: '#/components/responses/NotFound' 413: $ref: '#/components/responses/PayloadTooLarge' 429: $ref: '#/components/responses/TooManyRequests' 456: $ref: '#/components/responses/QuotaExceeded' 500: $ref: '#/components/responses/InternalServerError' 504: $ref: '#/components/responses/ServiceUnavailable' 529: $ref: '#/components/responses/TooManyRequests' security: - auth_header: [] /v2/admin/developer-keys: post: tags: - AdminApi summary: Create a developer key as an admin operationId: adminCreateDeveloperKey requestBody: required: true content: application/json: schema: type: object properties: label: $ref: '#/components/schemas/ApiKeyLabel' responses: 200: description: The create function returns a JSON representation of the created API key. headers: X-Trace-ID: $ref: '#/components/headers/X-Trace-ID' content: application/json: schema: $ref: '#/components/schemas/ApiKey' 400: $ref: '#/components/responses/BadRequest' 403: $ref: '#/components/responses/Forbidden' 404: $ref: '#/components/responses/NotFound' 500: $ref: '#/components/responses/InternalServerError' security: - auth_header: [ ] get: tags: - AdminApi summary: Get all developer keys as an admin operationId: adminGetDeveloperKeys responses: 200: description: The get function returns a JSON representation of all developer API keys in the organization. headers: X-Trace-ID: $ref: '#/components/headers/X-Trace-ID' content: application/json: schema: type: array items: $ref: '#/components/schemas/ApiKey' 400: $ref: '#/components/responses/BadRequest' 403: $ref: '#/components/responses/Forbidden' 404: $ref: '#/components/responses/NotFound' 500: $ref: '#/components/responses/InternalServerError' security: - auth_header: [ ] /v2/admin/developer-keys/deactivate: put: tags: - AdminApi summary: Deactivate a developer key as an admin operationId: adminDeactivateDeveloperKey requestBody: required: true content: application/json: schema: type: object required: - key_id properties: key_id: $ref: '#/components/schemas/ApiKeyId' responses: 200: description: The deactivate function returns a JSON representation of the deactivated API key. headers: X-Trace-ID: $ref: '#/components/headers/X-Trace-ID' content: application/json: schema: $ref: '#/components/schemas/ApiKey' 400: $ref: '#/components/responses/BadRequest' 403: $ref: '#/components/responses/Forbidden' 404: $ref: '#/components/responses/NotFound' 500: $ref: '#/components/responses/InternalServerError' security: - auth_header: [ ] /v2/admin/developer-keys/label: put: tags: - AdminApi summary: Rename a developer key as an admin operationId: adminRenameDeveloperKey requestBody: required: true content: application/json: schema: type: object required: - key_id - label properties: key_id: $ref: '#/components/schemas/ApiKeyId' label: type: string description: API key label. example: developer key prod responses: 200: description: The set label function returns a JSON representation of the renamed API key. headers: X-Trace-ID: $ref: '#/components/headers/X-Trace-ID' content: application/json: schema: $ref: '#/components/schemas/ApiKey' 400: $ref: '#/components/responses/BadRequest' 403: $ref: '#/components/responses/Forbidden' 404: $ref: '#/components/responses/NotFound' 500: $ref: '#/components/responses/InternalServerError' security: - auth_header: [ ] /v2/admin/developer-keys/limits: put: tags: - AdminApi summary: Set developer key usage limits as an admin operationId: adminSetDeveloperKeyUsageLimits requestBody: required: true content: application/json: schema: type: object required: - key_id properties: key_id: $ref: '#/components/schemas/ApiKeyId' characters: $ref: '#/components/schemas/ApiKeyUsageCharacters' speech_to_text_milliseconds: $ref: '#/components/schemas/ApiKeyUsageSpeechToTextMilliseconds' responses: 200: description: The set usage limits function returns a JSON representation of the modified API key. headers: X-Trace-ID: $ref: '#/components/headers/X-Trace-ID' content: application/json: schema: $ref: '#/components/schemas/ApiKey' 400: $ref: '#/components/responses/BadRequest' 403: $ref: '#/components/responses/Forbidden' 404: $ref: '#/components/responses/NotFound' 500: $ref: '#/components/responses/InternalServerError' security: - auth_header: [] /v2/admin/analytics: get: tags: - AdminApi summary: Get usage statistics as an admin operationId: adminGetAnalytics description: |- Retrieve usage statistics for the organization within a specified date range. Optionally group the results by API key or by API key and day. parameters: - name: start_date in: query required: true description: Start date for the usage report (ISO 8601 date format). schema: type: string format: date example: "2025-09-29" - name: end_date in: query required: true description: End date for the usage report (ISO 8601 date format). schema: type: string format: date example: "2025-10-01" - name: group_by in: query required: false description: |- Optional parameter to group usage statistics. Possible values: * `key` - Group by API key * `key_and_day` - Group by API key and usage date schema: type: string enum: - key - key_and_day example: "key_and_day" responses: 200: description: The usage statistics for the specified date range. headers: X-Trace-ID: $ref: '#/components/headers/X-Trace-ID' content: application/json: schema: $ref: '#/components/schemas/AdminUsageReport' examples: withGrouping: summary: Usage report grouped by key and day value: usage_report: total_usage: total_characters: 9619 text_translation_characters: 4892 document_translation_characters: 0 text_improvement_characters: 4727 speech_to_text_milliseconds: 1800000 group_by: "key_and_day" start_date: "2025-09-29T00:00:00" end_date: "2025-10-01T00:00:00" key_and_day_usages: - api_key: "dc88****3a2c" api_key_label: "Staging API Key" usage_date: "2025-09-29T00:00:00Z" usage: total_characters: 315 text_translation_characters: 159 document_translation_characters: 0 text_improvement_characters: 156 speech_to_text_milliseconds: 1800000 withoutGrouping: summary: Usage report without grouping value: usage_report: total_usage: total_characters: 9619 text_translation_characters: 4892 document_translation_characters: 0 text_improvement_characters: 4727 speech_to_text_milliseconds: 1800000 start_date: "2025-09-29T00:00:00" end_date: "2025-10-01T00:00:00" 400: description: Bad request. Please check error message and your parameters. headers: X-Trace-ID: $ref: '#/components/headers/X-Trace-ID' content: application/json: schema: type: object properties: message: type: string description: Error message describing the issue. examples: dateRangeExceeded: summary: Date range exceeds maximum allowed value: message: "Bad request. Reason: Date range cannot exceed 366 days" invalidGroupBy: summary: Invalid group_by parameter value value: message: "Value for 'group_by' not supported. Allowed: '', 'key', 'key_and_day'." 403: $ref: '#/components/responses/Forbidden' 404: $ref: '#/components/responses/NotFound' 500: $ref: '#/components/responses/InternalServerError' security: - auth_header: [ ] /v3/style_rules: get: tags: - StyleRules summary: Retrieve style rule lists operationId: getStyleRuleLists parameters: - name: page in: query schema: type: integer default: 0 description: The index of the first page to return. Use with `page_size` to get the next page of rule lists - name: page_size in: query schema: type: integer default: 10 minimum: 1 maximum: 25 description: The maximum number of style rule lists to return. - name: detailed in: query schema: type: boolean default: false description: Determines if the rule list's `configured_rules` and `custom_instructions` should be included in the response body. responses: 200: headers: X-Trace-ID: $ref: '#/components/headers/X-Trace-ID' content: application/json: schema: type: object properties: style_rules: type: array items: $ref: '#/components/schemas/StyleRuleList' 401: $ref: '#/components/responses/Unauthorized' 403: $ref: '#/components/responses/Forbidden' 429: $ref: '#/components/responses/TooManyRequests' 500: $ref: '#/components/responses/InternalServerError' 503: $ref: '#/components/responses/ServiceUnavailable' security: - auth_header: [] post: tags: - StyleRules summary: Create a style rule list operationId: createStyleRuleList requestBody: required: true content: application/json: schema: type: object required: - name - language properties: name: type: string description: Name of the style rule list example: "Technical Documentation Rules" language: $ref: '#/components/schemas/StyleRuleLanguage' configured_rules: $ref: '#/components/schemas/ConfiguredRules' custom_instructions: type: array description: List of custom instructions to enable for the style rule list items: $ref: '#/components/schemas/CustomInstructionRequest' maxItems: 200 responses: 201: description: Style rule list created successfully headers: X-Trace-ID: $ref: '#/components/headers/X-Trace-ID' content: application/json: schema: $ref: '#/components/schemas/StyleRuleList' 400: $ref: '#/components/responses/BadRequest' 401: $ref: '#/components/responses/Unauthorized' 403: $ref: '#/components/responses/Forbidden' 429: $ref: '#/components/responses/TooManyRequests' 456: $ref: '#/components/responses/QuotaExceeded' 500: $ref: '#/components/responses/InternalServerError' 503: $ref: '#/components/responses/ServiceUnavailable' security: - auth_header: [] /v3/style_rules/{style_id}: get: tags: - StyleRules summary: Retrieve a style rule list operationId: getStyleRuleList parameters: - name: style_id in: path required: true description: The unique ID of the style rule list schema: type: string example: "a74d88fb-ed2a-4943-a664-a4512398b994" responses: 200: description: Style rule list retrieved successfully headers: X-Trace-ID: $ref: '#/components/headers/X-Trace-ID' content: application/json: schema: $ref: '#/components/schemas/StyleRuleList' 401: $ref: '#/components/responses/Unauthorized' 403: $ref: '#/components/responses/Forbidden' 404: $ref: '#/components/responses/NotFound' 429: $ref: '#/components/responses/TooManyRequests' 500: $ref: '#/components/responses/InternalServerError' 503: $ref: '#/components/responses/ServiceUnavailable' security: - auth_header: [] patch: tags: - StyleRules summary: Update a style rule list operationId: updateStyleRuleList parameters: - name: style_id in: path required: true description: The unique ID of the style rule list schema: type: string example: "a74d88fb-ed2a-4943-a664-a4512398b994" requestBody: required: true content: application/json: schema: type: object properties: name: type: string description: Name of the style rule list example: "New Technical Documentation Rules" responses: 200: description: Style rule list updated successfully headers: X-Trace-ID: $ref: '#/components/headers/X-Trace-ID' content: application/json: schema: $ref: '#/components/schemas/StyleRuleList' 400: $ref: '#/components/responses/BadRequest' 401: $ref: '#/components/responses/Unauthorized' 403: $ref: '#/components/responses/Forbidden' 404: $ref: '#/components/responses/NotFound' 429: $ref: '#/components/responses/TooManyRequests' 456: $ref: '#/components/responses/QuotaExceeded' 500: $ref: '#/components/responses/InternalServerError' 503: $ref: '#/components/responses/ServiceUnavailable' security: - auth_header: [] delete: tags: - StyleRules summary: Delete a style rule list operationId: deleteStyleRuleList parameters: - name: style_id in: path required: true description: The unique ID of the style rule list schema: type: string example: "a74d88fb-ed2a-4943-a664-a4512398b994" responses: 204: description: Style rule list deleted successfully 401: $ref: '#/components/responses/Unauthorized' 403: $ref: '#/components/responses/Forbidden' 404: $ref: '#/components/responses/NotFound' 429: $ref: '#/components/responses/TooManyRequests' 500: $ref: '#/components/responses/InternalServerError' 503: $ref: '#/components/responses/ServiceUnavailable' security: - auth_header: [] /v3/style_rules/{style_id}/configured_rules: put: tags: - StyleRules summary: Update configured rules for a style rule list operationId: updateStyleRuleConfiguredRules parameters: - name: style_id in: path required: true description: The unique ID of the style rule list schema: type: string example: "a74d88fb-ed2a-4943-a664-a4512398b994" requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/ConfiguredRules' example: dates_and_times: calendar_era: "use_bc_and_ad" punctuation: periods_in_academic_degrees: "do_not_use" responses: 200: description: Configured rules updated successfully headers: X-Trace-ID: $ref: '#/components/headers/X-Trace-ID' content: application/json: schema: $ref: '#/components/schemas/StyleRuleList' 400: $ref: '#/components/responses/BadRequest' 401: $ref: '#/components/responses/Unauthorized' 403: $ref: '#/components/responses/Forbidden' 404: $ref: '#/components/responses/NotFound' 429: $ref: '#/components/responses/TooManyRequests' 500: $ref: '#/components/responses/InternalServerError' 503: $ref: '#/components/responses/ServiceUnavailable' security: - auth_header: [] /v3/style_rules/{style_id}/custom_instructions: post: tags: - StyleRules summary: Create a custom instruction operationId: createCustomInstruction parameters: - name: style_id in: path required: true description: The unique ID of the style rule list schema: type: string example: "a74d88fb-ed2a-4943-a664-a4512398b994" requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CustomInstructionRequest' responses: 201: description: Custom instruction created successfully headers: X-Trace-ID: $ref: '#/components/headers/X-Trace-ID' content: application/json: schema: $ref: '#/components/schemas/CustomInstruction' 400: $ref: '#/components/responses/BadRequest' 401: $ref: '#/components/responses/Unauthorized' 403: $ref: '#/components/responses/Forbidden' 404: $ref: '#/components/responses/NotFound' 429: $ref: '#/components/responses/TooManyRequests' 456: $ref: '#/components/responses/QuotaExceeded' 500: $ref: '#/components/responses/InternalServerError' 503: $ref: '#/components/responses/ServiceUnavailable' security: - auth_header: [] /v3/style_rules/{style_id}/custom_instructions/{instruction_id}: get: tags: - StyleRules summary: Retrieve a custom instruction operationId: getCustomInstruction parameters: - name: style_id in: path required: true description: The unique ID of the style rule list schema: type: string example: "a74d88fb-ed2a-4943-a664-a4512398b994" - name: instruction_id in: path required: true description: The unique ID of the custom instruction schema: type: string example: "f4515921-8fdf-4e3a-a981-ad7a6717a8aa" responses: 200: description: Custom instruction retrieved successfully headers: X-Trace-ID: $ref: '#/components/headers/X-Trace-ID' content: application/json: schema: $ref: '#/components/schemas/CustomInstruction' 401: $ref: '#/components/responses/Unauthorized' 403: $ref: '#/components/responses/Forbidden' 404: $ref: '#/components/responses/NotFound' 429: $ref: '#/components/responses/TooManyRequests' 500: $ref: '#/components/responses/InternalServerError' 503: $ref: '#/components/responses/ServiceUnavailable' security: - auth_header: [] put: tags: - StyleRules summary: Update a custom instruction operationId: updateCustomInstruction parameters: - name: style_id in: path required: true description: The unique ID of the style rule list schema: type: string example: "a74d88fb-ed2a-4943-a664-a4512398b994" - name: instruction_id in: path required: true description: The unique ID of the custom instruction schema: type: string example: "f4515921-8fdf-4e3a-a981-ad7a6717a8aa" requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CustomInstructionRequest' responses: 200: description: Custom instruction updated successfully headers: X-Trace-ID: $ref: '#/components/headers/X-Trace-ID' content: application/json: schema: $ref: '#/components/schemas/CustomInstruction' 400: $ref: '#/components/responses/BadRequest' 401: $ref: '#/components/responses/Unauthorized' 403: $ref: '#/components/responses/Forbidden' 404: $ref: '#/components/responses/NotFound' 429: $ref: '#/components/responses/TooManyRequests' 500: $ref: '#/components/responses/InternalServerError' 503: $ref: '#/components/responses/ServiceUnavailable' security: - auth_header: [] delete: tags: - StyleRules summary: Delete a custom instruction operationId: deleteCustomInstruction parameters: - name: style_id in: path required: true description: The unique ID of the style rule list schema: type: string example: "a74d88fb-ed2a-4943-a664-a4512398b994" - name: instruction_id in: path required: true description: The unique ID of the custom instruction schema: type: string example: "f4515921-8fdf-4e3a-a981-ad7a6717a8aa" responses: 204: description: Custom instruction deleted successfully 401: $ref: '#/components/responses/Unauthorized' 403: $ref: '#/components/responses/Forbidden' 404: $ref: '#/components/responses/NotFound' 429: $ref: '#/components/responses/TooManyRequests' 500: $ref: '#/components/responses/InternalServerError' 503: $ref: '#/components/responses/ServiceUnavailable' security: - auth_header: [] /v3/voice/realtime: post: tags: - VoiceAPI summary: Get Streaming URL operationId: getVoiceStreamingUrl requestBody: required: true content: application/json: schema: type: object required: - source_media_content_type properties: source_media_content_type: $ref: '#/components/schemas/VoiceMediaContentType' source_language: $ref: '#/components/schemas/VoiceSourceLanguage' source_language_mode: $ref: '#/components/schemas/VoiceSourceLanguageMode' target_languages: $ref: '#/components/schemas/VoiceTargetLanguages' glossary_id: $ref: '#/components/schemas/GlossaryId' formality: $ref: '#/components/schemas/VoiceFormality' examples: basic: summary: Basic configuration value: source_media_content_type: 'audio/ogg; codecs=opus' source_language: 'en' source_language_mode: 'auto' target_languages: ['de', 'fr', 'es'] with_glossary: summary: With glossary and formality value: source_media_content_type: 'audio/pcm; encoding=s16le; rate=16000' source_language: 'en' source_language_mode: 'fixed' target_languages: ['de', 'fr'] glossary_id: 'def3a26b-3e84-45b3-84ae-0c0aaf3525f7' formality: 'formal' responses: 200: description: Successfully obtained streaming URL and token headers: X-Trace-ID: $ref: '#/components/headers/X-Trace-ID' content: application/json: schema: $ref: '#/components/schemas/VoiceStreamingResponse' example: streaming_url: 'wss://api.deepl.com/v3/voice/realtime/connect' token: 'VGhpcyBpcyBhIGZha2UgdG9rZW4K' 400: $ref: '#/components/responses/BadRequest' 401: $ref: '#/components/responses/Unauthorized' 403: $ref: '#/components/responses/Forbidden' 429: $ref: '#/components/responses/TooManyRequests' 456: $ref: '#/components/responses/QuotaExceeded' 500: $ref: '#/components/responses/InternalServerError' 503: $ref: '#/components/responses/ServiceUnavailable' security: - auth_header: [] get: tags: - VoiceAPI summary: Request Reconnection operationId: requestReconnection parameters: - name: token in: query required: true description: The latest ephemeral token obtained for the stream. schema: type: string example: 'VGhpcyBpcyBhIGZha2UgdG9rZW4K' responses: 200: description: Successfully obtained streaming URL and reconnection token. headers: X-Trace-ID: $ref: '#/components/headers/X-Trace-ID' content: application/json: schema: $ref: '#/components/schemas/VoiceStreamingResponse' example: streaming_url: 'wss://api.deepl.com/v3/voice/realtime/connect' token: 'VGhpcyBpcyBhIGZha2UgdG9rZW4K' session_id: '4f911080-cfe2-41d4-8269-0e6ec15a0354' 400: $ref: '#/components/responses/BadRequest' 401: $ref: '#/components/responses/Unauthorized' 403: $ref: '#/components/responses/Forbidden' 429: $ref: '#/components/responses/TooManyRequests' 456: $ref: '#/components/responses/QuotaExceeded' 500: $ref: '#/components/responses/InternalServerError' 503: $ref: '#/components/responses/ServiceUnavailable' security: - auth_header: [] components: parameters: DocumentID: name: document_id description: The document ID that was sent to the client when the document was uploaded to the API. in: path required: true schema: type: string example: 04DE5AD98A02647D83285A36021911C6 GlossaryID: name: glossary_id description: A unique ID assigned to the glossary. in: path required: true schema: type: string SourceLanguage: name: source_lang in: query schema: $ref: '#/components/schemas/SourceLanguage' TargetLanguage: name: target_lang in: query required: true schema: $ref: '#/components/schemas/TargetLanguage' headers: X-Trace-ID: description: A unique identifier for the request that can be included in bug reports to DeepL support. schema: type: string example: 501c3d93cc0c4f11ae2f60a226c2f0f0 responses: BadRequest: description: Bad request. Please check error message and your parameters. headers: X-Trace-ID: $ref: '#/components/headers/X-Trace-ID' BadRequestGlossaries: description: Bad request. Please check error message and your parameters. headers: X-Trace-ID: $ref: '#/components/headers/X-Trace-ID' content: application/json: schema: type: object properties: message: description: Generic description of the error. type: string detail: description: More specific description of the error. type: string example: message: Invalid glossary entries provided detail: Key with the index 1 (starting at position 13) duplicates key with the index 0 (starting at position 0) Unauthorized: description: Authorization failed. Please supply a valid `DeepL-Auth-Key` via the `Authorization` header. headers: X-Trace-ID: $ref: '#/components/headers/X-Trace-ID' Forbidden: description: Authorization failed. Please supply a valid `DeepL-Auth-Key` via the `Authorization` header. headers: X-Trace-ID: $ref: '#/components/headers/X-Trace-ID' ForbiddenGlossaries: description: Forbidden. The access to the requested resource is denied, because of insufficient access rights. headers: X-Trace-ID: $ref: '#/components/headers/X-Trace-ID' NotFound: description: The requested resource could not be found. headers: X-Trace-ID: $ref: '#/components/headers/X-Trace-ID' NotFound404DocTransDownload: description: Trying to download a document using a non-existing document ID or the wrong document key will result in a 404 error. As stated above, documents can only be downloaded once before they are deleted from the server and their document ID is invalidated. headers: X-Trace-ID: $ref: '#/components/headers/X-Trace-ID' content: application/json: schema: $ref: '#/components/schemas/DocumentTranslationError' examples: NotFound: summary: Not Found value: message: Document not found PayloadTooLarge: description: The request size exceeds the limit. headers: X-Trace-ID: $ref: '#/components/headers/X-Trace-ID' URITooLong: description: The request URL is too long. You can avoid this error by using a POST request instead of a GET request, and sending the parameters in the HTTP body. headers: X-Trace-ID: $ref: '#/components/headers/X-Trace-ID' UnsupportedMediaTypeGlossaries: description: The requested entries format specified in the `Accept` header is not supported. headers: X-Trace-ID: $ref: '#/components/headers/X-Trace-ID' TooManyRequests: description: Too many requests. Please wait and resend your request. headers: X-Trace-ID: $ref: '#/components/headers/X-Trace-ID' QuotaExceeded: description: Quota exceeded. The character limit has been reached. headers: X-Trace-ID: $ref: '#/components/headers/X-Trace-ID' QuotaExceededGlossaries: description: Quota exceeded. The glossary creation limit has been reached. headers: X-Trace-ID: $ref: '#/components/headers/X-Trace-ID' InternalServerError: description: Internal error. headers: X-Trace-ID: $ref: '#/components/headers/X-Trace-ID' ServiceUnavailable: description: Resource currently unavailable. Try again later. headers: X-Trace-ID: $ref: '#/components/headers/X-Trace-ID' ServiceUnavailable503DocTransDownload: description: |- A 503 result will be returned if the user tries to download a translated document that is currently being processed and is not yet ready for download. Please make sure to check that the document status is 'done' before trying to send a download request. headers: X-Trace-ID: $ref: '#/components/headers/X-Trace-ID' content: application/json: schema: $ref: '#/components/schemas/DocumentTranslationError' examples: AlreadyDownloaded: summary: Already Downloaded value: message: Document already downloaded securitySchemes: auth_header: type: apiKey description: Authentication with `Authorization` header and `DeepL-Auth-Key` authentication scheme name: Authorization in: header schemas: ApiKeyId: description: API key ID. Consists of two valid GUIDs separated by a colon. type: string example: ca7d5694-96eb-4263-a9a4-7f7e4211529e:20c2abcf-4c3c-4cd6-8ae8-8bd2a7d4da38 ApiKeyLabel: description: API key label. The default value is `DeepL API Key`. type: string example: "developer key prod" ApiKeyUsageCharacters: description: | Restricts 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. 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. type: number example: 5000 ApiKeyUsageSpeechToTextMilliseconds: description: | Restricts the number of milliseconds of speech-to-text that can be consumed by an API key in a one-month usage period. Setting the limit to `0` means the API key will not be able to consume speech-to-text milliseconds. Setting the limit to `null` disables the limit, effectively allowing unlimited usage. type: number example: 3600000 ApiKey: description: The API key. type: object properties: key_id: $ref: '#/components/schemas/ApiKeyId' label: $ref: '#/components/schemas/ApiKeyLabel' creation_time: description: Timestamp when the key was created (ISO 8601 format) type: string example: "2025-07-08T08:15:29.362Z" deactivated_time: description: Timestamp when the key was deactivated (ISO 8601 format). The default value is `null`. type: string example: "2025-07-09T08:15:29.362Z" is_deactivated: description: Flag indicating whether the API key is deactivated. The default value is `false`. type: boolean example: true usage_limits: description: Usage limits for the API key. type: object properties: characters: $ref: '#/components/schemas/ApiKeyUsageCharacters' speech_to_text_milliseconds: $ref: '#/components/schemas/ApiKeyUsageSpeechToTextMilliseconds' ConfiguredRules: description: The enabled rules for the style rule list including what option was selected for each rule. This schema combines rules from all supported languages. type: object properties: dates_and_times: type: object properties: calendar_era: type: string description: Formatting options for Calendar Era enum: - use_bc_and_ad - use_bce_and_ce centuries: type: string description: Formatting options for Centuries enum: - spell_out - use_arabic_numerals - use_numerals - use_roman_numerals date_format: type: string description: Formatting options for Date Format enum: - use_dd_period_mm_period_yy_with_leading_zeros_for_single_digit_days_and_months - use_dd_period_mm_period_yyyy - use_dd_period_mm_period_yyyy_with_leading_zeros_for_single_digit_days_and_months - use_dd_period_space_abbreviated_month_yyyy_with_abbreviations_jan_period_feb_period_mrz_period_apr_period_mai_jun_period_jul_period_aug_period_sep_period_okt_period_nov_period_dez_period_without_leading_zeros_for_single_digit_days - use_dd_period_space_abbreviated_month_yyyy_with_abbreviations_jan_period_febr_period_maerz_apr_period_mai_juni_juli_aug_period_sept_period_okt_period_nov_period_dez_period_without_leading_zeros_for_single_digit_days - use_dd_period_space_month_yyyy_without_leading_zeros_for_single_digit_days - use_dd_slash_mm_slash_yyyy - use_dd_slash_mm_slash_yyyy_with_leading_zeros_for_single_digit_days_and_months - use_dd_space_spelled_out_month_space_yyyy - use_dd_space_spelled_out_month_space_yyyy_and_use_spanish_word_septiembre_for_ninth_month - use_dd_space_spelled_out_month_space_yyyy_and_use_spanish_word_setiembre_for_ninth_month - use_dd_space_spelled_out_month_space_yyyy_without_leading_zeros_for_single_digit_days - use_historical_eras_and_write_numbers_in_chinese_followed_by_chinese_word_公元前_or_公元后_with_arabic_numerals_in_parentheses - use_mm_slash_dd_slash_yyyy_with_leading_zeros_for_single_digit_days_and_months - use_numerals_only_with_leading_zero_for_single_digits - use_numerals_only_without_leading_zero_for_single_digits - use_spelled_out_month_space_dd_comma_space_yyyy_and_use_spanish_word_septiembre_for_ninth_month - use_spelled_out_month_space_dd_comma_space_yyyy_without_leading_zeros_for_single_digit_days - use_traditional_calendar_system_with_chinese_numbers - use_yyyy_chinese_word_年_mm_chinese_word_月_dd_chinese_word_日_with_chinese_numbers - use_yyyy_chinese_word_年_mm_chinese_word_月_dd_chinese_word_日_without_leading_zero_for_single_digit_months_and_days - use_yyyy_hyphen_mm_hyphen_dd_with_leading_zero_for_single_digit_days_and_months - use_yyyy_hyphen_mm_hyphen_dd_with_leading_zeros_for_single_digit_days_and_months - use_yyyy_korean word_년_space_mm_korean word_월_space_dd_korean word_일_without_leading_zero_for_single_digit_days_and_months - use_yyyy_period_mm_period_dd - use_yyyy_period_space_mm_period_space_dd_period_space_without_leading_zero_for_single_digit_days_and_months - use_yyyy_slash_mm_slash_dd - use_yyyy_slash_mm_slash_dd_with_leading_zero_for_single_digit_days_and_months dates_in_numerical_form: type: string description: Formatting options for Dates In Numerical Form enum: - use_dd_hyphen_mm_hyphen_yyyy - use_dd_period_mm_period_yyyy - use_dd_slash_mm_slash_yyyy decades: type: string description: Formatting options for Decades enum: - spell_out - use_apostrophe_yy - use_yy_for_20th_century_but_yyyy_for_other_centuries - use_yy_without_apostrophe - use_yyyy hours_minutes_seconds_separator: type: string description: Formatting options for Hours Minutes Seconds Separator enum: - use_colon - use_period hours_minutes_separator: type: string description: Formatting options for Hours Minutes Separator enum: - use_colon_without_spaces - use_letter_h_with_regular_space_on_either_side - use_letter_h_without_spaces midnight_in_numerals: type: string description: Formatting options for Midnight In Numerals enum: - use_00_00 - use_24_00 single_digit_days_and_months: type: string description: Formatting options for Single Digit Days And Months enum: - do_not_use_leading_zero - use_leading_zero single_digit_hours: type: string description: Formatting options for Single Digit Hours enum: - do_not_use_leading_zero - use_leading_zero time_format: type: string description: Formatting options for Time Format enum: - spell_out_time_in_words - use_12_hour_clock_and_do_not_specify_morning_or_evening - use_12_hour_clock_and_lowercase_am_or_pm_with_periods - use_12_hour_clock_and_lowercase_am_or_pm_with_periods_except_use_noon_and_midnight_instead_of_12_am_and_12_pm - use_12_hour_clock_and_lowercase_am_or_pm_without_periods - use_12_hour_clock_and_lowercase_am_or_pm_without_periods_except_use_noon_and_midnight_instead_of_12_am_and_12_pm - use_12_hour_clock_and_specify_morning_or_evening - use_12_hour_clock_and_uppercase_am_or_pm_with_periods - use_12_hour_clock_and_uppercase_am_or_pm_with_periods_except_use_noon_and_midnight_instead_of_12_am_and_12_pm - use_12_hour_clock_and_uppercase_am_or_pm_without_periods - use_12_hour_clock_and_uppercase_am_or_pm_without_periods_except_use_noon_and_midnight_instead_of_12_am_and_12_pm - use_12_hour_clock_and_write_chinese_word_上午_or_下午_or_chinese_word_早上_or_晚上_followed_by_arabic_numerals - use_12_hour_clock_and_write_chinese_word_上午_or_下午_or_chinese_word_早上_or_晚上_followed_by_arabic_numerals_with_chinese_word_点_for_hours - use_12_hour_clock_and_write_chinese_word_上午_or_下午_or_chinese_word_早上_or_晚上_followed_by_arabic_numerals_with_chinese_words_时_and_分_for_hours_and_minutes - use_12_hour_clock_and_write_chinese_word_上午_or_下午_or_chinese_word_早上_or_晚上_followed_by_chinese_numbers_with_chinese_words_时_and_分_for_hours_and_minutes - use_12_hour_clock_with_arabic_numerals_and_colon - use_12_hour_clock_with_korean_words_시_and_분 - use_12_hour_clock_without_leading_zero_or_minutes_for_full_hours_use_colon_as_separator_and_lowercase_am_or_pm_without_periods - use_12_hour_clock_without_leading_zero_or_minutes_for_full_hours_use_colon_as_separator_and_uppercase_am_or_pm_without_periods - use_12_hour_clock_without_leading_zero_use_period_as_separator_and_lowercase_am_or_pm_with_periods_and_spaces - use_24_hour_clock - use_24_hour_clock_with_arabic_numerals_and_colon - use_24_hour_clock_with_colon_as_separator - use_24_hour_clock_with_korean_words_시_and_분 - use_24_hour_clock_with_period_as_separator - use_hh_colon_mm_german_word_uhr_with_leading_zeros_for_single_digit_hours - use_hh_colon_mm_german_word_uhr_without_leading_zeros_for_single_digit_hours - use_hh_period_mm_german_word_uhr_with_leading_zeros_for_single_digit_hours - use_hh_period_mm_german_word_uhr_without_leading_zeros_for_single_digit_hours - use_hh_period_mm_german_word_uhr_without_leading_zeros_for_single_digit_hours_and_for_full_hours_state_hour_only writing_dates: type: string description: Formatting options for Writing Dates enum: - use_dd_space_spelled_out_month_space_yyyy - use_numerals years: type: string description: Formatting options for Years enum: - use_apostrophe_yy - use_common_era - use_japanese_imperial_era - use_yyyy formatting: type: object properties: email_address_format: type: string description: Formatting options for Email Address Format enum: - place_domain_in_parentheses - replace_at_symbol_with_english_word_at_in_brackets_and_replace_periods_with_english_word_dot_in_brackets - replace_at_symbol_with_english_word_at_in_brackets_with_space_on_either_side - replace_at_symbol_with_english_word_at_in_parentheses_with_space_on_either_side - replace_at_symbol_with_english_word_at_with_space_on_either_side - use_standard_format phone_number_country_code_format: type: string description: Formatting options for Phone Number Country Code Format enum: - use_00_before_country_code - use_plus_sign_before_country_code phone_number_format: type: string description: Formatting options for Phone Number Format enum: - do_not_use_spaces - do_not_use_spaces_or_special_characters_between_digits_of_phone_number - keep_original_format - place_area_code_in_parentheses_followed_by_space - separate_area_code_and_phone_number_with_slash - separate_area_code_and_phone_number_with_space - separate_country_code_area_code_local_prefix_and_last_four_digits_with_hyphens - separate_country_code_area_code_local_prefix_and_last_four_digits_with_periods - separate_country_code_area_code_local_prefix_and_last_four_digits_with_spaces - use_north_american_numbering_plan_format - use_space_after_country_code space_between_arabic_numerals_and_unit: type: string description: Formatting options for Space Between Arabic Numerals And Unit enum: - do_not_use space_between_chinese_and_english: type: string description: Formatting options for Space Between Chinese And English enum: - do_not_use space_between_chinese_characters_and_arabic_numerals: type: string description: Formatting options for Space Between Chinese Characters And Arabic Numerals enum: - do_not_use numbers: type: object properties: approximate_numbers: type: string description: Formatting options for Approximate Numbers enum: - use_kanji_numbers currency_format: type: string description: Formatting options for Currency Format enum: - spell_out - spell_out_currency_name_followed_by_amount_in_arabic_numerals_without_space - spell_out_currency_name_followed_by_amount_in_chinese - use_amount_followed_by_currency_symbol_without_space - use_amount_followed_by_space_then_currency_symbol - use_amount_followed_by_space_then_iso_code - use_amount_followed_by_space_then_spell_out_currency_name - use_amount_followed_by_space_then_spell_out_currency_name_in_lowercase - use_amount_followed_by_spelled_out_currency_name_in_japanese_without_space - use_amount_followed_by_spelled_out_currency_name_without_space - use_currency_symbol_but_spell_out_if_no_symbol_exists - use_currency_symbol_but_use_iso_code_if_no_symbol_exists - use_currency_symbol_followed_by_amount_in_arabic_numerals_without_space - use_currency_symbol_followed_by_amount_without_space - use_currency_symbol_followed_by_space_then_amount - use_currency_symbol_followed_by_space_then_amount_in_arabic_numerals - use_full_width_currency_symbol_followed_by_amount_without_space - use_half_width_currency_symbol_followed_by_amount_without_space - use_half_width_currency_symbol_followed_by_space_then_amount - use_iso_code - use_iso_code_followed_by_space_then_amount - use_iso_code_followed_by_space_then_amount_in_arabic_numerals decimal_numbers_less_than_one: type: string description: Formatting options for Decimal Numbers Less Than One enum: - always_use_0_before_decimal_separator decimal_separator: type: string description: Formatting options for Decimal Separator enum: - use_comma_and_do_not_use_thousands_separator - use_comma_as_decimal_separator - use_comma_do_not_use_thousands_separator_and_use_period_only_for_radio_stations - use_period_and_do_not_use_thousands_separator - use_period_as_decimal_separator dimensions_separator: type: string description: Formatting options for Dimensions Separator enum: - use_multiplication_sign_between_dimensions_with_space_on_either_side - use_multiplication_sign_between_dimensions_without_space_on_either_side - use_x_between_dimensions_with_space_on_either_side - use_x_between_dimensions_without_space_on_either_side equation_formula_reference: type: string description: Formatting options for Equation Formula Reference enum: - always_use_arabic_numerals_to_number_equations_or_formulas_referenced_in_text kanji_numbers: type: string description: Formatting options for Kanji Numbers enum: - use_kanji_numbers_for_numbers_in_phrases_and_counting_method_based_on_native_japanese_readings large_number_format: type: string description: Formatting options for Large Number Format enum: - always_use_arabic_numerals - spell_out_large_numbers - use_abbreviations_for_large_numbers - use_chinese_characters_for_ten_thousands_and_hundred_millions - use_comma_to_separate_large_numbers_into_units_of_three_except_for_calendar_years - use_kanji_for_trillions_hundred_millions_and_ten_thousands - use_korean_words_만_억_조_with_space - use_korean_words_만_억_조_without_space large_sums_of_money: type: string description: Formatting options for Large Sums Of Money enum: - spell_out_italian_words_milione_and_miliardo - use_italian_words_mio_and_mrd_instead_of_italian_words_milione_and_miliardo large_sums_of_money_format: type: string description: Formatting options for Large Sums Of Money Format enum: - use_amount_followed_by_abbreviation_for_million_or_billion_without_space - use_amount_followed_by_space_then_abbreviation_for_million_or_billion - use_amount_followed_by_space_then_english_word_million_or_billion list_of_measurements_with_units: type: string description: Formatting options for List Of Measurements With Units enum: - repeat_unit_for_each_measurement_in_list mathematical_expression_spacing: type: string description: Formatting options for Mathematical Expression Spacing enum: - use_space_between_elements_of_mathematical_expression_or_equation number_format: type: string description: Formatting options for Number Format enum: - use_half_width_comma_to_separate_large_numbers_into_units_of_three_except_for_calendar_years_and_use_half_width_period_as_decimal_separator number_separator: type: string description: Formatting options for Number Separator enum: - do_not_use_chinese_comma_to_separate_numbers_indicating_approximate_value - use_chinese_comma_to_separate_numbers_in_abbreviations numbers_of_5_digits_or_more: type: string description: Formatting options for Numbers Of 5 Digits Or More enum: - use_comma_as_decimal_separator_and_period_as_thousands_separator - use_comma_as_decimal_separator_and_space_as_thousands_separator - use_comma_as_decimal_separator_period_as_thousands_separator_and_period_for_radio_stations - use_comma_as_decimal_separator_space_as_thousands_separator_and_period_for_radio_stations - use_period_as_decimal_separator_and_comma_as_thousands_separator - use_period_as_decimal_separator_and_space_as_thousands_separator numbers_up_to_4_digits: type: string description: Formatting options for Numbers Up To 4 Digits enum: - use_comma_as_decimal_separator_and_period_as_thousands_separator - use_comma_as_decimal_separator_and_space_as_thousands_separator - use_comma_as_decimal_separator_period_as_thousands_separator_and_period_for_radio_stations - use_comma_as_decimal_separator_space_as_thousands_separator_and_period_for_radio_stations - use_period_as_decimal_separator_and_comma_as_thousands_separator - use_period_as_decimal_separator_and_space_as_thousands_separator percentage_format: type: string description: Formatting options for Percentage Format enum: - use_arabic_numerals_followed_by_percent_symbol_without_space - use_chinese_numbers_followed_by_chinese_word_百分之 - use_numerals_followed_by_full_width_percent_symbol_without_space - use_numerals_followed_by_japanese_word_パーセント_without_space - use_numerals_followed_by_korean_word_퍼센트 - use_numerals_followed_by_percent_symbol - use_numerals_followed_by_space_then_german_word_prozent - use_numerals_followed_by_space_then_half_width_percent_symbol - use_numerals_followed_by_space_then_italian_word_per_cento - use_numerals_followed_by_space_then_italian_word_percento - use_numerals_followed_by_space_then_korean_word_퍼센트 - use_numerals_followed_by_space_then_percent_symbol - use_numerals_followed_by_space_then_spell_out_per_cent - use_numerals_followed_by_space_then_spell_out_percent - use_spanish_word_por_cien - use_spanish_word_por_ciento reference_to_symbol: type: string description: Formatting options for Reference To Symbol enum: - spell_out_symbol_name_followed_by_symbol_in_parentheses spelling_out_units: type: string description: Formatting options for Spelling Out Units enum: - abbreviate_units_of_measure_when_used_with_numeral_but_spell_out_when_used_without_numeral - always_abbreviate_units_of_measure - always_spell_out_units_of_measure - spell_out_units_in_korean - spell_out_units_of_measure_when_used_with_spelled_out_numbers_but_abbreviate_when_used_with_numeral - spell_out_units_of_measure_with_katakana_or_katakana_and_kanji - use_si_symbols - use_unit_symbols temperature_format: type: string description: Formatting options for Temperature Format enum: - spell_out_unit - spell_out_unit_followed_by_numerals_then_korean_word_도 - use_arabic_numerals_followed_by_space_then_spell_out_unit - use_arabic_numerals_followed_by_unit_symbol_without_space - use_arabic_numerals_then_spell_out_unit - use_chinese_numbers_then_spell_out_unit - use_italian_word_grado_and_do_not_specify_temperature_scale - use_numerals_followed_by_japanese_word_度_without_space - use_numerals_followed_by_korean_word_도 - use_numerals_followed_by_space_then_spell_out_unit - use_numerals_followed_by_space_then_unit_symbol - use_numerals_followed_by_unit_symbol_without_space - use_spanish_word_grado_and_do_not_specify_temperature_scale thousands_separator: type: string description: Formatting options for Thousands Separator enum: - do_not_use - do_not_use_thousands_separator - use_comma - use_comma_to_separate_large_numbers_into_units_of_three - use_period - use_period_as_thousands_separator - use_space - use_space_as_thousands_separator - use_space_to_separate_large_numbers_into_units_of_three - use_straight_apostrophe_as_thousands_separator units_of_measure_spacing: type: string description: Formatting options for Units Of Measure Spacing enum: - do_not_use_space_between_numeral_and_unit_of_measure - use_space_between_numeral_and_unit_of_measure use_of_hiragana_and_kanji: type: string description: Formatting options for Use Of Hiragana And Kanji enum: - use_hiragana_japanese_word_か所_or_か月_when_using_arabic_numerals_in_horizontal_writing_but_use_kanji_japanese_word_箇所_or_箇月_when_using_kanji_numbers writing_numbers: type: string description: Formatting options for Writing Numbers enum: - always_use_kanji_numbers - use_arabic_numerals - use_full_width_arabic_numerals_and_only_use_kanji_numbers_where_it_would_otherwise_sound_unnatural - use_half_width_arabic_numerals_and_only_use_kanji_numbers_where_it_would_otherwise_sound_unnatural zero_format: type: string description: Formatting options for Zero Format enum: - use_chinese_word_〇_for_numbering - use_chinese_word_零_for_measurement punctuation: type: object properties: abbreviations: type: string description: Formatting options for Abbreviations enum: - do_not_separate_abbreviated_words - separate_each_abbreviated_word_with_period_and_space - separate_each_abbreviated_word_with_period_without_space - separate_each_abbreviated_word_with_space_without_period acronyms: type: string description: Formatting options for Acronyms enum: - do_not_use_periods ampersand_abbreviation_spacing: type: string description: Formatting options for Ampersand Abbreviation Spacing enum: - do_not_use_spaces_before_and_after_ampersand_as_part_of_abbreviation - use_spaces_before_and_after_ampersand_as_part_of_abbreviation ampersand_usage: type: string description: Formatting options for Ampersand Usage enum: - use_english_word_and_except_in_company_names_common_abbreviations_titles_software_code_and_mathematical_equations - use_full_width_ampersand - use_german_word_und_except_in_company_names_common_abbreviations_titles_software_code_and_mathematical_equations - use_half_width_ampersand apostrophe: type: string description: Formatting options for Apostrophe enum: - use_curly_apostrophes - use_straight_apostrophes bracket: type: string description: Formatting options for Bracket enum: - use_hexagonal_brackets - use_lenticular_brackets - use_parentheses - use_square_brackets_for_nationality_and_hexagonal_brackets_for_historical_period chinese_mixed_with_english: type: string description: Formatting options for Chinese Mixed With English enum: - do_not_place_english_in_quotation_marks - place_english_in_quotation_marks colon: type: string description: Formatting options for Colon enum: - use_full_width_colon - use_half_width_colon colon_between_hours_and_minutes_or_chapters_and_verses: type: string description: Formatting options for Colon Between Hours And Minutes Or Chapters And Verses enum: - do_not_use_space_before_or_after_colon colon_in_heading: type: string description: Formatting options for Colon In Heading enum: - use_space_after_colon_not_before colon_to_replace_versus_or_to: type: string description: Formatting options for Colon To Replace Versus Or To enum: - do_not_use_space_before_or_after_colon comma_after_conjunctive_adverbs: type: string description: Formatting options for Comma After Conjunctive Adverbs enum: - do_not_use - use comma_after_i_e_and_e_g: type: string description: Formatting options for Comma After I E And E G enum: - do_not_use - use comma_after_short_introductory_phrase: type: string description: Formatting options for Comma After Short Introductory Phrase enum: - do_not_use - use comma_and_semicolon: type: string description: Formatting options for Comma And Semicolon enum: - use_comma_between_clauses - use_semicolon_between_clauses corner_bracket_and_periods: type: string description: Formatting options for Corner Bracket And Periods enum: - add_period_after_closing_corner_bracket_at_end_of_sentence corner_brackets_and_periods: type: string description: Formatting options for Corner Brackets And Periods enum: - do_not_add_period_before_closing_corner_bracket_when_sentence_continues dash: type: string description: Formatting options for Dash enum: - use_em_dash - use_hyphen - use_tilde ellipsis: type: string description: Formatting options for Ellipsis enum: - use_ellipsis_character - use_one_ellipsis_character - use_six_dots_at_the_bottom - use_six_dots_in_the_center - use_three_dots_at_the_bottom - use_three_dots_in_the_center - use_three_ellipsis_characters - use_three_periods - use_three_periods_without_spaces - use_three_spaced_periods - use_two_ellipsis_characters em_dash: type: string description: Formatting options for Em Dash enum: - use_double_em_dash emphasis: type: string description: Formatting options for Emphasis enum: - use_double_corner_brackets exclamation_marks: type: string description: Formatting options for Exclamation Marks enum: - do_not_use explanatory_note_indicator: type: string description: Formatting options for Explanatory Note Indicator enum: - use_double_em_dash - use_parentheses full_sentence_in_round_brackets: type: string description: Formatting options for Full Sentence In Round Brackets enum: - add_period_before_closing_round_bracket highlighting_specific_expressions: type: string description: Formatting options for Highlighting Specific Expressions enum: - use_single_curly_quotation_marks - use_single_straight_quotation_marks japanese_reference_materials: type: string description: Formatting options for Japanese Reference Materials enum: - use_double_corner_brackets parentheses_for_supplementary_information: type: string description: Formatting options for Parentheses For Supplementary Information enum: - use_parentheses_without_space_on_either_side passage_of_time_and_movement_between_locations: type: string description: Formatting options for Passage Of Time And Movement Between Locations enum: - use_double_em_dash periods_and_commas: type: string description: Formatting options for Periods And Commas enum: - use_full_width_japanese_periods_and_full_width_japanese_commas - use_full_width_japanese_periods_and_full_width_non_japanese_commas - use_full_width_non_japanese_periods_and_full_width_japanese_commas - use_full_width_non_japanese_periods_and_full_width_non_japanese_commas periods_in_academic_degrees: type: string description: Formatting options for Periods In Academic Degrees enum: - do_not_use - use periods_in_direct_quotes: type: string description: Formatting options for Periods In Direct Quotes enum: - do_not_use - use periods_in_uppercase_initialisms_and_acronyms: type: string description: Formatting options for Periods In Uppercase Initialisms And Acronyms enum: - do_not_use plus_sign_usage: type: string description: Formatting options for Plus Sign Usage enum: - do_not_use_plus_sign_to_symbolize_english_word_and_unless_it_is_part_of_a_proper_noun possessives_of_proper_names_ending_in_s_style: type: string description: Formatting options for Possessives Of Proper Names Ending In S Style enum: - add_apostrophe_only - add_apostrophe_s quotation_mark: type: string description: Formatting options for Quotation Mark enum: - use_curly_quotation_marks - use_double_curly_quotation_marks - use_double_straight_quotation_marks - use_guillemets - use_straight_quotation_marks quotation_mark_and_apostrophe: type: string description: Formatting options for Quotation Mark And Apostrophe enum: - use_curly_quotation_marks_and_apostrophes - use_double_and_single_curly_quotation_marks_and_curly_apostrophes - use_double_and_single_straight_quotation_marks_and_straight_apostrophes - use_guillemets_and_curly_apostrophes - use_guillemets_and_straight_apostrophes - use_straight_quotation_marks_and_apostrophes quotation_style: type: string description: Formatting options for Quotation Style enum: - use_corner_brackets_for_primary_quotations_and_double_corner_brackets_for_secondary_quotations - use_double_curly_quotation_marks_for_primary_quotations_and_single_curly_quotation_marks_for_secondary_quotations - use_double_curly_quotation_marks_for_primary_quotations_then_alternate_with_single_curly_quotation_marks_for_nested_quotations - use_double_german_quotation_marks_for_primary_quotations_and_single_german_quotation_marks_for_secondary_quotations - use_double_quotation_marks_for_primary_quotations_and_single_quotation_marks_for_secondary_quotations - use_double_straight_quotation_marks_for_primary_quotations_and_single_straight_quotation_marks_for_secondary_quotations - use_double_straight_quotation_marks_for_primary_quotations_then_alternate_with_single_straight_quotation_marks_for_nested_quotations - use_guillemets_for_primary_quotations_and_double_curly_quotation_marks_for_secondary_quotations - use_guillemets_for_primary_quotations_and_double_straight_quotation_marks_for_secondary_quotations - use_guillemets_for_primary_quotations_and_single_guillemets_for_secondary_quotations - use_guillemets_for_primary_quotations_double_curly_quotation_marks_for_secondary_quotations_and_single_curly_quotation_marks_for_further_nested_quotations - use_reversed_guillemets_for_primary_quotations_and_single_reversed_guillemets_for_secondary_quotations - use_single_quotation_marks_for_primary_quotations_and_double_quotation_marks_for_secondary_quotations range_indicator: type: string description: Formatting options for Range Indicator enum: - use_en_dash_with_spaces - use_en_dash_without_space_on_either_side - use_en_dash_without_spaces - use_english_word_to - use_full_width_dash - use_full_width_wave_dash - use_german_word_bis - use_half_width_dash - use_hyphen - use_hyphen_with_space_on_either_side - use_hyphen_with_spaces - use_hyphen_without_space_on_either_side - use_hyphen_without_spaces - use_italian_words_da_a - use_japanese_word_から - use_korean_words_부터_까지 - use_spanish_words_de_a - use_tilde related_phrases_indicator: type: string description: Formatting options for Related Phrases Indicator enum: - use_comma - use_hyphen - use_middle_dot round_brackets: type: string description: Formatting options for Round Brackets enum: - use_full_width_round_brackets - use_half_width_round_brackets salutation: type: string description: Formatting options for Salutation enum: - do_not_use_comma_after_salutation_capitalize_following_word - use_colon_after_salutation - use_comma_after_salutation - use_exclamation_mark_after_salutation sentence_break_indicator: type: string description: Formatting options for Sentence Break Indicator enum: - use_em_dash_with_space_on_either_side - use_em_dash_without_space_on_either_side - use_en_dash_with_space_on_either_side serial_comma: type: string description: Formatting options for Serial Comma enum: - do_not_use - do_not_use_serial_comma_when_using_chinese_comma - use - use_serial_comma_when_using_comma setting_off_non_quoted_phrases: type: string description: Formatting options for Setting Off Non Quoted Phrases enum: - use_full_width_quotation_marks - use_half_width_quotation_marks slash: type: string description: Formatting options for Slash enum: - do_not_use_spaces_before_and_after_slashes - use_spaces_before_and_after_slashes - use_spaces_before_and_after_slashes_if_there_are_multiple_words_before_and_after_slash - use_spaces_before_and_after_slashes_if_there_are_multiple_words_before_or_after_slash slash_usage: type: string description: Formatting options for Slash Usage enum: - do_not_use_slash_to_symbolize_english_word_or spacing_and_punctuation: type: string description: Formatting options for Spacing And Punctuation enum: - do_not_use_space - use_regular_space text_in_round_brackets_referring_to_previous_sentence: type: string description: Formatting options for Text In Round Brackets Referring To Previous Sentence enum: - add_period_after_closing_round_bracket - add_period_before_closing_round_bracket text_in_round_brackets_supplementing_preceding_text: type: string description: Formatting options for Text In Round Brackets Supplementing Preceding Text enum: - add_period_after_closing_round_bracket titles_of_books_and_newspapers: type: string description: Formatting options for Titles Of Books And Newspapers enum: - use_double_angle_brackets - use_double_corner_brackets - use_double_straight_quotation_marks titles_of_creative_works_trade_names_laws_and_regulations: type: string description: Formatting options for Titles Of Creative Works Trade Names Laws And Regulations enum: - use_single_angle_brackets - use_single_corner_brackets - use_single_straight_quotation_marks uppercase_acronyms: type: string description: Formatting options for Uppercase Acronyms enum: - do_not_use_spaces - use_spaces spelling_and_grammar: type: object properties: abbreviating_french_word_numero: type: string description: Formatting options for Abbreviating French Word Numero enum: - abbreviate_as_n_then_degree_symbol - abbreviate_as_n_then_o_in_superscript - abbreviate_as_no abbreviation_usage: type: string description: Formatting options for Abbreviation Usage enum: - do_not_use_abbreviations - do_not_use_abbreviations_unless_necessary - use_abbreviations - use_abbreviations_as_needed accents_and_cedillas: type: string description: Formatting options for Accents And Cedillas enum: - do_not_use_on_capital_letters - never_use - use_even_on_capital_letters accents_in_verbs_conjugated_like_french_word_céder: type: string description: Formatting options for Accents In Verbs Conjugated Like French Word Céder enum: - use_acute_accent - use_grave_accent accents_with_subject_verb_inversion: type: string description: Formatting options for Accents With Subject Verb Inversion enum: - use_acute_accent - use_grave_accent active_passive_voice: type: string description: Formatting options for Active Passive Voice enum: - use_active_voice_if_subject_is_prominent_and_agent_is_clear - use_active_voice_to_describe_operations_with_user_as_subject - use_active_voice_unless_agent_is_unknown_or_irrelevant - use_passive_voice_as_needed - use_passive_voice_for_automatic_operations_from_user_perspective - use_passive_voice_if_agent_is_unknown_or_irrelevant all_caps: type: string description: Formatting options for All Caps enum: - do_not_use_all_caps_except_for_acronyms_initialisms_or_proper_nouns - do_not_use_all_caps_except_for_acronyms_or_brand_names complete_sentences: type: string description: Formatting options for Complete Sentences enum: - always_write_complete_sentences compound_nouns: type: string description: Formatting options for Compound Nouns enum: - write_as_one_word - write_with_hyphen conjunctions: type: string description: Formatting options for Conjunctions enum: - never_start_sentence_with_coordinating_conjunction contractions: type: string description: Formatting options for Contractions enum: - do_not_use_contractions - use_contractions - use_contractions_but_avoid_negative_contractions established_loanwords: type: string description: Formatting options for Established Loanwords enum: - use_as_is - use_native_or_sino_korean_equivalents eszett: type: string description: Formatting options for Eszett enum: - replace_eszett_with_ss foreign_word_translation: type: string description: Formatting options for Foreign Word Translation enum: - use_equivalent_expressions_in_chinese - use_foreign_forms_or_abbreviations_for_technical_terms_or_brand_names - use_literal_translation - use_localized_names_for_brands_with_official_chinese_translations - use_mixture_of_transliteration_and_translation - use_transliteration french_verbs_ending_in_eler_and_eter: type: string description: Formatting options for French Verbs Ending In Eler And Eter enum: - transcribe_open_e_sound_by_doubling_next_consonant - transcribe_open_e_sound_with_grave_accent i_and_u_with_circumflex_accents: type: string description: Formatting options for I And U With Circumflex Accents enum: - do_not_use_circumflex_accents_except_in_verbs_and_to_distinguish_homophones - use_circumflex_accents informal_address_pronouns: type: string description: Formatting options for Informal Address Pronouns enum: - capitalize_informal_address_pronouns - do_not_capitalize_informal_address_pronouns latin_abbreviations: type: string description: Formatting options for Latin Abbreviations enum: - do_not_use_latin_abbreviations passive_voice: type: string description: Formatting options for Passive Voice enum: - avoid_passive_voice_when_agent_is_known past_participle_of_french_word_laisser_followed_by_infinitive: type: string description: Formatting options for Past Participle Of French Word Laisser Followed By Infinitive enum: - make_french_word_laisser_agree_with_direct_object_complement_if_it_appears_before_verb - use_invariable_form_french_word_laissé personal_titles: type: string description: Formatting options for Personal Titles enum: - abbreviate - do_not_abbreviate pluralizing_foreign_words: type: string description: Formatting options for Pluralizing Foreign Words enum: - use_french_spelling_rules - use_original_language_spelling quotation_modification: type: string description: Formatting options for Quotation Modification enum: - do_not_modify_text_in_quotation_marks - modify_text_in_quotation_marks_according_to_custom_rules spanish_word_solo: type: string description: Formatting options for Spanish Word Solo enum: - never_use_acute_accent - use_acute_accent_when_used_as_adverb special_characters: type: string description: Formatting options for Special Characters enum: - never_use_symbols spelled_out_numbers: type: string description: Formatting options for Spelled Out Numbers enum: - use_hyphens - use_hyphens_between_elements_under_100_and_not_separated_by_french_word_et umlauts: type: string description: Formatting options for Umlauts enum: - replace_umlauts_with_ae_oe_ue unestablished_loanwords: type: string description: Formatting options for Unestablished Loanwords enum: - paraphrase_in_korean - use_as_is - use_as_is_with_explanation_in_parentheses style_and_tone: type: object properties: abbreviations: type: string description: Formatting options for Abbreviations enum: - avoid_abbreviations_and_symbols_that_can_be_spelled_out_easily - use_abbreviations_and_symbols addressing_non_binary_people: type: string description: Formatting options for Addressing Non Binary People enum: - use_spanish_word_elle - use_spanish_word_ellx addressing_the_reader: type: string description: Formatting options for Addressing The Reader enum: - use_formal_french_word_vous - use_formal_italian_word_lei - use_informal_french_word_tu - use_informal_italian_word_tu anglicisms: type: string description: Formatting options for Anglicisms enum: - avoid_anglicisms_when_there_is_a_french_equivalent binary_representation_of_gender: type: string description: Formatting options for Binary Representation Of Gender enum: - avoid_binary_representation_of_gender_when_gender_neutral_language_can_be_used - replace_binary_representations_of_gender_with_gender_neutral_language - use_neutral_pronouns complex_sentences: type: string description: Formatting options for Complex Sentences enum: - avoid_unnecessarily_complex_sentences country_names: type: string description: Formatting options for Country Names enum: - use_long_form - use_short_form declarative_endings: type: string description: Formatting options for Declarative Endings enum: - mix_hapsho_and_haeyo_styles - use_hae_style - use_haeyo_style - use_hapsho_style - use_hara_style default_first_person_pronoun: type: string description: Formatting options for Default First Person Pronoun enum: - do_not_use_first_person_pronouns - omit_first_person_subject_when_clear_from_context - use_first_person_pronouns default_second_person_pronoun: type: string description: Formatting options for Default Second Person Pronoun enum: - do_not_use_second_person_pronouns - use_second_person_pronouns directional_language: type: string description: Formatting options for Directional Language enum: - do_not_use_directional_language double_negatives: type: string description: Formatting options for Double Negatives enum: - do_not_use_double_negatives - use_double_negatives formality: type: string description: Formatting options for Formality enum: - use_casual_tone - use_formal_tone gender_neutral_language_readability: type: string description: Formatting options for Gender Neutral Language Readability enum: - use_generic_masculine_for_common_compound_nouns_if_it_increases_readability gender_unspecified: type: string description: Formatting options for Gender Unspecified enum: - use_both_masculine_and_feminine_forms - use_gender_neutral_terms - use_masculine_form_only - use_middle_dots - use_parentheses - use_periods gender_unspecified_or_mixed: type: string description: Formatting options for Gender Unspecified Or Mixed enum: - use_both_feminine_and_masculine_forms - use_feminine_form_only - use_inclusive_nouns_and_adjectives - use_masculine_form_only - use_neutral_nouns_and_adjectives idioms_colloquialisms_and_culture_specific_references: type: string description: Formatting options for Idioms Colloquialisms And Culture Specific References enum: - do_not_use inflected_words_masculine_noun_agreement: type: string description: Formatting options for Inflected Words Masculine Noun Agreement enum: - place_masculine_nouns_closest_to_inflected_words instructions_style: type: string description: Formatting options for Instructions Style enum: - use_imperative - use_indicative - use_infinitive - use_modal_verbs - use_passive_voice mixing_styles: type: string description: Formatting options for Mixing Styles enum: - do_not_mix_desu_masu_style_and_dearu_style modal_verbs: type: string description: Formatting options for Modal Verbs enum: - avoid_modal_verbs personal_vs_impersonal_style: type: string description: Formatting options for Personal Vs Impersonal Style enum: - use_impersonal_style - use_personal_style positive_vs_negative_language: type: string description: Formatting options for Positive Vs Negative Language enum: - use_positive_language proximity_agreement: type: string description: Formatting options for Proximity Agreement enum: - use reader_action_required: type: string description: Formatting options for Reader Action Required enum: - use_you_must_when_action_is_required_from_reader redundant_introductory_phrases: type: string description: Formatting options for Redundant Introductory Phrases enum: - avoid_redundant_introductory_phrases - do_not_use_redundant_phrases_that_refer_to_current_text redundant_phrases: type: string description: Formatting options for Redundant Phrases enum: - avoid_relativizing_and_redundant_phrases - do_not_use_redundant_phrases referring_to_non_binary_people: type: string description: Formatting options for Referring To Non Binary People enum: - use_the_singular_and_plural_schwa short_vs_long_words: type: string description: Formatting options for Short Vs Long Words enum: - use_short_words simple_words_and_sentences: type: string description: Formatting options for Simple Words And Sentences enum: - use_simple_words_and_sentences_avoid_hard_to_translate_words_and_figures_of_speech text_position_references: type: string description: Formatting options for Text Position References enum: - avoid_directional_terms_as_only_reference_to_position_in_text_specify_exact_position_instead tone: type: string description: Formatting options for Tone enum: - use_dearu_style_to_give_impression_content_is_accurate_and_rigorous_or_to_convey_sense_of_confidence_and_reliability - use_desu_masu_style_to_give_impression_content_is_plain_and_straightforward_or_to_give_reader_reassuring_or_soft_impression verbal_vs_nominal_style: type: string description: Formatting options for Verbal Vs Nominal Style enum: - use_nominal_style - use_verbal_style vocabulary: type: object properties: abbreviations: type: string description: Formatting options for Abbreviations enum: - write_original_term_then_abbreviation_and_explanation loanwords: type: string description: Formatting options for Loanwords enum: - add_explanation_to_loanword_if_difficult_to_rephrase - rephrase_loanword_in_daily_use_chinese_or_japanese_words_if_possible - rephrase_loanword_with_another_expression_if_not_established - use_loanword_as_is_if_well_established Context: description: |- 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). type: string CreateGlossaryParameters: type: object required: - name - source_lang - target_lang - entries - entries_format properties: name: description: Name to be associated with the glossary. type: string example: My Glossary source_lang: $ref: '#/components/schemas/GlossarySourceLanguage' target_lang: $ref: '#/components/schemas/GlossaryTargetLanguage' entries: description: The entries of the glossary. The entries have to be specified in the format provided by the `entries_format` parameter. type: string example: "Hello\tGuten Tag" entries_format: description: |- The format in which the glossary entries are provided. Formats currently available: - `tsv` (default) - tab-separated values - `csv` - comma-separated values See [Supported Glossary Formats](https://www.deepl.com/docs-api/glossaries/formats) for details about each format. type: string enum: - tsv - csv example: tsv default: tsv CreateMultilingualGlossaryParameters: type: object required: - name - dictionaries properties: name: description: Name to be associated with the glossary. type: string example: My Glossary dictionaries: description: Dictionaries to populate the glossary with. type: array items: $ref: '#/components/schemas/GlossaryDictionary' CustomInstruction: description: All enabled custom instructions for the style rule list type: object required: - id - label - prompt properties: id: type: string description: Unique identifier for the custom instruction example: "68fdb803-c013-4e67-b62e-1aad0ab519cd" label: type: string description: Name associated with the custom instruction example: "Currency custom instruction" prompt: type: string description: Prompt of the custom instruction example: "Have currency symbols before the numerical value (e.g. $100, €100)" source_language: type: string description: Optional source language of the custom instruction example: "en" CustomInstructionRequest: description: Input schema for creating or updating a custom instruction type: object required: - label - prompt properties: label: type: string description: Name associated with the custom instruction example: "Currency custom instruction" maxLength: 100 prompt: type: string description: Prompt of the custom instruction example: "Have currency symbols before the numerical value (e.g. $100, €100)" maxLength: 300 source_language: type: string description: Optional source language of the custom instruction example: "en" DocumentTranslationError: type: object properties: message: type: string description: detailed error message DocumentKey: type: object required: - document_key properties: document_key: description: The document encryption key that was sent to the client when the document was uploaded to the API. type: string example: 0CB0054F1C132C1625B392EADDA41CB754A742822F6877173029A6C487E7F60A Formality: description: |- 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 [here](https://support.deepl.com/hc/en-us/articles/6306700061852-About-the-plain-polite-feature-in-Japanese). 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 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 type: string enum: - default - more - less - prefer_more - prefer_less default: default GlossaryDictionary: type: object description: A dictionary contained in a multilingual glossary. Each dictionary contains the mapping of source terms to target language terms. properties: source_lang: $ref: '#/components/schemas/GlossarySourceLanguage' target_lang: $ref: '#/components/schemas/GlossaryTargetLanguage' entries: $ref: '#/components/schemas/GlossaryEntries' entries_format: $ref: '#/components/schemas/GlossaryEntriesFormat' GlossaryEntries: type: string description: The entries of the glossary. The entries have to be specified in the format provided by the `entries_format` parameter. example: "Hello\tGuten Tag" GlossaryEntriesFormat: description: |- The format in which the glossary entries are provided. Formats currently available: - `tsv` (default) - tab-separated values - `csv` - comma-separated values See [Supported Glossary Formats](https://www.deepl.com/docs-api/glossaries/formats) for details about each format. type: string enum: - tsv - csv example: tsv default: tsv GlossaryEntryCount: description: The number of entries in the glossary. type: integer GlossaryId: type: string description: A unique ID assigned to a glossary. example: def3a26b-3e84-45b3-84ae-0c0aaf3525f7 GlossaryName: description: Name associated with the glossary. type: string GlossarySourceLanguage: type: string description: The language in which the source texts in the glossary are specified. enum: - ar - bg - cs - da - de - el - en - es - et - fi - fr - he - hu - id - it - ja - ko - lt - lv - nb - nl - pl - pt - ro - ru - sk - sl - sv - th - tr - uk - vi - zh example: en GlossaryTargetLanguage: type: string description: The language in which the target texts in the glossary are specified. enum: - ar - bg - cs - da - de - el - en - es - et - fi - fr - he - hu - id - it - ja - ko - lt - lv - nb - nl - pl - pt - ro - ru - sk - sl - sv - th - tr - uk - vi - zh example: de ModelType: type: string description: |- Specifies which DeepL model should be used for translation. Possible values are: * `latency_optimized` (default) - uses lower latency “classic” translation models, which support all language pairs; default value * `quality_optimized` - uses higher latency, improved quality “next-gen” translation models, which support only a subset of language pairs; if a language pair that is not supported by next-gen models is included in the request, it will fail. Consider using prefer_quality_optimized instead. * `prefer_quality_optimized` - prioritizes use of higher latency, improved quality “next-gen” translation models, which support only a subset of DeepL languages; if a request includes a language pair not supported by next-gen models, the request will fall back to latency_optimized classic models. enum: - quality_optimized - prefer_quality_optimized - latency_optimized MonolingualGlossary: type: object properties: glossary_id: $ref: '#/components/schemas/GlossaryId' name: $ref: '#/components/schemas/GlossaryName' ready: description: |- Indicates if the newly created glossary can already be used in `translate` requests. If the created glossary is not yet ready, you have to wait and check the `ready` status of the glossary before using it in a `translate` request. type: boolean source_lang: $ref: '#/components/schemas/GlossarySourceLanguage' target_lang: $ref: '#/components/schemas/GlossaryTargetLanguage' creation_time: description: 'The creation time of the glossary in the ISO 8601-1:2019 format (e.g.: `2021-08-03T14:16:18.329Z`).' type: string format: date-time entry_count: $ref: '#/components/schemas/GlossaryEntryCount' example: 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 MultilingualGlossary: type: object properties: glossary_id: $ref: '#/components/schemas/GlossaryId' name: $ref: '#/components/schemas/GlossaryName' dictionaries: description: |- List of dictionaries contained in this glossary. Each dictionary contains a source and target language, as well as pairs of source and target entries. type: array items: $ref: '#/components/schemas/GlossaryDictionary' creation_time: description: 'The creation time of the glossary in the ISO 8601-1:2019 format (e.g.: `2021-08-03T14:16:18.329Z`).' type: string format: date-time example: glossary_id: def3a26b-3e84-45b3-84ae-0c0aaf3525f7 name: My Glossary dictionaries: - source_lang: en target_lang: de entry_count: 1 creation_time: '2021-08-03T14:16:18.329Z' MultilingualGlossaryEntries: type: object properties: source_lang: $ref: '#/components/schemas/GlossarySourceLanguage' target_lang: $ref: '#/components/schemas/GlossaryTargetLanguage' entries: $ref: '#/components/schemas/GlossaryEntries' entries_format: $ref: '#/components/schemas/GlossaryEntriesFormat' MultilingualGlossaryEntriesResponse: type: object properties: dictionaries: type: array items: $ref: '#/components/schemas/MultilingualGlossaryEntriesInformation' MultilingualGlossaryEntriesInformation: type: object properties: source_lang: $ref: '#/components/schemas/GlossarySourceLanguage' target_lang: $ref: '#/components/schemas/GlossaryTargetLanguage' entry_count: $ref: '#/components/schemas/GlossaryEntryCount' OutlineDetectionOption: description: |- 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=0` and setting the parameters manually to `tag_handling=xml`, `split_sentences=nonewlines`, and `splitting_tags=par,title`. * Example request: ``` A document's title This is the first sentence. Followed by a second one. This is the third sentence. ``` * 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". type: boolean default: true OutlineDetectionOptionStr: description: |- 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 `0` 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=0` and setting the parameters manually to `tag_handling=xml`, `split_sentences=nonewlines`, and `splitting_tags=par,title`. * Example request: ``` A document's title This is the first sentence. Followed by a second one. This is the third sentence. ``` * 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. type: string enum: - '0' PatchMultilingualGlossaryParameters: type: object properties: name: $ref: '#/components/schemas/GlossaryId' dictionaries: description: Dictionaries to edit the glossary with. Currently only supports 0 or 1 dictionaries in the array. type: array items: $ref: '#/components/schemas/GlossaryDictionary' PreserveFormattingOption: description: |- 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". type: boolean default: false PreserveFormattingOptionStr: description: |- Sets whether the translation engine should respect the original formatting, even if it would usually correct some aspects. Possible values are: * `0` (default) * `1` 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 type: string enum: - '0' - '1' default: '0' PutMultilingualGlossaryParameters: $ref: '#/components/schemas/MultilingualGlossaryEntries' ShowBilledCharacters: description: |- When true, the response will include the billed_characters parameter, giving the number of characters from the request that will be counted by DeepL for billing purposes. Note: for requests sent as URL-encoded forms, boolean values should be specified as "1" or "0". type: boolean SplitSentencesOption: description: |- 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 sentence * `1` (default when `tag_handling` is not set to `html`) - splits on punctuation and on newlines * `nonewlines` (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`. type: string enum: - '0' - '1' - nonewlines default: '1' SourceLanguage: type: string description: |- Language of the text to be translated. If this parameter is omitted, the API will attempt to detect the language of the text and translate it. **Note:** Some languages only work with `model_type` set to `quality_optimized`. See [supported languages](https://developers.deepl.com/docs/getting-started/supported-languages) for more details. enum: - ACE - AF - AN - AR - AS - AY - AZ - BA - BE - BG - BHO - BN - BR - BS - CA - CEB - CKB - CS - CY - DA - DE - EL - EN - EO - ES - ET - EU - FA - FI - FR - GA - GL - GN - GOM - GU - HA - HE - HI - HR - HT - HU - HY - ID - IG - IS - IT - JA - JV - KA - KK - KMR - KO - KY - LA - LB - LMO - LN - LT - LV - MAI - MG - MI - MK - ML - MN - MR - MS - MT - MY - NB - NE - NL - OC - OM - PA - PAG - PAM - PL - PRS - PS - PT - QU - RO - RU - SA - SCN - SK - SL - SQ - SR - ST - SU - SV - SW - TA - TE - TG - TH - TK - TL - TN - TR - TS - TT - UK - UR - UZ - VI - WO - XH - YI - YUE - ZH - ZU example: EN StyleRuleList: type: object required: - style_id - name - creation_time - updated_time - language - version properties: style_id: $ref: '#/components/schemas/StyleId' name: $ref: '#/components/schemas/StyleRuleName' creation_time: description: 'The creation time of the style rule in the ISO 8601-1:2019 format (e.g.: `2021-08-03T14:16:18.329Z`).' type: string format: date-time updated_time: description: 'The time of the style rule when it was last updated in the ISO 8601-1:2019 format (e.g.: `2022-08-03T14:16:18.329Z`).' type: string format: date-time language: $ref: '#/components/schemas/StyleRuleLanguage' version: description: The version of the style rule. Incremented when the style rule is updated. type: integer example: 13 configured_rules: $ref: '#/components/schemas/ConfiguredRules' custom_instructions: type: array description: |- List of custom instructions enabled for the style rule list. items: $ref: '#/components/schemas/CustomInstruction' StyleId: type: string description: A unique ID assigned to a style rule. example: "bd0a38f3-1831-440b-a8dd-2c702e2325ab" StyleRuleLanguage: description: The language that the style rules are applied to. type: string enum: - de - en - es - fr - it - ja - ko - zh StyleRuleName: description: Name associated with the style rule. type: string TagHandlingOption: description: |- Sets which kind of tags should be handled. Options currently available: * `xml`: Enable XML tag handling; see [XML Handling](https://www.deepl.com/docs-api/xml). * `html`: Enable HTML tag handling; see [HTML Handling](https://www.deepl.com/docs-api/html). type: string enum: - xml - html TagHandlingVersionOption: description: |- Sets which version of the tag handling algorithm should be used. Options currently available: * `v2`: Improved algorithm released in October 2025 (default as of December 2025). * `v1`: Traditional algorithm (default until December 2025). type: string enum: - v2 - v1 UsageResponse: type: object properties: character_count: description: Characters translated so far in the current billing period. type: integer format: int64 example: 180118 character_limit: description: Current maximum number of characters that can be translated per billing period. If cost control is set, the cost control limit will be returned in this field. type: integer format: int64 example: 1250000 products: type: array description: Only present for API Pro users. Per-product usage details. items: type: object properties: product_type: type: string description: The type of product (e.g., 'write', 'translate'). example: write billing_unit: type: string enum: - characters - milliseconds description: The billing unit for this product type. example: characters api_key_unit_count: type: integer description: Units used for this product by this API key in the current period. example: 0 account_unit_count: type: integer description: Total units used for this product by the account in the current period. example: 5643 api_key_character_count: type: integer description: Characters used for this product by this API key in the current period. example: 0 character_count: type: integer description: Total characters used for this product in the current period. example: 5643 api_key_character_count: type: integer description: Only present for API Pro users. Total characters used by this API key in the current period. example: 636 api_key_character_limit: type: integer description: Only present for API Pro users. Character limit for this API key in the current period. example: 1000000000000 speech_to_text_milliseconds_count: type: integer description: Only present for API Pro users. Milliseconds of speech-to-text used in the current period. example: 1800000 speech_to_text_milliseconds_limit: type: integer description: Only present for API Pro users. Milliseconds of speech-to-text limit in the current period. example: 36000000 start_time: type: string format: date-time description: Only present for API Pro users. Start time of the current billing period (ISO 8601). example: '2025-05-13T09:18:42Z' end_time: type: string format: date-time description: Only present for API Pro users. End time of the current billing period (ISO 8601). example: '2025-06-13T09:18:42Z' NonSplittingTagCommaSeparatedList: allOf: - $ref: '#/components/schemas/TagCommaSeparatedList' description: |- Comma-separated list of XML tags which never split sentences. For some XML files, finding tags with textual content and splitting sentences using those tags won't yield the best results. The following example shows the engine splitting sentences on `par` tags and proceeding to translate the parts separately, resulting in an incorrect translation: * Example request: ``` The firm said it had been conducting an internal investigation. ``` * Example response: ``` Die Firma sagte, es sei eine gute Idee gewesen. Durchführung einer internen Untersuchung. ``` As this can lead to bad translations, this type of structure should either be avoided, or the `non_splitting_tags` parameter should be set. The following example shows the same call, with the parameter set to `par`: * Example request: ``` The firm said it had been conducting an internal investigation. ``` * Example response: ``` Die Firma sagte, dass sie eine interne Untersuchung durchgeführt habe. ``` This time, the sentence is translated as a whole. The XML tags are now considered markup and copied into the translated sentence. As the translation of the words "had been" has moved to another position in the German sentence, the two par tags are duplicated (which is expected here). NonSplittingTagList: allOf: - $ref: '#/components/schemas/TagList' description: |- List of XML tags which never split sentences. For some XML files, finding tags with textual content and splitting sentences using those tags won't yield the best results. The following example shows the engine splitting sentences on `par` tags and proceeding to translate the parts separately, resulting in an incorrect translation: * Example request: ``` The firm said it had been conducting an internal investigation. ``` * Example response: ``` Die Firma sagte, es sei eine gute Idee gewesen. Durchführung einer internen Untersuchung. ``` As this can lead to bad translations, this type of structure should either be avoided, or the `non_splitting_tags` parameter should be set. The following example shows the same call, with the parameter set to `par`: * Example request: ``` The firm said it had been conducting an internal investigation. ``` * Example response: ``` Die Firma sagte, dass sie eine interne Untersuchung durchgeführt habe. ``` This time, the sentence is translated as a whole. The XML tags are now considered markup and copied into the translated sentence. As the translation of the words "had been" has moved to another position in the German sentence, the two par tags are duplicated (which is expected here). SplittingTagCommaSeparatedList: allOf: - $ref: '#/components/schemas/TagCommaSeparatedList' description: |- Comma-separated list of XML tags which always cause splits. See the example in the `outline_detection` parameter's description. SplittingTagList: allOf: - $ref: '#/components/schemas/TagList' description: |- List of XML tags which always cause splits. See the example in the `outline_detection` parameter's description. IgnoreTagCommaSeparatedList: allOf: - $ref: '#/components/schemas/TagCommaSeparatedList' description: |- Comma-separated list of XML tags that indicate text not to be translated. Use this parameter to ensure that elements in the original text are not altered in the translation (e.g., trademarks, product names) and insert tags into your original text. In the following example, the `ignore_tags` parameter is set to `keep`: * Example request: ``` Please open the page Settings to configure your system. ``` * Example response: ``` Bitte öffnen Sie die Seite Settings um Ihr System zu konfigurieren. ``` IgnoreTagList: allOf: - $ref: '#/components/schemas/TagList' description: |- List of XML tags that indicate text not to be translated. Use this parameter to ensure that elements in the original text are not altered in the translation (e.g., trademarks, product names) and insert tags into your original text. In the following example, the `ignore_tags` parameter is set to `keep`: * Example request: ``` Please open the page Settings to configure your system. ``` * Example response: ``` Bitte öffnen Sie die Seite Settings um Ihr System zu konfigurieren. ``` TagCommaSeparatedList: description: Comma-separated list of XML tags. type: string example: a,p,span TagList: description: List of XML tags. type: array items: type: string example: - a - p - span TargetLanguage: type: string description: |- The language into which the text should be translated. **Note:** Some languages only work with `model_type` set to `quality_optimized`. See [supported languages](https://developers.deepl.com/docs/getting-started/supported-languages) for more details. enum: - ACE - AF - AN - AR - AS - AY - AZ - BA - BE - BG - BHO - BN - BR - BS - CA - CEB - CKB - CS - CY - DA - DE - EL - EN - EN-GB - EN-US - EO - ES - ES-419 - ET - EU - FA - FI - FR - GA - GL - GN - GOM - GU - HA - HE - HI - HR - HT - HU - HY - ID - IG - IS - IT - JA - JV - KA - KK - KMR - KO - KY - LA - LB - LMO - LN - LT - LV - MAI - MG - MI - MK - ML - MN - MR - MS - MT - MY - NB - NE - NL - OC - OM - PA - PAG - PAM - PL - PRS - PS - PT - PT-BR - PT-PT - QU - RO - RU - SA - SCN - SK - SL - SQ - SR - ST - SU - SV - SW - TA - TE - TG - TH - TK - TL - TN - TR - TS - TT - UK - UR - UZ - VI - WO - XH - YI - YUE - ZH - ZH-HANS - ZH-HANT - ZU example: DE TargetLanguageWrite: type: string description: |- The language for the text improvement. Options currently available: * `de` - German * `en` - English (unspecified variant, defaults to `en-US`) * `en-GB` - English (British) * `en-US` - English (American) * `es` - Spanish * `fr` - French * `it` - Italian * `pt` - Portuguese (unspecified variant, defaults to `pt-PT`) * `pt-BR` - Portuguese (Brazilian) * `pt-PT` - Portuguese (all Portuguese variants excluding Brazilian Portuguese) enum: - de - en - en-GB - en-US - fr - it - pt - pt-BR - pt-PT example: de VoiceFormality: description: |- Sets whether the translated text should lean towards formal or informal language. Possible options are: * `default` - use the default formality for the target language * `formal`/`more` - for a more formal language * `informal`/`less` - for a more informal language type: string enum: - default - formal - more - informal - less default: default example: formal VoiceMediaContentType: type: string description: |- The audio format for streaming. Specifies container, codec, and encoding parameters. Supported formats include PCM (recommended), OPUS (recommended for low bandwidth), FLAC, MP3, and AAC. PCM formats require explicit sample rate. Mono audio only. enum: - audio/auto - audio/flac - audio/mpeg - audio/ogg - audio/webm - audio/x-matroska - audio/ogg; codecs=flac - audio/ogg; codecs=opus - audio/pcm; encoding=s16le; rate=8000 - audio/pcm; encoding=s16le; rate=16000 - audio/pcm; encoding=s16le; rate=44100 - audio/pcm; encoding=s16le; rate=48000 - audio/webm; codecs=opus - audio/x-matroska; codecs=aac - audio/x-matroska; codecs=flac - audio/x-matroska; codecs=mp3 - audio/x-matroska; codecs=opus example: audio/ogg; codecs=opus VoiceSourceLanguage: type: string description: |- Source language of the audio stream. Must be one of the supported Voice API source languages. Language identifier must comply with IETF BCP 47 language tags. enum: - zh - nl - en - fr - de - id - it - ja - ko - pl - pt - ro - ru - es - sv - tr - uk example: en VoiceSourceLanguageMode: type: string description: |- Controls how the source_language value is used. - `auto`: Treats source language as a hint; server can override - `fixed`: Treats source language as mandatory; server must use this language enum: - auto - fixed default: auto example: auto VoiceStreamingResponse: type: object required: - streaming_url - token properties: streaming_url: type: string description: The WebSocket URL to use for establishing the streaming connection. This URL is ephemeral and valid for one-time use only. example: wss://api.deepl.com/v3/voice/realtime/connect token: type: string description: A unique ephemeral token for authentication with the streaming endpoint. Pass this as a query parameter when connecting to the WebSocket URL. example: VGhpcyBpcyBhIGZha2UgdG9rZW4K session_id: type: string description: Internal use only. A unique identifier for the requested stream. example: 4f911080-cfe2-41d4-8269-0e6ec15a0354 VoiceTargetLanguages: type: array description: |- List of target languages for translation. The stream will emit translations for each language. Maximum 5 target languages per stream. Language identifiers must comply with IETF BCP 47. items: type: string maxItems: 5 example: ['de', 'fr', 'es'] WritingStyle: type: string description: |- Specify a style to rephrase your text in a way that fits your audience and goals. The `prefer_` prefix allows falling back to the default style if the language does not yet support styles. enum: - academic - business - casual - default - simple - prefer_academic - prefer_business - prefer_casual - prefer_simple WritingTone: type: string description: |- Specify the desired tone for your text. The `prefer_` prefix allows falling back to the default tone if the language does not yet support tones. enum: - confident - default - diplomatic - enthusiastic - friendly - prefer_confident - prefer_diplomatic - prefer_enthusiastic - prefer_friendly AdminUsageReport: type: object description: The response for admin usage statistics. properties: usage_report: $ref: '#/components/schemas/AdminUsageReportData' AdminUsageReportData: type: object description: Contains the detailed usage statistics for the specified date range. properties: total_usage: $ref: '#/components/schemas/UsageBreakdown' start_date: type: string format: date-time description: Start date of the usage report period. example: "2025-09-29T00:00:00" end_date: type: string format: date-time description: End date of the usage report period. example: "2025-10-01T00:00:00" group_by: type: string description: The grouping method used, if any. enum: - key - key_and_day example: "key_and_day" key_usages: type: array description: Usage statistics grouped by key. Present when group_by='key'. items: $ref: '#/components/schemas/KeyUsageItem' key_and_day_usages: type: array description: Usage statistics grouped by key and day. Present when group_by='key_and_day'. items: $ref: '#/components/schemas/KeyAndDayUsageItem' UsageBreakdown: type: object description: Breakdown of character usage by category. properties: total_characters: type: integer description: Total number of characters used. example: 9619 text_translation_characters: type: integer description: Number of characters used for text translation. example: 4892 document_translation_characters: type: integer description: Number of characters used for document translation. example: 0 text_improvement_characters: type: integer description: Number of characters used for text improvement. example: 4727 speech_to_text_milliseconds: type: integer description: Duration of speech-to-text usage in milliseconds. example: 1800000 KeyUsageItem: type: object description: Usage statistics for a specific API key (without date grouping). properties: api_key: type: string description: Masked API key identifier. example: "db96****cb2c" api_key_label: type: string description: Label associated with the API key. example: "DeepL API Key Prod" usage: $ref: '#/components/schemas/UsageBreakdown' KeyAndDayUsageItem: type: object description: Usage statistics for a specific API key and specific date. properties: api_key: type: string description: Masked API key identifier. example: "db96****cb2c" api_key_label: type: string description: Label associated with the API key. example: "DeepL API Key Prod" usage_date: type: string format: date-time description: The usage date when group_by is "key_and_day". example: "2025-09-29T00:00:00Z" usage: $ref: '#/components/schemas/UsageBreakdown'