openapi: 3.0.3 info: title: DeepL API Documentation description: |- The DeepL API provides programmatic access to DeepL’s language AI technology. Note: this OpenAPI spec is embedded into our API documentation and has shortened descriptions. termsOfService: https://www.deepl.com/pro-license contact: name: DeepL - Contact us url: https://www.deepl.com/contact-us version: 3.13.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: beta description: Experimental features that are under testing and not yet intended for production use. - name: TranslateText description: |- The text-translation API currently consists of a single endpoint, `translate`, which is described below. - 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 (versions 1.2, 2.0, and 2.1) * `srt` - SRT Document * `idml` - Adobe InDesign Markup Language * `xml` - XML Document * `json` - JSON Document * `dita` - DITA topic (Darwin Information Typing Architecture) * `mif` - Adobe FrameMaker Interchange Format * `jpeg` / `jpg` / `png` - Image (currently in beta) - name: RephraseText description: |- The `rephrase` endpoint is used to make corrections and adjustments to texts based on style or tone. - name: CorrectText description: |- The `correct` endpoint fixes spelling and grammar errors without broader rephrasing. Use it when you want a minimal-change correction pass rather than the broader rewriting performed by `rephrase`. - name: ManageSpokenTerms description: |- The *Spoken Terms* functions allow you to create, inspect, edit and delete Spoken Terms collections. Spoken Terms improve speech recognition in the Voice API: they ensure specific words and phrases, such as company names, acronyms, and product names, are transcribed correctly. A collection contains one or more term lists, each holding terms for a single language, and is applied to a voice session via the `spoken_terms_id` parameter. - 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 (with the exception of Thai). 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 (with the exception of Thai). - name: MetaInformation description: Information about API usage and value ranges - name: TranslationMemories description: |- The translation memory endpoints allow you to manage your account's translation memories, used to store and reuse previously created translations. You can list and retrieve translation memories, page through their stored segments, create one by importing a TMX file, export one back to TMX, and delete one. Editing the contents of an existing translation memory is not supported; import a new one instead. Importing and exporting run as background jobs. Create the job, then poll `GET /v3/translation_memories/jobs/{job_id}` until it reports `completed`. Translation memories can be used in text translation requests by specifying the `translation_memory_id` parameter to denote a specific translation memory and the `translation_memory_threshold` which defines the minimum matching percentage required for a translation memory segment to be applied (recommended to be 75% or higher). A translation request fails with `404` if the translation memory does not exist or does not cover the requested language pair. - 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. - name: VoiceTranslateJob description: "**Alpha.** Async voice translation jobs. This API may change without notice." - name: AdminApi description: Endpoints for organization administrators to manage API keys and retrieve usage analytics. - name: QualityEvaluation description: |- **Closed alpha.** Evaluate translation quality. Submit source/target segment pairs and retrieve per-segment quality issues categorized by error type and severity, with character spans pointing to where each issue occurs. x-hideTryItPanel: true x-codeSamples: false paths: /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_minutes: 107.46 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_minutes: 11.94 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_minutes: 107.46 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: [ ] /v2/admin/analytics/custom-tags: get: tags: - AdminApi summary: Get custom tag usage statistics as an admin operationId: adminGetCustomTagAnalytics description: |- Retrieve usage statistics broken down by custom tags within a specified date range. Optionally aggregate results by day or over the entire period. Results are paginated; use the `page` parameter with the `next_page` value from a previous response to retrieve subsequent pages. 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: "2026-05-17" - name: end_date in: query required: true description: End date for the usage report (ISO 8601 date format). schema: type: string format: date example: "2026-05-18" - name: aggregate_by in: query required: false description: |- Optional parameter to control aggregation of usage statistics. Possible values: * `period` - Aggregate usage over the entire date range (default) * `day` - Group usage by individual day schema: type: string enum: - period - day default: period example: "day" - name: page in: query required: false description: |- Page number for pagination. Use the integer value returned in `next_page` from a previous response to retrieve the next page of results. schema: type: integer example: 2 responses: 200: description: The custom tag usage statistics for the specified date range. headers: X-Trace-ID: $ref: '#/components/headers/X-Trace-ID' content: application/json: schema: $ref: '#/components/schemas/CustomTagUsageReport' examples: aggregateByPeriod: summary: Usage report aggregated over the full period value: custom_tag_usage_report: aggregate_by: "period" start_date: "2026-05-03T00:00:00" end_date: "2026-05-05T00:00:00" next_page: null usage: - custom_tag: "example-custom-tag" breakdown: total_characters: 380 text_translation_characters: 380 text_improvement_characters: 0 speech_to_text_minutes: 12.5 speech_to_speech_minutes: 4.2 - custom_tag: "example-custom-tag-2" breakdown: total_characters: 475 text_translation_characters: 475 text_improvement_characters: 0 speech_to_text_minutes: 0 speech_to_speech_minutes: 0 aggregateByDay: summary: Usage report aggregated by day value: custom_tag_usage_report: aggregate_by: "day" start_date: "2026-05-03T00:00:00" end_date: "2026-05-15T00:00:00" next_page: null usage: - custom_tag: "example-custom-tag" usage_date: "2026-05-04T00:00:00Z" breakdown: total_characters: 380 text_translation_characters: 380 text_improvement_characters: 0 speech_to_text_minutes: 12.5 speech_to_speech_minutes: 4.2 - custom_tag: "example-custom-tag" usage_date: "2026-05-11T00:00:00Z" breakdown: total_characters: 595 text_translation_characters: 595 text_improvement_characters: 0 speech_to_text_minutes: 0 speech_to_speech_minutes: 0 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" invalidAggregateBy: summary: Invalid aggregate_by parameter value value: message: "Value for 'aggregate_by' not supported. Allowed: '', 'period', 'day'." 403: $ref: '#/components/responses/Forbidden' 404: $ref: '#/components/responses/NotFound' 500: $ref: '#/components/responses/InternalServerError' 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/translate: post: tags: - TranslateText summary: Request Translation operationId: translateText parameters: - $ref: '#/components/parameters/CustomReportingTag' 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 many times in a single request, within the request size limit (128KiB). Translations are returned in the same order as they are requested. Each text in the array is translated independently — texts do not share context with each other. type: array x-default: - Hello, World! items: type: string example: Hello, World! source_lang: $ref: '#/components/schemas/SourceLanguage' target_lang: $ref: '#/components/schemas/TargetLanguage' x-default: DE 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: description: |- Specify the glossary to use for the translation. **Important:** This requires the `source_lang` parameter to be set. The language pair of the glossary has to match the language pair of the request. Cannot be used together with `glossary_ids`. type: string example: def3a26b-3e84-45b3-84ae-0c0aaf3525f7 glossary_ids: description: |- Specify up to 5 glossaries to use for the translation, as an array of glossary IDs. Each glossary's matching terms are applied to the translation. **Important:** This requires the `source_lang` parameter to be set. Every listed glossary must contain a dictionary for the requested language pair. Cannot be used together with `glossary_id`. type: array maxItems: 5 items: type: string example: def3a26b-3e84-45b3-84ae-0c0aaf3525f7 style_id: description: |- Specify the [style rule list](/docs/customize/using-style-rules) to use for the translation. **Important:** The target language has to match the language of the style rule list. All `model_type` values are supported. type: string example: 7ff9bfd6-cd85-4190-8503-d6215a321519 translation_memory_id: $ref: '#/components/schemas/TranslationMemoryId' translation_memory_threshold: $ref: '#/components/schemas/TranslationMemoryThreshold' 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. type: array items: type: string example: "Use a friendly, diplomatic tone" tag_handling: $ref: '#/components/schemas/TagHandlingOption' tag_handling_version: $ref: '#/components/schemas/TagHandlingVersionOption' outline_detection: $ref: '#/components/schemas/OutlineDetectionOption' enable_beta_languages: description: |- This parameter is maintained for backward compatibility and has no effect. type: boolean default: false deprecated: true non_splitting_tags: description: Comma-separated list of XML tags which never split sentences. type: array items: type: string example: non_splitting_tag splitting_tags: description: Comma-separated list of XML tags which always cause splits. type: array items: type: string example: splitting_tag ignore_tags: description: Comma-separated list of XML tags that indicate text not to be translated. type: array items: type: string example: ignore_tag application/x-www-form-urlencoded: 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 many times in a single request, within the request size limit (128KiB). Translations are returned in the same order as they are requested. Each text in the array is translated independently — texts do not share context with each other. 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/PreserveFormattingOptionStr' formality: $ref: '#/components/schemas/Formality' model_type: $ref: '#/components/schemas/ModelType' glossary_id: description: |- Specify the glossary to use for the translation. **Important:** This requires the `source_lang` parameter to be set. The language pair of the glossary has to match the language pair of the request. Cannot be used together with `glossary_ids`. type: string example: def3a26b-3e84-45b3-84ae-0c0aaf3525f7 glossary_ids: description: |- Comma-separated list of up to 5 glossary IDs to use for the translation. Each glossary's matching terms are applied to the translation. May also be sent as a repeated parameter. **Important:** This requires the `source_lang` parameter to be set. Every listed glossary must contain a dictionary for the requested language pair. Cannot be used together with `glossary_id`. type: array maxItems: 5 items: type: string example: def3a26b-3e84-45b3-84ae-0c0aaf3525f7 translation_memory_id: $ref: '#/components/schemas/TranslationMemoryId' translation_memory_threshold: $ref: '#/components/schemas/TranslationMemoryThreshold' tag_handling: $ref: '#/components/schemas/TagHandlingOption' outline_detection: $ref: '#/components/schemas/OutlineDetectionOptionStr' enable_beta_languages: description: |- This parameter is maintained for backward compatibility and has no effect. type: boolean default: false deprecated: true non_splitting_tags: description: Comma-separated list of XML tags which never split sentences. type: array items: type: string example: non_splitting_tag splitting_tags: description: Comma-separated list of XML tags which always cause splits. type: array items: type: string example: splitting_tag ignore_tags: description: Comma-separated list of XML tags that indicate text not to be translated. type: array items: type: string example: ignore_tag 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: description: The language detected in the source text. It reflects the value of the `source_lang` parameter, when specified. type: string example: EN text: description: The translated text. type: string example: Hallo, Welt! 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 example: 42 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 tag_handling_version: description: The version of the tag handling algorithm used for the translation. Only present when the `tag_handling` parameter (`xml` or `html`) is set. If you don't specify `tag_handling_version`, this shows the default that was applied. type: string enum: - v2 - v1 example: v2 400: $ref: '#/components/responses/BadRequest' 403: $ref: '#/components/responses/ForbiddenScoped' 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 requestBody: required: true content: multipart/form-data: examples: Basic: summary: Basic Document Translation value: target_lang: DE file: '@document.docx' Watermark: summary: Adding a "Translated by DeepL" watermark (docx/pdf only) value: target_lang: DE file: '@document.pdf' enable_watermark: true Glossary: summary: Using a Glossary value: source_lang: EN target_lang: DE file: '@document.docx' glossary_id: '[yourGlossaryId]' MultipleGlossaries: summary: Using Multiple Glossaries value: source_lang: EN target_lang: DE file: '@document.docx' glossary_ids: '[yourGlossaryId1],[yourGlossaryId2]' StyleRule: summary: Using a Style Rule List value: source_lang: EN target_lang: DE file: '@document.docx' style_id: '[yourStyleId]' TranslationMemory: summary: Using a Translation Memory value: source_lang: EN target_lang: DE file: '@document.docx' translation_memory_id: '[yourTranslationMemoryId]' translation_memory_threshold: 75 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 (versions 1.2, 2.0, and 2.1) * `srt` - SRT Document * `idml` - Adobe InDesign Markup Language * `xml` - XML Document * `json` - JSON Document * `dita` - DITA topic (Darwin Information Typing Architecture) * `mif` - Adobe FrameMaker Interchange Format * `jpeg` / `jpg` / `png` - Image (currently in beta) 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. formality: $ref: '#/components/schemas/Formality' glossary_id: description: |- A unique ID assigned to a glossary. To check glossary support for a language pair, call `GET /v3/languages?resource=translate_document` and verify the `glossary` feature key is present on both the source and target language. Cannot be used together with `glossary_ids`. type: string example: def3a26b-3e84-45b3-84ae-0c0aaf3525f7 glossary_ids: description: |- Comma-separated list of up to 5 glossary IDs to use for the translation. Each glossary's matching terms are applied to the translated document. May also be sent as a repeated parameter. **Important:** This requires the `source_lang` parameter to be set. Every listed glossary must contain a dictionary for the requested language pair. Cannot be used together with `glossary_id`. type: array maxItems: 5 items: type: string example: def3a26b-3e84-45b3-84ae-0c0aaf3525f7 style_id: description: |- Specify the [style rule list](/docs/customize/using-style-rules) to use for the translation. **Important:** The target language has to match the language of the style rule list. type: string example: 7ff9bfd6-cd85-4190-8503-d6215a321519 translation_memory_id: $ref: '#/components/schemas/TranslationMemoryId' translation_memory_threshold: $ref: '#/components/schemas/TranslationMemoryThreshold' enable_watermark: description: |- When `true`, adds a "Translated by DeepL" watermark to the translated document. Only supported for `docx` and `pdf` output. For all other output formats the parameter is ignored and the document is returned without a watermark. type: boolean default: false enable_beta_languages: description: |- This parameter is maintained for backward compatibility and has no effect. type: boolean default: false deprecated: true 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 example: 04DE5AD98A02647D83285A36021911C6 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: 0CB0054F1C132C1625B392EADDA41CB754A742822F6877173029A6C487E7F60A example: document_id: 04DE5AD98A02647D83285A36021911C6 document_key: 0CB0054F1C132C1625B392EADDA41CB754A742822F6877173029A6C487E7F60A 400: $ref: '#/components/responses/BadRequest' 403: $ref: '#/components/responses/ForbiddenScoped' 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 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 example: 04DE5AD98A02647D83285A36021911C6 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 example: done 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 example: 1337 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 example: Only available if document status is error 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/ForbiddenScoped' 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 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/ForbiddenScoped' 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: deprecated: true tags: - ManageGlossaries summary: List Language Pairs Supported by Glossaries description: |- **Deprecated.** Use `GET /v3/languages?resource=glossary` instead, which returns per-language availability including source and target roles. 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 example: en target_lang: description: The language in which the target texts in the glossary are specified. type: string example: de example: supported_languages: - source_lang: de target_lang: en - source_lang: en target_lang: de 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' 415: $ref: '#/components/responses/UnsupportedMediaTypeGlossaries' 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: [ ] /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/ForbiddenGlossaries' 404: $ref: '#/components/responses/NotFound' 413: $ref: '#/components/responses/PayloadTooLarge' 415: $ref: '#/components/responses/UnsupportedMediaTypeGlossaries' 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' 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' 415: $ref: '#/components/responses/UnsupportedMediaTypeGlossaries' 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: [ ] /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 entry_count: 1 - source_lang: DE target_lang: EN entry_count: 2 creation_time: '2021-08-03T14:16:18.429Z' 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' 415: $ref: '#/components/responses/UnsupportedMediaTypeGlossaries' 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: [ ] 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' 415: $ref: '#/components/responses/UnsupportedMediaTypeGlossaries' 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. 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' 415: $ref: '#/components/responses/UnsupportedMediaTypeGlossaries' 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: [ ] /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: type: object properties: dictionaries: description: The dictionaries of the glossary, each with its entries in the requested format. type: array items: $ref: '#/components/schemas/MultilingualGlossaryEntries' 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' 415: $ref: '#/components/responses/UnsupportedMediaTypeGlossaries' 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: [ ] /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. 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' 415: $ref: '#/components/responses/UnsupportedMediaTypeGlossaries' 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: [ ] 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' 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' 415: $ref: '#/components/responses/UnsupportedMediaTypeGlossaries' 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/ForbiddenGlossaries' 404: $ref: '#/components/responses/NotFound' 413: $ref: '#/components/responses/PayloadTooLarge' 415: $ref: '#/components/responses/UnsupportedMediaTypeGlossaries' 429: $ref: '#/components/responses/TooManyRequests' 456: $ref: '#/components/responses/QuotaExceeded' 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 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' 415: $ref: '#/components/responses/UnsupportedMediaTypeGlossaries' 429: $ref: '#/components/responses/TooManyRequests' 456: $ref: '#/components/responses/QuotaExceeded' 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' 413: $ref: '#/components/responses/PayloadTooLarge' 415: $ref: '#/components/responses/UnsupportedMediaTypeGlossaries' 429: $ref: '#/components/responses/TooManyRequests' 456: $ref: '#/components/responses/QuotaExceeded' 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. 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' 415: $ref: '#/components/responses/UnsupportedMediaTypeGlossaries' 429: $ref: '#/components/responses/TooManyRequests' 456: $ref: '#/components/responses/QuotaExceeded' 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 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' 413: $ref: '#/components/responses/PayloadTooLarge' 415: $ref: '#/components/responses/UnsupportedMediaTypeGlossaries' 429: $ref: '#/components/responses/TooManyRequests' 456: $ref: '#/components/responses/QuotaExceeded' 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: Improve text 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 x-default: - this is a example sentence to imprve 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 x-default: - this is a example sentence to imprve 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 target_language: description: The target language specified by the request. type: string example: en-US text: description: The improved text. type: string example: This is a sample sentence to improve. 400: $ref: '#/components/responses/BadRequest' 403: $ref: '#/components/responses/ForbiddenScoped' 413: $ref: '#/components/responses/PayloadTooLarge' 415: description: Unsupported Content-Type. Use `application/json` or `application/x-www-form-urlencoded`. 429: $ref: '#/components/responses/TooManyRequests' 456: $ref: '#/components/responses/QuotaExceeded' 500: $ref: '#/components/responses/InternalServerError' 504: $ref: '#/components/responses/ServiceUnavailable' security: - auth_header: [ ] /v2/write/correct: post: tags: - CorrectText summary: Correct text description: |- Fix spelling and grammar errors in one or more texts. Unlike `/v2/write/rephrase`, this endpoint applies a minimal-change correction pass and does not rewrite the text for style or tone. operationId: correctText requestBody: required: true content: application/json: schema: type: object required: - text properties: text: description: Text to be corrected. Only UTF-8-encoded plain text is supported. Corrections are returned in the same order as they are requested. type: array x-default: - this is a example sentence to imprve items: type: string example: this is a example sentence to imprve target_lang: $ref: '#/components/schemas/TargetLanguageWrite' application/x-www-form-urlencoded: schema: type: object required: - text properties: text: description: Text to be corrected. Only UTF-8-encoded plain text is supported. Corrections are returned in the same order as they are requested. type: array x-default: - this is a example sentence to imprve items: type: string example: this is a example sentence to imprve target_lang: $ref: '#/components/schemas/TargetLanguageWrite' responses: 200: description: Successful text correction. 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 target_language: description: The target language specified by the request. type: string example: en-US text: description: The corrected text. type: string example: This is a sample sentence to improve. 400: $ref: '#/components/responses/BadRequest' 403: $ref: '#/components/responses/ForbiddenScoped' 413: $ref: '#/components/responses/PayloadTooLarge' 415: description: Unsupported Content-Type. Use `application/json` or `application/x-www-form-urlencoded`. 429: $ref: '#/components/responses/TooManyRequests' 456: $ref: '#/components/responses/QuotaExceeded' 500: $ref: '#/components/responses/InternalServerError' 504: $ref: '#/components/responses/ServiceUnavailable' security: - auth_header: [ ] /v2/usage: get: tags: - MetaInformation summary: Check Usage and Limits 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: speechToText billing_unit: minutes api_key_unit_count: 30 account_unit_count: 30 api_key_character_count: 0 character_count: 0 - product_type: speechToSpeech billing_unit: minutes api_key_unit_count: 12 account_unit_count: 12 api_key_character_count: 0 character_count: 0 api_key_character_count: 636 api_key_character_limit: 1000000000000 speech_to_text_milliseconds_count: 0 speech_to_text_milliseconds_limit: 0 speech_to_text_minutes_count: 30 speech_to_text_minutes_limit: 600 speech_to_speech_minutes_count: 12 speech_to_speech_minutes_limit: 600 start_time: '2025-05-13T09:18:42Z' end_time: '2025-06-13T09:18:42Z' 400: $ref: '#/components/responses/BadRequest' 403: $ref: '#/components/responses/ForbiddenScoped' 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: deprecated: true tags: - MetaInformation summary: Retrieve Supported Languages description: |- **Deprecated.** Use `GET /v3/languages?resource=translate_text` (or the appropriate resource) instead. See the [migration guide](https://developers.deepl.com/docs/languages/migrating-from-v2-languages) for details. operationId: getLanguagesV2 parameters: - name: type in: query schema: type: string enum: - source - target default: source description: Supported values are "source" or "target". If type parameter is not included, defaults to "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 example: DE name: description: Name of the language in English. type: string example: German supports_formality: description: Denotes formality support in case of a target language listing. type: boolean example: true example: - language: AR name: Arabic - language: BG name: Bulgarian - language: CS name: Czech - language: DA name: Danish - language: DE name: German - language: EL name: Greek - language: EN name: English - language: ES name: Spanish - language: ET name: Estonian - language: FI name: Finnish - language: FR name: French - language: HE name: Hebrew - language: HU name: Hungarian - language: ID name: Indonesian - language: IT name: Italian - language: JA name: Japanese - language: KO name: Korean - language: LT name: Lithuanian - language: LV name: Latvian - language: NB name: Norwegian - language: NL name: Dutch - language: PL name: Polish - language: PT name: Portuguese - language: RO name: Romanian - language: RU name: Russian - language: SK name: Slovak - language: SL name: Slovenian - language: SV name: Swedish - language: TH name: Thai - language: TR name: Turkish - language: UK name: Ukrainian - language: VI name: Vietnamese - language: ZH name: Chinese 400: $ref: '#/components/responses/BadRequest' 403: $ref: '#/components/responses/ForbiddenScoped' 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: [ ] /v3/spoken-terms: post: tags: - ManageSpokenTerms summary: Create Spoken Terms collection operationId: createSpokenTerms description: Create a new Spoken Terms collection with one or more term lists. Each term list contains terms for a single language. The number of collections per account is limited by your plan. requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CreateSpokenTermsParameters' examples: Basic: value: name: Technical Terms term_lists: - lang: en entries: "DeepL\nAPI\nwebhook" application/x-www-form-urlencoded: schema: $ref: '#/components/schemas/CreateSpokenTermsParameters' responses: 201: description: Successfully created Spoken Terms collection. headers: X-Trace-ID: $ref: '#/components/headers/X-Trace-ID' content: application/json: schema: $ref: '#/components/schemas/SpokenTerms' 400: $ref: '#/components/responses/BadRequestSpokenTerms' 401: $ref: '#/components/responses/Unauthorized' 403: $ref: '#/components/responses/ForbiddenSpokenTerms' 413: $ref: '#/components/responses/PayloadTooLarge' 415: $ref: '#/components/responses/UnsupportedMediaType' 429: $ref: '#/components/responses/TooManyRequests' 456: $ref: '#/components/responses/QuotaExceededSpokenTerms' security: - auth_header: [ ] get: tags: - ManageSpokenTerms summary: List all Spoken Terms collections operationId: listSpokenTerms description: List all Spoken Terms collections and their metadata, but not the actual terms. responses: 200: description: JSON object containing all Spoken Terms collections. headers: X-Trace-ID: $ref: '#/components/headers/X-Trace-ID' content: application/json: schema: type: object properties: spoken_terms: type: array items: $ref: '#/components/schemas/SpokenTerms' example: spoken_terms: - spoken_terms_id: def3a26b-3e84-45b3-84ae-0c0aaf3525f7 name: Technical Terms term_lists: - lang: en entry_count: 3 creation_time: '2025-08-03T14:16:18.329Z' 401: $ref: '#/components/responses/Unauthorized' 403: $ref: '#/components/responses/ForbiddenSpokenTerms' 429: $ref: '#/components/responses/TooManyRequests' security: - auth_header: [ ] /v3/spoken-terms/{spoken_terms_id}: get: tags: - ManageSpokenTerms summary: Retrieve Spoken Terms collection details description: Retrieve metadata for a Spoken Terms collection, including term list information but not the actual terms. operationId: getSpokenTerms parameters: - $ref: '#/components/parameters/SpokenTermsID' responses: 200: description: JSON object containing the Spoken Terms metadata. headers: X-Trace-ID: $ref: '#/components/headers/X-Trace-ID' content: application/json: schema: $ref: '#/components/schemas/SpokenTerms' example: spoken_terms_id: def3a26b-3e84-45b3-84ae-0c0aaf3525f7 name: Technical Terms term_lists: - lang: en entry_count: 3 creation_time: '2025-08-03T14:16:18.329Z' 400: $ref: '#/components/responses/BadRequestSpokenTerms' 401: $ref: '#/components/responses/Unauthorized' 403: $ref: '#/components/responses/ForbiddenSpokenTerms' 404: $ref: '#/components/responses/NotFound' 429: $ref: '#/components/responses/TooManyRequests' security: - auth_header: [ ] patch: tags: - ManageSpokenTerms summary: Edit Spoken Terms collection details description: Update the name of a Spoken Terms collection or merge new entries into an existing term list. operationId: patchSpokenTerms parameters: - $ref: '#/components/parameters/SpokenTermsID' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/PatchSpokenTermsParameters' examples: UpdateName: value: name: Updated Technical Terms MergeEntries: value: term_lists: - lang: en entries: "authentication\nendpoint" application/x-www-form-urlencoded: schema: $ref: '#/components/schemas/PatchSpokenTermsParameters' responses: 200: description: Successfully updated Spoken Terms collection. headers: X-Trace-ID: $ref: '#/components/headers/X-Trace-ID' content: application/json: schema: $ref: '#/components/schemas/SpokenTerms' 400: $ref: '#/components/responses/BadRequestSpokenTerms' 401: $ref: '#/components/responses/Unauthorized' 403: $ref: '#/components/responses/ForbiddenSpokenTerms' 404: $ref: '#/components/responses/NotFound' 413: $ref: '#/components/responses/PayloadTooLarge' 415: $ref: '#/components/responses/UnsupportedMediaType' 429: $ref: '#/components/responses/TooManyRequests' security: - auth_header: [ ] delete: tags: - ManageSpokenTerms summary: Delete Spoken Terms collection description: Delete the entire Spoken Terms collection. operationId: deleteSpokenTerms parameters: - $ref: '#/components/parameters/SpokenTermsID' responses: 204: description: Successfully deleted Spoken Terms collection. 400: $ref: '#/components/responses/BadRequestSpokenTerms' 401: $ref: '#/components/responses/Unauthorized' 403: $ref: '#/components/responses/ForbiddenSpokenTerms' 404: $ref: '#/components/responses/NotFound' 429: $ref: '#/components/responses/TooManyRequests' security: - auth_header: [ ] /v3/spoken-terms/{spoken_terms_id}/entries: get: tags: - ManageSpokenTerms summary: Retrieve Spoken Terms entries description: Retrieve the actual terms for a specific language from a Spoken Terms collection. operationId: getSpokenTermsEntries parameters: - $ref: '#/components/parameters/SpokenTermsID' - name: lang in: query required: true description: The language code (ISO 639-1) for the term list to retrieve. schema: type: string example: en responses: 200: description: JSON object containing the term list entries. headers: X-Trace-ID: $ref: '#/components/headers/X-Trace-ID' content: application/json: schema: $ref: '#/components/schemas/SpokenTermsEntries' example: lang: en entries: "DeepL\nAPI\nwebhook" 400: $ref: '#/components/responses/BadRequestSpokenTerms' 401: $ref: '#/components/responses/Unauthorized' 403: $ref: '#/components/responses/ForbiddenSpokenTerms' 404: $ref: '#/components/responses/NotFound' 429: $ref: '#/components/responses/TooManyRequests' security: - auth_header: [ ] /v3/spoken-terms/{spoken_terms_id}/term-lists: put: tags: - ManageSpokenTerms summary: Replace or create a term list description: Replace an existing term list for a language, or create a new one if it doesn't exist. operationId: putSpokenTermsList parameters: - $ref: '#/components/parameters/SpokenTermsID' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/PutSpokenTermsListParameters' examples: Basic: value: lang: en entries: "DeepL\nAPI\nwebhook\nintegration" application/x-www-form-urlencoded: schema: $ref: '#/components/schemas/PutSpokenTermsListParameters' responses: 200: description: Successfully replaced or created term list. headers: X-Trace-ID: $ref: '#/components/headers/X-Trace-ID' content: application/json: schema: $ref: '#/components/schemas/SpokenTermsList' 400: $ref: '#/components/responses/BadRequestSpokenTerms' 401: $ref: '#/components/responses/Unauthorized' 403: $ref: '#/components/responses/ForbiddenSpokenTerms' 404: $ref: '#/components/responses/NotFound' 413: $ref: '#/components/responses/PayloadTooLarge' 415: $ref: '#/components/responses/UnsupportedMediaType' 429: $ref: '#/components/responses/TooManyRequests' security: - auth_header: [ ] delete: tags: - ManageSpokenTerms summary: Delete a term list description: Delete a term list for a specific language from the Spoken Terms collection. operationId: deleteSpokenTermsList parameters: - $ref: '#/components/parameters/SpokenTermsID' - name: lang in: query required: true description: The language code (ISO 639-1) for the term list to delete. schema: type: string example: en responses: 204: description: Successfully deleted term list. 400: $ref: '#/components/responses/BadRequestSpokenTerms' 401: $ref: '#/components/responses/Unauthorized' 403: $ref: '#/components/responses/ForbiddenSpokenTerms' 404: $ref: '#/components/responses/NotFound' 429: $ref: '#/components/responses/TooManyRequests' security: - auth_header: [ ] /v3/languages/resources: get: tags: - MetaInformation summary: Retrieve Language Resources operationId: getLanguageResources description: |- Returns all DeepL API resources and the features they support. For each feature, the response indicates which languages must support it for the feature to be available — source only (`needs_source_support`), target only (`needs_target_support`), or both. This allows clients to determine feature availability for a language pair by checking the appropriate language's `features` object returned by `GET /v3/languages`. responses: 200: description: JSON array where each item represents a DeepL API product. headers: X-Trace-ID: $ref: '#/components/headers/X-Trace-ID' content: application/json: schema: type: array items: type: object required: - name - features properties: name: description: The resource identifier. type: string enum: - translate_text - translate_document - glossary - voice - write - style_rules - translation_memory example: translate_text features: description: |- Features supported by this resource. Each feature indicates which languages must support it for the feature to be available — source, target, or both. type: array items: type: object required: - name properties: name: description: The feature identifier, corresponding to keys in the `features` object returned by `GET /v3/languages`. type: string enum: - formality - style_rules - tag_handling - glossary - writing_style - tone - auto_detection - transcription - translated_speech - spoken_terms - translation_memory needs_source_support: description: If `true`, the source language must support this feature for it to be available. Defaults to `false` if absent. type: boolean needs_target_support: description: If `true`, the target language must support this feature for it to be available. Defaults to `false` if absent. type: boolean example: - name: translate_text features: - name: formality needs_target_support: true - name: style_rules needs_target_support: true - name: tag_handling needs_source_support: true needs_target_support: true - name: glossary needs_source_support: true needs_target_support: true - name: auto_detection needs_source_support: true - name: voice features: - name: glossary needs_source_support: true needs_target_support: true - name: style_rules features: [] 400: $ref: '#/components/responses/BadRequest' 401: $ref: '#/components/responses/Unauthorized' 403: $ref: '#/components/responses/ForbiddenScoped' 429: $ref: '#/components/responses/TooManyRequests' 500: $ref: '#/components/responses/InternalServerError' 503: $ref: '#/components/responses/ServiceUnavailable' security: - auth_header: [] /v3/languages: get: tags: - MetaInformation summary: Retrieve Languages operationId: getLanguages description: |- Returns languages supported by the specified DeepL API resource. Each language indicates whether it can be used as a source language, a target language, or both, along with the features it supports for that resource. parameters: - name: resource in: query required: true schema: type: string enum: - translate_text - translate_document - glossary - voice - write - style_rules - translation_memory example: translate_text x-default: translate_text description: |- The resource to retrieve languages for. Supported values: `translate_text`, `translate_document`, `glossary`, `voice`, `write`, `style_rules`, `translation_memory`. - name: include in: query required: false schema: type: array items: type: string enum: - beta - external style: form explode: true description: |- Controls which languages and features are included in the response. By default, only stable languages and features are returned. Values can be combined with repeated parameters (e.g. `?include=beta&include=external`). - `beta`: Include languages and features in beta, in addition to stable - `external`: Include features that rely on third-party service providers 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: - lang - name - usable_as_source - usable_as_target - features - status properties: lang: description: The language code (BCP 47). type: string example: de name: description: Name of the language in English. type: string example: German usable_as_source: description: Whether this language can be used as a source language with the specified resource. type: boolean usable_as_target: description: Whether this language can be used as a target language with the specified resource. type: boolean status: description: Availability status of this language. type: string enum: - stable - beta - early_access example: stable features: description: |- Features supported for this language with the specified resource. Always present; empty object if no optional features are supported. Each key is a feature name; the value is an object with at least a `status` field. Consult `GET /v3/languages/resources` to determine whether a feature must be present on the source language, target language, or both for a given resource. type: object additionalProperties: type: object required: - status properties: status: description: Availability status of this feature for this language. type: string enum: - stable - beta - early_access example: formality: status: stable tag_handling: status: stable glossary: status: stable examples: translateTextLanguages: summary: Languages for text translation value: - lang: de name: German usable_as_source: true usable_as_target: true status: stable features: formality: status: stable tag_handling: status: stable glossary: status: stable - lang: en name: English usable_as_source: true usable_as_target: false status: stable features: tag_handling: status: stable glossary: status: stable - lang: en-US name: English (American) usable_as_source: false usable_as_target: true status: stable features: tag_handling: status: stable glossary: status: stable 400: $ref: '#/components/responses/BadRequest' 401: $ref: '#/components/responses/Unauthorized' 403: $ref: '#/components/responses/ForbiddenScoped' 429: $ref: '#/components/responses/TooManyRequests' 500: $ref: '#/components/responses/InternalServerError' 503: $ref: '#/components/responses/ServiceUnavailable' security: - auth_header: [] /v3/translation_memories: get: tags: - TranslationMemories summary: List translation memories operationId: listTranslationMemories description: |- Retrieve a list of translation memories associated with the authenticated account. 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 translation memories. - name: page_size in: query schema: type: integer default: 10 minimum: 1 maximum: 100 description: The maximum number of translation memories to return. Values above 100 are reduced to 100. responses: 200: description: Returns a list of translation memories. headers: X-Trace-ID: $ref: '#/components/headers/X-Trace-ID' content: application/json: schema: type: object properties: translation_memories: type: array items: $ref: '#/components/schemas/TranslationMemory' total_count: type: integer description: The total number of translation memories available. example: 2 examples: Basic: value: translation_memories: - translation_memory_id: a74d88fb-ed2a-4943-a664-a4512398b994 name: Legal source_language: en target_languages: - es - de segment_count: 3542 - translation_memory_id: 855d36ab-6112-4ef5-8868-0d69bc4d826a name: Medical terms source_language: de target_languages: - fr - ja - zh segment_count: 23 total_count: 2 400: $ref: '#/components/responses/BadRequest' 401: $ref: '#/components/responses/Unauthorized' 403: $ref: '#/components/responses/ForbiddenScoped' 429: $ref: '#/components/responses/TooManyRequests' 500: $ref: '#/components/responses/InternalServerError' 503: $ref: '#/components/responses/ServiceUnavailable' security: - auth_header: [] /v3/translation_memories/import: post: tags: - TranslationMemories summary: Import a translation memory operationId: createTranslationMemoryImport description: |- Create a translation memory by importing a TMX file. This endpoint does not accept the file itself. It returns a short-lived `upload_url`, and you upload the TMX file to that URL with a separate `PUT` request. Processing starts automatically once the upload completes, so there is no third call to confirm it. 1. `POST /v3/translation_memories/import` with the file's name and size. The response returns a `job_id`, an `upload_url`, and the `expires_at` time after which the URL stops working. 2. `PUT` the TMX file to `upload_url`. Do not send your `Authorization` header on this request, because the URL is already signed. 3. Poll [Retrieve an import or export job](/api-reference/translation-memory/retrieve-a-translation-memory-job) until the status is `completed`. The new `translation_memory_id` is on the job result. Requires an API key with the `translation_memories:write` scope. requestBody: required: true content: application/json: schema: type: object required: - source_file properties: source_file: type: object required: - file_name - content_length properties: file_name: description: |- The name of the TMX file you intend to upload, including its extension. At most 100 characters. type: string maxLength: 100 example: legal.tmx content_type: description: |- The MIME type of the file. Defaults to `application/xml`, which is correct for TMX. TMX is currently the only supported import format. At most 127 characters. type: string default: application/xml maxLength: 127 example: application/xml content_length: description: |- The size of the file in bytes. Must be greater than 0 and at most 1 GB. An oversize value is rejected with `400 Bad Request`. type: integer format: int64 minimum: 1 example: 1024 parameters: type: object properties: display_name: description: |- The name to give the new translation memory. If you omit this, the translation memory is created without a name. type: string example: Legal examples: Basic: value: source_file: file_name: legal.tmx content_type: application/xml content_length: 1024 parameters: display_name: Legal responses: 202: description: |- The import job was created. Upload the file to `upload_url` before `expires_at`. headers: X-Trace-ID: $ref: '#/components/headers/X-Trace-ID' content: application/json: schema: type: object required: - job_id - upload_url - expires_at properties: job_id: description: The identifier of the import job. Use it to poll the job's status. type: string format: uuid example: 0f8b6c1e-4d2a-4c77-9a3e-1b5d8c9e2f40 upload_url: description: |- A signed URL to `PUT` the TMX file to. Do not send your `Authorization` header with the upload request. type: string format: uri example: https://assets.deepl.com/upload/0f8b6c1e-4d2a-4c77-9a3e-1b5d8c9e2f40 expires_at: description: |- The time the `upload_url` stops accepting uploads, in the ISO 8601-1:2019 format. After this time, create a new import job. type: string format: date-time example: '2026-08-06T15:34:25.223Z' examples: Basic: value: job_id: 0f8b6c1e-4d2a-4c77-9a3e-1b5d8c9e2f40 upload_url: https://assets.deepl.com/upload/0f8b6c1e-4d2a-4c77-9a3e-1b5d8c9e2f40 expires_at: '2026-08-06T15:34:25.223Z' 400: $ref: '#/components/responses/BadRequest' 401: $ref: '#/components/responses/Unauthorized' 403: $ref: '#/components/responses/ForbiddenScoped' 429: $ref: '#/components/responses/TooManyRequests' 456: description: |- You have reached the maximum number of translation memories for your account. Delete a translation memory before creating another one. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' 500: $ref: '#/components/responses/InternalServerError' 503: $ref: '#/components/responses/ServiceUnavailable' security: - auth_header: [] /v3/translation_memories/jobs/{job_id}: get: tags: - TranslationMemories summary: Retrieve an import or export job operationId: getTranslationMemoryJob description: |- Retrieve the status of a translation memory import or export job. Poll this endpoint after creating a job. The `operation` field tells you which kind of job it is, and the single entry in `results` carries the status and, once the job finishes, its output: the new `translation_memory_id` for an import, or a `download_url` for an export. Requires an API key with the `translation_memories:read` scope. parameters: - name: job_id in: path required: true schema: type: string format: uuid description: The identifier of the job, returned when you created the import or export. example: 0f8b6c1e-4d2a-4c77-9a3e-1b5d8c9e2f40 responses: 200: description: Returns the current state of the job. headers: X-Trace-ID: $ref: '#/components/headers/X-Trace-ID' content: application/json: schema: $ref: '#/components/schemas/TranslationMemoryJob' examples: Import awaiting upload: value: job_id: 0f8b6c1e-4d2a-4c77-9a3e-1b5d8c9e2f40 product: translation_memory operation: import creation_time: '2026-08-06T15:04:25.223Z' updated_time: '2026-08-06T15:04:25.223Z' source_file: content_type: application/xml content_length: 1024 parameters: display_name: Legal results: - status: awaiting_input status_metadata: required_action: Waiting for upload Import completed: value: job_id: 0f8b6c1e-4d2a-4c77-9a3e-1b5d8c9e2f40 product: translation_memory operation: import creation_time: '2026-08-06T15:04:25.223Z' updated_time: '2026-08-06T15:06:11.418Z' source_file: content_type: application/xml content_length: 1024 parameters: display_name: Legal results: - status: completed translation_memory_id: a74d88fb-ed2a-4943-a664-a4512398b994 skipped_segment_count: 12 Export completed: value: job_id: 7c2e5a91-3b8d-4f16-8e0a-6d4c2b7f9a13 product: translation_memory operation: export creation_time: '2026-08-06T15:04:25.223Z' updated_time: '2026-08-06T15:05:02.771Z' parameters: translation_memory_id: a74d88fb-ed2a-4943-a664-a4512398b994 results: - status: completed download_url: https://assets.deepl.com/download/7c2e5a91-3b8d-4f16-8e0a-6d4c2b7f9a13 expires_at: '2026-08-06T16:05:02.771Z' Failed: value: job_id: 0f8b6c1e-4d2a-4c77-9a3e-1b5d8c9e2f40 product: translation_memory operation: import creation_time: '2026-08-06T15:04:25.223Z' updated_time: '2026-08-06T15:04:58.102Z' source_file: content_type: application/xml content_length: 1024 parameters: display_name: Legal results: - status: failed error: message: The uploaded file is not valid TMX. 400: $ref: '#/components/responses/BadRequest' 401: $ref: '#/components/responses/Unauthorized' 403: $ref: '#/components/responses/ForbiddenScoped' 404: description: The job could not be found. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' 429: $ref: '#/components/responses/TooManyRequests' 500: $ref: '#/components/responses/InternalServerError' 503: $ref: '#/components/responses/ServiceUnavailable' security: - auth_header: [] /v3/translation_memories/{translation_memory_id}: get: tags: - TranslationMemories summary: Retrieve a translation memory operationId: getTranslationMemory description: |- Retrieve a single translation memory by its ID, including its languages and segment count. To read the stored segments themselves, use [List translation memory segments](/api-reference/translation-memory/list-translation-memory-segments). Requires an API key with the `translation_memories:read` scope. parameters: - name: translation_memory_id in: path required: true schema: $ref: '#/components/schemas/TranslationMemoryId' description: The ID of the translation memory to retrieve. responses: 200: description: Returns the translation memory. headers: X-Trace-ID: $ref: '#/components/headers/X-Trace-ID' content: application/json: schema: $ref: '#/components/schemas/TranslationMemory' examples: Basic: value: translation_memory_id: a74d88fb-ed2a-4943-a664-a4512398b994 name: Legal source_language: en target_languages: - es - de segment_count: 3542 creation_time: '2026-04-01T16:34:25.223Z' updated_time: '2026-08-06T09:12:44.108Z' 400: $ref: '#/components/responses/BadRequest' 401: $ref: '#/components/responses/Unauthorized' 403: $ref: '#/components/responses/ForbiddenScoped' 404: description: |- The translation memory could not be found. This is also returned for a translation memory that belongs to another account. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' 429: $ref: '#/components/responses/TooManyRequests' 500: $ref: '#/components/responses/InternalServerError' 503: $ref: '#/components/responses/ServiceUnavailable' security: - auth_header: [] delete: tags: - TranslationMemories summary: Delete a translation memory operationId: deleteTranslationMemory description: |- Delete a translation memory and all of its segments. Deletion is permanent and cannot be undone. Export the translation memory first if you need a copy of its contents. Translation requests that pass the deleted `translation_memory_id` fail after this call, so update your integration before deleting. Requires an API key with the `translation_memories:write` scope. parameters: - name: translation_memory_id in: path required: true schema: $ref: '#/components/schemas/TranslationMemoryId' description: The ID of the translation memory to delete. responses: 204: description: The translation memory was deleted. The response has no body. headers: X-Trace-ID: $ref: '#/components/headers/X-Trace-ID' 400: $ref: '#/components/responses/BadRequest' 401: $ref: '#/components/responses/Unauthorized' 403: $ref: '#/components/responses/ForbiddenScoped' 404: description: |- The translation memory could not be found. This is also returned for a translation memory that belongs to another account. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' 429: $ref: '#/components/responses/TooManyRequests' 500: $ref: '#/components/responses/InternalServerError' 503: $ref: '#/components/responses/ServiceUnavailable' security: - auth_header: [] /v3/translation_memories/{translation_memory_id}/segments: get: tags: - TranslationMemories summary: List translation memory segments operationId: getTranslationMemorySegments description: |- List the segments stored in a translation memory, one page at a time. Each entry is a source segment with its translations in every target language. This endpoint uses cursor-based pagination rather than the numbered pages used by [List translation memories](/api-reference/translation-memory/list-translation-memories). Omit `page_cursor` on your first call, then pass the `next_page_cursor` from each response to get the following page. When a response has no `next_page_cursor`, you have reached the last page. Requires an API key with the `translation_memories:read` scope. parameters: - name: translation_memory_id in: path required: true schema: $ref: '#/components/schemas/TranslationMemoryId' description: The ID of the translation memory whose segments you want to list. - name: page_size in: query schema: type: integer default: 50 minimum: 1 maximum: 100 description: |- The maximum number of segments to return per page. Values above 100 are reduced to 100. - name: page_cursor in: query schema: type: string description: |- The `next_page_cursor` from a previous response. Omit this on your first call. Treat the value as opaque: do not build or modify it yourself. - name: filter_text in: query schema: type: string minLength: 2 description: |- Return only segments where this text appears in the source or in any target translation. Must be at least 2 characters. - name: filter_case_sensitive in: query schema: type: boolean default: false description: Whether `filter_text` is matched case-sensitively. responses: 200: description: Returns a page of segments. headers: X-Trace-ID: $ref: '#/components/headers/X-Trace-ID' content: application/json: schema: type: object required: - segments - segment_count properties: segments: description: The segments on this page. type: array items: $ref: '#/components/schemas/TranslationMemorySegment' segment_count: description: |- The total number of segments in the translation memory. This is not reduced by `filter_text`, so a filtered request still reports the full count. Do not use it to predict how many results a filtered query returns. type: integer example: 3542 next_page_cursor: description: |- The cursor to pass as `page_cursor` to retrieve the next page. Absent on the last page. type: string example: eyJvZmZzZXQiOjUwfQ examples: Basic: value: segments: - source_segment_id: 4f1c2d3e-8a9b-4c5d-9e6f-7a8b9c0d1e2f source_text: This agreement is governed by the laws of Germany. creation_time: '2026-04-01T16:34:25.223Z' updated_time: '2026-04-01T16:34:25.223Z' last_used_time: '2026-08-05T11:02:18.771Z' targets: - target_segment_id: 9b8a7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d target_language: de target_text: Dieser Vertrag unterliegt dem Recht der Bundesrepublik Deutschland. creation_time: '2026-04-01T16:34:25.223Z' updated_time: '2026-04-01T16:34:25.223Z' last_used_time: '2026-08-05T11:02:18.771Z' - target_segment_id: 2c3d4e5f-6a7b-4c8d-9e0f-1a2b3c4d5e6f target_language: es target_text: Este contrato se rige por las leyes de Alemania. creation_time: '2026-04-01T16:34:25.223Z' updated_time: '2026-04-01T16:34:25.223Z' last_used_time: '2026-07-22T08:41:05.330Z' segment_count: 3542 next_page_cursor: eyJvZmZzZXQiOjUwfQ Last page: value: segments: - source_segment_id: 7a8b9c0d-1e2f-4a3b-8c4d-5e6f7a8b9c0d source_text: Termination requires 30 days written notice. creation_time: '2026-04-01T16:34:25.223Z' updated_time: '2026-04-01T16:34:25.223Z' last_used_time: '2026-08-01T14:20:09.512Z' targets: - target_segment_id: 0d1e2f3a-4b5c-4d6e-8f7a-8b9c0d1e2f3a target_language: de target_text: Die Kündigung erfordert eine schriftliche Frist von 30 Tagen. creation_time: '2026-04-01T16:34:25.223Z' updated_time: '2026-04-01T16:34:25.223Z' last_used_time: '2026-08-01T14:20:09.512Z' segment_count: 3542 400: $ref: '#/components/responses/BadRequest' 401: $ref: '#/components/responses/Unauthorized' 403: $ref: '#/components/responses/ForbiddenScoped' 404: description: |- The translation memory could not be found. This is also returned for a translation memory that belongs to another account. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' 429: $ref: '#/components/responses/TooManyRequests' 500: $ref: '#/components/responses/InternalServerError' 503: $ref: '#/components/responses/ServiceUnavailable' security: - auth_header: [] /v3/translation_memories/{translation_memory_id}/export: post: tags: - TranslationMemories summary: Export a translation memory operationId: createTranslationMemoryExport description: |- Export a translation memory as a TMX file. The export runs as a background job. Poll [Retrieve an import or export job](/api-reference/translation-memory/retrieve-a-translation-memory-job) until the status is `completed`, then download the file from the `download_url` on the job result. That URL is short-lived, so download the file rather than storing the link. If a recent export of the same translation memory is still available, DeepL reuses it and returns `200 OK` with that job instead of starting a new one. Handle both `200` and `202` as success. If a different export of the same translation memory is still running, the request returns `409 Conflict`. Requires an API key with the `translation_memories:read` scope. parameters: - name: translation_memory_id in: path required: true schema: $ref: '#/components/schemas/TranslationMemoryId' description: The ID of the translation memory to export. responses: 200: description: An existing export was reused. Poll the returned `job_id` for the download URL. headers: X-Trace-ID: $ref: '#/components/headers/X-Trace-ID' content: application/json: schema: $ref: '#/components/schemas/CreateTranslationMemoryExport' examples: Basic: value: job_id: 7c2e5a91-3b8d-4f16-8e0a-6d4c2b7f9a13 parameters: translation_memory_id: a74d88fb-ed2a-4943-a664-a4512398b994 202: description: The export job was created. Poll the returned `job_id` for the download URL. headers: X-Trace-ID: $ref: '#/components/headers/X-Trace-ID' content: application/json: schema: $ref: '#/components/schemas/CreateTranslationMemoryExport' examples: Basic: value: job_id: 7c2e5a91-3b8d-4f16-8e0a-6d4c2b7f9a13 parameters: translation_memory_id: a74d88fb-ed2a-4943-a664-a4512398b994 400: $ref: '#/components/responses/BadRequest' 401: $ref: '#/components/responses/Unauthorized' 403: $ref: '#/components/responses/ForbiddenScoped' 404: description: |- The translation memory could not be found. This is also returned for a translation memory that belongs to another account. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' 409: description: |- An export of this translation memory is already in progress. Poll that job instead of starting another export. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' 429: $ref: '#/components/responses/TooManyRequests' 500: $ref: '#/components/responses/InternalServerError' 503: $ref: '#/components/responses/ServiceUnavailable' security: - auth_header: [] /v3/style_rules: get: 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: description: JSON object containing the style rule lists. 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' 400: $ref: '#/components/responses/BadRequest' 401: $ref: '#/components/responses/Unauthorized' 403: $ref: '#/components/responses/ForbiddenScoped' 429: $ref: '#/components/responses/TooManyRequests' 500: $ref: '#/components/responses/InternalServerError' 503: $ref: '#/components/responses/ServiceUnavailable' security: - auth_header: [] post: summary: Create a style rule list operationId: createStyleRuleList requestBody: required: true content: application/json: schema: type: object required: - name - language properties: name: $ref: '#/components/schemas/StyleRuleName' x-default: My style rules language: $ref: '#/components/schemas/StyleRuleLanguage' x-default: de configured_rules: $ref: '#/components/schemas/ConfiguredRules' custom_instructions: type: array description: Array of custom instruction objects maxItems: 200 items: type: object required: - label - prompt properties: label: type: string description: Label for the custom instruction prompt: type: string description: Instruction text maxLength: 300 source_language: type: string description: Optional source language code example: name: "My style rules" language: "de" configured_rules: style_and_tone: abbreviations: "use_abbreviations_and_symbols" short_vs_long_words: "use_short_words" punctuation: apostrophe: "use_curly_apostrophes" custom_instructions: - label: "Currency custom instruction" prompt: "Have currency symbols before the numerical value (e.g. $100, €100)" source_language: "en" 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/ForbiddenScoped' 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: summary: Get a style rule list operationId: getStyleRuleList parameters: - name: style_id in: path required: true schema: type: string description: The ID of the style rule list responses: 200: description: Style rule list details 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/ForbiddenScoped' 404: $ref: '#/components/responses/NotFound' 429: $ref: '#/components/responses/TooManyRequests' 500: $ref: '#/components/responses/InternalServerError' 503: $ref: '#/components/responses/ServiceUnavailable' security: - auth_header: [] patch: summary: Update a style rule list's name operationId: updateStyleRuleList parameters: - name: style_id in: path required: true schema: type: string description: The ID of the style rule list requestBody: required: true content: application/json: schema: type: object properties: name: $ref: '#/components/schemas/StyleRuleName' 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/ForbiddenScoped' 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: summary: Delete a style rule list operationId: deleteStyleRuleList parameters: - name: style_id in: path required: true schema: type: string description: The ID of the style rule list responses: 204: description: Style rule list deleted successfully headers: X-Trace-ID: $ref: '#/components/headers/X-Trace-ID' 400: $ref: '#/components/responses/BadRequest' 401: $ref: '#/components/responses/Unauthorized' 403: $ref: '#/components/responses/ForbiddenScoped' 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: summary: Replace configured rules for a style rule list operationId: updateStyleRuleConfiguredRules parameters: - name: style_id in: path required: true schema: type: string description: The ID of the style rule list 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/ForbiddenScoped' 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: summary: Create a custom instruction operationId: createCustomInstruction parameters: - name: style_id in: path required: true schema: type: string description: The ID of the style rule list requestBody: required: true content: application/json: schema: type: object required: - label - prompt properties: label: type: string description: Label for the custom instruction maxLength: 100 x-default: Currency custom instruction prompt: type: string description: Instruction text maxLength: 300 x-default: "Have currency symbols before the numerical value (e.g. $100, €100)" source_language: type: string description: Optional source language code example: label: "Currency custom instruction" prompt: "Have currency symbols before the numerical value (e.g. $100, €100)" 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/ForbiddenScoped' 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: summary: Get a custom instruction operationId: getCustomInstruction parameters: - name: style_id in: path required: true schema: type: string description: The ID of the style rule list - name: instruction_id in: path required: true schema: type: string description: The ID of the custom instruction responses: 200: description: Custom instruction details 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/ForbiddenScoped' 404: $ref: '#/components/responses/NotFound' 429: $ref: '#/components/responses/TooManyRequests' 500: $ref: '#/components/responses/InternalServerError' 503: $ref: '#/components/responses/ServiceUnavailable' security: - auth_header: [] put: summary: Replace a custom instruction operationId: updateCustomInstruction parameters: - name: style_id in: path required: true schema: type: string description: The ID of the style rule list - name: instruction_id in: path required: true schema: type: string description: The ID of the custom instruction requestBody: required: true content: application/json: schema: type: object required: - label - prompt properties: label: type: string description: Updated label for the custom instruction maxLength: 100 prompt: type: string description: Updated instruction text maxLength: 300 source_language: type: string description: Optional source language code 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/ForbiddenScoped' 404: $ref: '#/components/responses/NotFound' 429: $ref: '#/components/responses/TooManyRequests' 500: $ref: '#/components/responses/InternalServerError' 503: $ref: '#/components/responses/ServiceUnavailable' security: - auth_header: [] delete: summary: Delete a custom instruction operationId: deleteCustomInstruction parameters: - name: style_id in: path required: true schema: type: string description: The ID of the style rule list - name: instruction_id in: path required: true schema: type: string description: The ID of the custom instruction responses: 204: description: Custom instruction deleted successfully headers: X-Trace-ID: $ref: '#/components/headers/X-Trace-ID' 400: $ref: '#/components/responses/BadRequest' 401: $ref: '#/components/responses/Unauthorized' 403: $ref: '#/components/responses/ForbiddenScoped' 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: servers: - url: https://api.deepl.com description: Override base path for all operations with the /v3/voice path post: tags: - VoiceAPI summary: Get Streaming URL operationId: getVoiceStreamingUrl parameters: - $ref: '#/components/parameters/CustomReportingTag' requestBody: required: true content: application/json: schema: type: object required: - source_media_content_type properties: message_format: $ref: '#/components/schemas/VoiceMessageFormat' source_media_content_type: $ref: '#/components/schemas/VoiceSourceMediaContentType' source_language: $ref: '#/components/schemas/VoiceSourceLanguage' source_language_mode: $ref: '#/components/schemas/VoiceSourceLanguageMode' target_languages: $ref: '#/components/schemas/VoiceTargetLanguages' target_media_languages: $ref: '#/components/schemas/VoiceTargetMediaLanguages' target_media_content_type: $ref: '#/components/schemas/VoiceTargetMediaContentType' target_media_voice: $ref: '#/components/schemas/VoiceTargetMediaVoice' spoken_terms_id: $ref: '#/components/schemas/SpokenTermsId' glossary_id: description: |- Specify the glossary to use for the target transcripts (translations). For new integrations we recommend the more general `glossary_ids`. Cannot be used together with `glossary_ids`. type: string example: def3a26b-3e84-45b3-84ae-0c0aaf3525f7 glossary_ids: description: |- Specify the glossaries to use for the target transcripts (translations), as an array of glossary IDs ordered by priority (highest first). Each glossary's matching terms are applied to the translation; where entries conflict, the higher-priority glossary wins. Unknown glossary IDs are ignored. Cannot be used together with `glossary_id`. Requests that exceed the session limit, contain duplicates, or combine `glossary_ids` with `glossary_id` are rejected with a `400 Bad Request` before a session is created. type: array items: type: string example: def3a26b-3e84-45b3-84ae-0c0aaf3525f7 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'] message_format: 'json' with_glossary: summary: With glossary and formality to customize translation value: source_media_content_type: 'audio/pcm; encoding=s16le; rate=16000' source_language: 'en' source_language_mode: 'fixed' target_languages: ['de', 'fr'] message_format: 'msgpack' glossary_id: 'def3a26b-3e84-45b3-84ae-0c0aaf3525f7' formality: 'formal' with_multiple_glossaries: summary: With multiple glossaries in priority order value: source_media_content_type: 'audio/pcm; encoding=s16le; rate=16000' source_language: 'en' source_language_mode: 'fixed' target_languages: ['de', 'fr'] glossary_ids: - 'def3a26b-3e84-45b3-84ae-0c0aaf3525f7' - '7c4f1080-cfe2-41d4-8269-0e6ec15a0354' with_spoken_terms: summary: With Spoken Terms to inform transcription value: source_media_content_type: 'audio/pcm; encoding=s16le; rate=16000' source_language: 'en' source_language_mode: 'fixed' target_languages: ['de'] spoken_terms_id: '7c4f1080-cfe2-41d4-8269-0e6ec15a0354' with_tts: summary: With translated audio (default format) value: source_media_content_type: 'audio/ogg;codecs=opus' source_language: 'en' target_languages: ['de', 'fr', 'es'] target_media_languages: ['de'] target_media_content_type: 'audio/webm;codecs=opus' target_media_voice: 'female' with_tts_short_form: summary: With translated audio using short-form MIME types value: source_media_content_type: 'audio/webm' source_language: 'en' target_languages: ['de', 'es'] target_media_languages: ['de'] target_media_content_type: 'audio/ogg' with_tts_high_quality: summary: With translated audio using high-quality PCM value: source_media_content_type: 'audio/pcm;encoding=s16le;rate=16000' source_language: 'en' target_languages: ['de'] target_media_languages: ['de'] target_media_content_type: 'audio/pcm;encoding=s16le;rate=24000' with_tts_raw_opus: summary: With translated audio using raw Opus value: source_media_content_type: 'audio/pcm;encoding=s16le;rate=16000' source_language: 'en' target_languages: ['de'] target_media_languages: ['de'] target_media_content_type: 'audio/opus' 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' 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: [] 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: [] /v1/jobs/voice/translate: post: tags: - VoiceTranslateJob operationId: createVoiceTranslateJob summary: Create a voice translation job description: |- Creates an async voice translation job. The response includes an upload URL for the source audio file. security: - auth_header: [] parameters: - $ref: '#/components/parameters/VoiceTranslateJobIncludeParam' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/VoiceTranslateCreateJobRequest' example: source_file: name: "podcast-episode-42.mp3" content_type: "audio/mpeg" content_length: 15728640 parameters: source_language: "en" targets: - language: "de" type: "text/plain" - language: "es" type: "audio/pcm;encoding=s16le;rate=16000" responses: "201": description: Job created successfully. content: application/json: schema: $ref: '#/components/schemas/VoiceTranslateCreateJobResponse' example: job_id: "a74d88fb-ed2a-4943-a664-a4512398b994" upload_url: "https://assets.deepl.com/collections/a74d88fb-ed2a-4943-a664-a4512398b994/assets/b1c2d3e4-f5a6-7890-abcd-ef1234567890" signature: "eyJhbGciOiJIUzI1NiIs..." "400": $ref: '#/components/responses/VoiceTranslateJobBadRequest' "401": $ref: '#/components/responses/Unauthorized' "403": $ref: '#/components/responses/Forbidden' "429": $ref: '#/components/responses/TooManyRequests' /v1/jobs/voice/translate/{job_id}: get: tags: - VoiceTranslateJob operationId: getVoiceTranslateJobStatus summary: Get voice translation job status description: |- Returns the current status of a voice translation job, including per-target result statuses. When a target's status is `complete`, the response includes a `download_url` and `signature` for that target. Results are returned in the same order as the targets in the create request. security: - auth_header: [] parameters: - $ref: '#/components/parameters/VoiceTranslateJobIdParam' - $ref: '#/components/parameters/VoiceTranslateJobIncludeParam' responses: "200": description: Job status retrieved successfully. content: application/json: schema: $ref: '#/components/schemas/VoiceTranslateJobStatusResponse' examples: processing: summary: Job still processing value: job_id: "a74d88fb-ed2a-4943-a664-a4512398b994" product: "voice" operation: "translate" created_at: "2026-10-01T01:03:03.444Z" updated_at: "2026-10-01T04:03:03.333Z" usage: storage_used: 31457280 source_file: name: "podcast-episode-42.mp3" content_type: "audio/mpeg" content_length: 15728640 parameters: source_language: "en" targets: - language: "de" type: "text/plain" - language: "es" type: "audio/pcm;encoding=s16le;rate=16000" results: - status: "processing" - status: "processing" complete: summary: Job with mixed results value: job_id: "a74d88fb-ed2a-4943-a664-a4512398b994" product: "voice" operation: "translate" created_at: "2026-10-01T01:03:03.444Z" updated_at: "2026-10-01T04:03:03.333Z" usage: storage_used: 31457280 source_file: name: "podcast-episode-42.mp3" content_type: "audio/mpeg" content_length: 15728640 parameters: source_language: "en" targets: - language: "de" type: "text/plain" - language: "es" type: "audio/pcm;encoding=s16le;rate=16000" results: - status: "complete" download_url: "https://assets.deepl.com/collections/a74d88fb/assets/c3d4e5f6" signature: "eyJhbGciOiJIUzI1NiIs..." - status: "failed" error: message: "processing failed" "401": $ref: '#/components/responses/Unauthorized' "404": $ref: '#/components/responses/NotFound' "429": $ref: '#/components/responses/TooManyRequests' /v1/quality-evaluation: post: tags: - QualityEvaluation summary: Submit an evaluation job operationId: submitQualityEvaluation description: |- Starts an evaluation job for the given segments. Returns a `poll_url` that can be used to retrieve the result. requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/QualityEvaluationRequest' example: metadata: source_language: en target_language: de segments: - source: Our Q3 revenue came in 5% above forecast. target: Unser Q3-Umsatz lag 5 % unter der Prognose. - source: Please share these results with your teams by Friday. target: Bitte teilen Sie diese Ergebnisse mit Ihrem Team. responses: 202: description: Job accepted. Use the returned `poll_url` to retrieve the result. headers: Retry-After: description: Suggested number of seconds to wait before polling. schema: type: integer example: 5 content: application/json: schema: $ref: '#/components/schemas/QualityEvaluationJobCreated' example: job_id: f3a8c5e1-9b7d-4e62-a1c4-8f5d2b6e3c19 poll_url: /v1/quality-evaluation/f3a8c5e1-9b7d-4e62-a1c4-8f5d2b6e3c19 400: description: |- Request validation failed. Common causes: - `metadata.source_language`, `metadata.target_language`, or `segments` is missing or empty. - `segments` contains more than 500 entries. - A segment's `source` or `target` exceeds 10,000 characters. - The `source_language` / `target_language` combination is not supported. content: application/json: schema: $ref: '#/components/schemas/QualityEvaluationApiError' example: message: segments[0].source is required. 403: description: |- Authorization failed. Common causes: - The API key does not have access to the Quality Evaluation feature. - A free-tier key is used against the paid endpoint, or vice versa. content: application/json: schema: $ref: '#/components/schemas/QualityEvaluationApiError' example: message: Forbidden 429: $ref: '#/components/responses/TooManyRequests' security: - auth_header: [ ] /v1/quality-evaluation/{job_id}: get: tags: - QualityEvaluation summary: Poll for the evaluation result operationId: pollQualityEvaluation description: |- Returns the current state of an evaluation job. While the job is in progress the response contains only status information. Once complete the response includes the full evaluation report. parameters: - name: job_id in: path required: true description: The job identifier returned by `POST /v1/quality-evaluation`. Must be a valid UUID. schema: type: string format: uuid example: f3a8c5e1-9b7d-4e62-a1c4-8f5d2b6e3c19 responses: 200: description: |- Polling result. The response shape depends on the `status` field. `done` returns the full evaluation report; `error` returns error details. content: application/json: schema: oneOf: - $ref: '#/components/schemas/QualityEvaluationDone' - $ref: '#/components/schemas/QualityEvaluationFailed' example: job_id: f3a8c5e1-9b7d-4e62-a1c4-8f5d2b6e3c19 status: done segments: - segment_index: 0 errors: - type: Accuracy sub_type: Mistranslation severity: Critical explanation: "The source says revenue was '5% above forecast' but the translation says '5 % unter der Prognose' (5% below forecast). This completely reverses the meaning and has financial implications." source_spans: - start: 23 end: 31 target_spans: - start: 20 end: 29 - segment_index: 1 errors: - type: Accuracy sub_type: Omission severity: Major explanation: "The source specifies the deadline 'by Friday' but the translation omits this temporal information entirely." source_spans: - start: 43 end: 52 target_spans: [] - type: Accuracy sub_type: Mistranslation severity: Minor explanation: "The source says 'your teams' (plural) but the translation says 'Ihrem Team' (singular). This changes the scope of the instruction." source_spans: - start: 32 end: 42 target_spans: - start: 38 end: 48 summary: overall_score: 72 granular_counts: Accuracy: Mistranslation: Critical: 1 Minor: 1 Omission: Major: 1 202: description: Job is still processing. Continue polling after the time suggested by the `Retry-After` header. headers: Retry-After: description: Suggested number of seconds to wait before polling again. schema: type: integer example: 5 content: application/json: schema: $ref: '#/components/schemas/QualityEvaluationProcessing' example: job_id: f3a8c5e1-9b7d-4e62-a1c4-8f5d2b6e3c19 status: processing 400: description: Invalid `job_id` format. The `job_id` must be a valid UUID. content: application/json: schema: $ref: '#/components/schemas/QualityEvaluationApiError' example: message: job_id must be a valid UUID. 404: description: |- Job not found. The `job_id` is well-formed but no job exists with that ID, or it has expired. Jobs are retained for 24 hours after reaching `done` or `error` state. content: application/json: schema: $ref: '#/components/schemas/QualityEvaluationApiError' example: message: Quality estimation job not found. 429: $ref: '#/components/responses/TooManyRequests' security: - auth_header: [ ] components: 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 parameters: CustomReportingTag: name: X-DeepL-Reporting-Tag in: header required: false description: > An optional custom reporting tag used to attribute this request's usage to a team, project, customer, or other category of your choosing. Values are limited to 100 characters. See [How to use custom reporting tags](/docs/learning-how-tos/examples-and-guides/how-to-use-custom-reporting-tags) for validation rules, naming guidance, and how to retrieve usage by tag. schema: type: string maxLength: 100 example: team-billing 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 VoiceTranslateJobIdParam: name: job_id in: path required: true description: The unique identifier of the job, returned by the create job endpoint. schema: type: string format: uuid example: "a74d88fb-ed2a-4943-a664-a4512398b994" VoiceTranslateJobIncludeParam: name: include in: query required: false description: |- Additional fields to include in the response. - `signed_url`: Include pre-signed URLs (`signed_upload_url` on create, `signed_download_url` on status) that can be used without an authorization header. schema: type: array items: type: string enum: - signed_url style: form explode: true GlossaryID: name: glossary_id description: A unique ID assigned to the glossary. in: path required: true schema: type: string SpokenTermsID: name: spoken_terms_id description: A unique ID assigned to the Spoken Terms collection. 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' responses: VoiceTranslateJobBadRequest: description: Bad request. Check the error message and request parameters. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: message: "/targets/0/type: Value is not valid" BadRequest: description: Bad request. Please check error message and your parameters. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' BadRequestGlossaries: description: Bad request. Please check error message and your parameters. 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. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' Forbidden: description: Authorization failed. Please supply a valid `DeepL-Auth-Key` via the `Authorization` header. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' ForbiddenScoped: description: Authorization failed. Please supply a valid `DeepL-Auth-Key` via the `Authorization` header. This error is also returned when the API key is scoped but does not include the scope required for this endpoint. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' ForbiddenGlossaries: description: Forbidden. The access to the requested resource is denied, because of insufficient access rights. This error is also returned when the API key is scoped but does not include the scope required for this endpoint. NotFound: description: The requested resource could not be found. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' 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. 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. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' 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. UnsupportedMediaTypeGlossaries: description: The requested entries format specified in the `Accept` header is not supported. TooManyRequests: description: Too many requests. Please wait and resend your request. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' QuotaExceeded: description: Quota exceeded. The character limit has been reached. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' QuotaExceededGlossaries: description: Quota exceeded. Too many requests were made to the glossary endpoints recently. BadRequestSpokenTerms: description: Bad request. Please check error message and your parameters. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: message: "Bad request" ForbiddenSpokenTerms: description: Forbidden. Authorization failed or feature not available for your plan. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: message: "Forbidden. Authorization failed or feature not available for your plan." QuotaExceededSpokenTerms: description: Quota exceeded. Spoken Terms collection limit reached for your plan. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: message: "Spoken Terms quota exhausted" UnsupportedMediaType: description: Unsupported Media Type. Must be application/json or application/x-www-form-urlencoded. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: message: "Unsupported Content-Type" InternalServerError: description: Internal error. ServiceUnavailable: description: Resource currently unavailable. Try again later. 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. 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. Example: `DeepL-Auth-Key ` name: Authorization in: header x-default: "DeepL-Auth-Key " 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 example: style_and_tone: abbreviations: "use_abbreviations_and_symbols" short_vs_long_words: "use_short_words" punctuation: apostrophe: "use_curly_apostrophes" Context: description: |- Additional context that can influence a translation but is not translated itself. Characters included in the `context` parameter will not be counted toward billing. type: string example: This is context. 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](/docs/customize/managing-glossaries#entry-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" 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 list 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 list 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 list. Incremented when the style rule list 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 list. example: "bd0a38f3-1831-440b-a8dd-2c702e2325ab" StyleRuleLanguage: description: The language that the style rule list is applied to. type: string enum: - de - en - es - fr - it - ja - ko - zh StyleRuleName: description: Name associated with the style rule list. type: string 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 is only available for certain target languages. 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 example: prefer_more 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' entry_count: allOf: - $ref: '#/components/schemas/GlossaryEntryCount' readOnly: true 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](/docs/customize/managing-glossaries#entry-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 SpokenTermsId: type: string format: uuid description: (beta) The ID of a Spoken Terms collection used to inform transcription. example: 7c4f1080-cfe2-41d4-8269-0e6ec15a0354 ModelType: type: string description: Specifies which DeepL model should be used for translation. enum: - quality_optimized - prefer_quality_optimized - latency_optimized MonolingualGlossary: type: object properties: glossary_id: $ref: '#/components/schemas/GlossaryId' name: description: Name associated with the glossary. type: string 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: description: The number of entries in the glossary. type: integer 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: |- Disable the automatic detection of XML structure 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. type: boolean default: true OutlineDetectionOptionStr: description: |- Disable the automatic detection of XML structure 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. type: string default: '1' 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' CreateSpokenTermsParameters: type: object required: - name - term_lists properties: name: description: Name for the Spoken Terms collection. type: string maxLength: 1024 example: Technical Terms term_lists: description: Array of term lists, one per language. type: array items: $ref: '#/components/schemas/SpokenTermsListInput' SpokenTermsListInput: type: object required: - lang - entries properties: lang: description: Language code (ISO 639-1) for this term list. type: string example: en entries: description: | Newline-separated list of terms, one term per line. Maximum 300 characters total. Terms are case-sensitive. Each term must be non-empty, must not contain C0 or C1 control characters (such as tabs or newlines within a term), and must not have leading or trailing whitespace. Duplicate terms within a list are not allowed (comparison is case-sensitive). type: string maxLength: 300 example: "DeepL\nAPI\nwebhook" PatchSpokenTermsParameters: type: object properties: name: description: New name for the Spoken Terms collection. type: string maxLength: 1024 example: Updated Technical Terms term_lists: description: Term lists to merge with existing lists. type: array items: $ref: '#/components/schemas/SpokenTermsListInput' PutSpokenTermsListParameters: type: object required: - lang - entries properties: lang: description: Language code (ISO 639-1) for this term list. type: string example: en entries: description: | Newline-separated list of terms, one term per line. Maximum 300 characters total. Terms are case-sensitive. Each term must be non-empty, must not contain C0 or C1 control characters (such as tabs or newlines within a term), and must not have leading or trailing whitespace. Duplicate terms within a list are not allowed (comparison is case-sensitive). type: string maxLength: 300 example: "DeepL\nAPI\nwebhook\nintegration" SpokenTerms: type: object properties: spoken_terms_id: description: A unique ID assigned to the Spoken Terms collection. type: string example: def3a26b-3e84-45b3-84ae-0c0aaf3525f7 name: description: Name of the Spoken Terms collection. type: string example: Technical Terms term_lists: description: List of term lists contained in this collection. type: array items: $ref: '#/components/schemas/SpokenTermsList' creation_time: description: 'The creation time of the Spoken Terms collection in ISO 8601-1:2019 format (e.g.: `2025-08-03T14:16:18.329Z`).' type: string format: date-time example: '2025-08-03T14:16:18.329Z' SpokenTermsList: type: object properties: lang: description: Language code (ISO 639-1). type: string example: en entry_count: description: Number of terms in this list. type: integer example: 3 SpokenTermsEntries: type: object properties: lang: description: Language code (ISO 639-1). type: string example: en entries: description: Newline-separated list of terms. type: string example: "DeepL\nAPI\nwebhook" PreserveFormattingOption: description: |- Sets whether the translation engine should respect the original formatting, even if it would usually correct some aspects. type: boolean default: false PreserveFormattingOptionStr: description: |- Sets whether the translation engine should respect the original formatting, even if it would usually correct some aspects. type: string enum: - '0' - '1' default: '0' 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. type: boolean SplitSentencesOption: description: |- Sets whether the translation engine should first split the input into sentences. 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 type: string enum: - '0' - '1' - nonewlines default: '1' example: '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. For the full list of supported source languages, see [supported languages](https://developers.deepl.com/docs/getting-started/supported-languages) or query the [`GET /v3/languages` endpoint](https://developers.deepl.com/docs/languages/using-the-languages-api). example: EN TranslationMemory: type: object required: - translation_memory_id - name - source_language - target_languages - segment_count properties: translation_memory_id: $ref: '#/components/schemas/TranslationMemoryId' name: description: Name associated with the translation memory. type: string example: Legal source_language: $ref: '#/components/schemas/TranslationMemorySourceLanguage' target_languages: description: The list of target languages available in the translation memory. type: array items: $ref: '#/components/schemas/TranslationMemoryTargetLanguage' example: - es - de segment_count: description: The number of segments stored in the translation memory. type: integer example: 34 creation_time: description: 'The creation time of the translation memory in the ISO 8601-1:2019 format (e.g.: `2021-08-03T14:16:18.329Z`).' type: string format: date-time example: '2026-04-01T16:34:25.223Z' updated_time: description: 'The time of the last update to the translation memory in the ISO 8601-1:2019 format (e.g.: `2021-08-03T14:16:18.329Z`).' type: string format: date-time example: '2026-04-01T16:34:25.264Z' TranslationMemoryId: type: string format: uuid description: |- A unique ID assigned to a translation memory. example: a74d88fb-ed2a-4943-a664-a4512398b994 TranslationMemorySourceLanguage: description: The source language of the translation memory. type: string enum: - de - en - es - fr - it - ja - ko - zh example: en TranslationMemoryTargetLanguage: description: The list of target languages available in the translation memory. A translation memory's target language must be compatible with the `target_lang` specified in a translation request. type: string enum: - de - en - en-gb - en-us - es - es-419 - fr - it - ja - ko - zh - zh-hans example: es TranslationMemorySegment: description: A source segment stored in a translation memory, with its translations. type: object required: - source_segment_id - source_text - targets properties: source_segment_id: description: A unique ID assigned to the source segment. type: string example: 4f1c2d3e-8a9b-4c5d-9e6f-7a8b9c0d1e2f source_text: description: The source text of the segment. type: string example: This agreement is governed by the laws of Germany. creation_time: description: The time the segment was added, in the ISO 8601-1:2019 format. type: string format: date-time example: '2026-04-01T16:34:25.223Z' updated_time: description: The time the segment was last changed, in the ISO 8601-1:2019 format. type: string format: date-time example: '2026-04-01T16:34:25.223Z' last_used_time: description: |- The time the segment was last applied to a translation, in the ISO 8601-1:2019 format. Absent if the segment has never been used. type: string format: date-time example: '2026-08-05T11:02:18.771Z' targets: description: The translations of this source segment, one per target language. type: array items: $ref: '#/components/schemas/TranslationMemoryTargetSegment' TranslationMemoryTargetSegment: description: A translation of a source segment in one target language. type: object required: - target_segment_id - target_language - target_text properties: target_segment_id: description: A unique ID assigned to the target segment. type: string example: 9b8a7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d target_language: $ref: '#/components/schemas/TranslationMemoryTargetLanguage' target_text: description: The translated text. type: string example: Dieser Vertrag unterliegt dem Recht der Bundesrepublik Deutschland. creation_time: description: The time the translation was added, in the ISO 8601-1:2019 format. type: string format: date-time example: '2026-04-01T16:34:25.223Z' updated_time: description: The time the translation was last changed, in the ISO 8601-1:2019 format. type: string format: date-time example: '2026-04-01T16:34:25.223Z' last_used_time: description: |- The time the translation was last applied to a translation request, in the ISO 8601-1:2019 format. Absent if it has never been used. type: string format: date-time example: '2026-08-05T11:02:18.771Z' CreateTranslationMemoryExport: description: A reference to a translation memory export job. type: object required: - job_id - parameters properties: job_id: description: The identifier of the export job. Use it to poll the job's status. type: string format: uuid example: 7c2e5a91-3b8d-4f16-8e0a-6d4c2b7f9a13 parameters: type: object properties: translation_memory_id: $ref: '#/components/schemas/TranslationMemoryId' TranslationMemoryJob: description: |- The state of a translation memory import or export job. Fields that do not apply to the job's `operation` are omitted. type: object required: - job_id - product - operation - creation_time - updated_time - parameters - results properties: job_id: description: The identifier of the job. type: string format: uuid example: 0f8b6c1e-4d2a-4c77-9a3e-1b5d8c9e2f40 product: description: The DeepL product the job belongs to. Always `translation_memory`. type: string example: translation_memory operation: description: Which kind of job this is. type: string enum: - import - export example: import creation_time: description: The time the job was created, in the ISO 8601-1:2019 format. type: string format: date-time example: '2026-08-06T15:04:25.223Z' updated_time: description: The time the job last changed state, in the ISO 8601-1:2019 format. type: string format: date-time example: '2026-08-06T15:06:11.418Z' source_file: description: The file declared when the import job was created. Omitted for export jobs. type: object properties: content_type: description: The MIME type declared for the uploaded file. type: string example: application/xml content_length: description: The size in bytes declared for the uploaded file. type: integer format: int64 example: 1024 parameters: description: |- The parameters the job was created with. Import jobs report `display_name`; export jobs report `translation_memory_id`. type: object properties: translation_memory_id: $ref: '#/components/schemas/TranslationMemoryId' display_name: description: The name given to the translation memory the import creates. type: string example: Legal results: description: |- The job's outcome. This array always holds exactly one entry. It is an array so that jobs producing multiple outputs can be represented without a breaking change. type: array items: $ref: '#/components/schemas/TranslationMemoryJobResult' TranslationMemoryJobResult: description: The status of a translation memory job and, once it finishes, its output. type: object required: - status properties: status: description: |- The job's current state: * `awaiting_input` - the job exists but the file has not been uploaded yet (import only) * `processing` - the file was received and is being processed * `completed` - the job finished successfully * `failed` - the job did not finish; see `error` * `expired` - the job is too old to act on; create a new one type: string enum: - awaiting_input - processing - completed - failed - expired example: completed status_metadata: description: |- Extra context for states that need you to act. Present only when there is something to do. type: object properties: required_action: description: What the job is waiting for. type: string example: Waiting for upload download_url: description: |- A short-lived URL to download the exported TMX file from. Present on completed export jobs only. Download the file rather than storing this URL. type: string format: uri example: https://assets.deepl.com/download/7c2e5a91-3b8d-4f16-8e0a-6d4c2b7f9a13 expires_at: description: |- The time `download_url` stops working, in the ISO 8601-1:2019 format. Present on completed export jobs only. type: string format: date-time example: '2026-08-06T16:05:02.771Z' error: description: Why the job failed. Present only when `status` is `failed`. type: object properties: message: description: A description of the failure. type: string example: The uploaded file is not valid TMX. translation_memory_id: $ref: '#/components/schemas/TranslationMemoryId' skipped_segment_count: description: |- How many segments in the uploaded file were not imported, for example because they were malformed or duplicated an existing segment. Present on completed import jobs only. A non-zero value does not mean the import failed. type: integer format: int64 example: 12 TranslationMemoryThreshold: type: integer description: The minimum matching percentage required for a translation memory segment to be applied (recommended to be 75% or higher). minimum: 0 maximum: 100 default: 75 example: 75 TagHandlingOption: description: |- Sets which kind of tags should be handled. Options currently available: * `xml` * `html` type: string enum: - xml - html example: html TagHandlingVersionOption: description: |- Sets which version of the tag handling algorithm should be used. Options currently available: * `v1`: Traditional algorithm (currently the default, will become deprecated in the future). * `v2`: Improved algorithm released in October 2025 (will become the default in the future). type: string enum: - v2 - v1 NonSplittingTagCommaSeparatedList: allOf: - $ref: '#/components/schemas/TagCommaSeparatedList' description: Comma-separated list of XML tags which never split sentences. 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. IgnoreTagList: allOf: - $ref: '#/components/schemas/TagList' description: List of XML tags that indicate text not to be translated. 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. For the full list of supported target languages, see [supported languages](https://developers.deepl.com/docs/getting-started/supported-languages) or query the [`GET /v3/languages` endpoint](https://developers.deepl.com/docs/languages/using-the-languages-api). example: DE TargetLanguageWrite: type: string description: |- The language for the text improvement. enum: - de - en - en-GB - en-US - es - fr - it - ja - ko - pt - pt-BR - pt-PT - zh - zh-Hans example: de 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 document_count: description: Documents translated so far in the current billing period. Only present for accounts with a document limit. type: integer format: int64 document_limit: description: Current maximum number of documents that can be translated per billing period. Only present for accounts with a document limit. type: integer format: int64 team_document_count: description: Documents translated by all users in the team so far in the current billing period. Only present for accounts with a team document limit. type: integer format: int64 team_document_limit: description: Current maximum number of documents that can be translated by the team per billing period. Only present for accounts with a team document limit. type: integer format: int64 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 - minutes 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 in the current period. example: 5643 api_key_character_count: type: integer deprecated: true description: Use api_key_unit_count instead. Characters used for this product by this API key in the current period." example: 0 character_count: type: integer deprecated: true description: Use account_unit_count instead. 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 deprecated: true description: Deprecated. Always returns 0. Use speech_to_text_minutes_count instead. example: 0 speech_to_text_milliseconds_limit: type: integer deprecated: true description: Deprecated. Always returns 0. Use speech_to_text_minutes_limit instead. example: 0 speech_to_text_minutes_count: type: integer description: Only present for API Pro users. Minutes of speech-to-text used in the current period. Milliseconds are rounded up to the nearest minute. example: 30 speech_to_text_minutes_limit: type: integer description: Only present for API Pro users. Maximum minutes of speech-to-text that can be used in the current billing period. example: 600 speech_to_speech_minutes_count: type: integer description: Only present for API Pro users. Minutes of speech-to-speech used in the current period. Milliseconds are rounded up to the nearest minute. example: 12 speech_to_speech_minutes_limit: type: integer description: Only present for API Pro users. Maximum minutes of speech-to-speech that can be used in the current billing period. example: 600 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' 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 VoiceMessageFormat: description: |- Message encoding format for WebSocket communication. Determines how messages are serialized and transmitted. Using `json`, messages are JSON-encoded and sent as TEXT WebSocket frames. All binary fields (such as audio data) are base64-encoded strings. Using `msgpack`, messages are MessagePack-encoded and sent as BINARY WebSocket frames. All binary fields (such as audio data) contain raw binary data. For more details, see [Message Encoding](/api-reference/voice#message-encoding). type: string enum: - json - msgpack default: json example: json VoiceTargetMediaVoice: description: Target audio voice selection for synthesized speech. The default voice is language dependent. type: string enum: - male - female example: female VoiceSourceMediaContentType: type: string description: " The audio format for streaming, which specifies container, codec, and encoding parameters. See the table below for supported formats. If `audio/auto` is specified, the server will auto-detect the container and codec for all supported combinations, except PCM. That requires explicit encoding parameters. All formats need to be single channel audio.\n \n | Content Type | Container | Codec |\n | :------------------------------------ | :------------------------------------------------ | :---------------------------------------- |\n | `audio/auto` | Auto-detect: FLAC / Matroska / MPEG / Ogg / WebM | Auto-detect AAC / FLAC / MP3 / OPUS |\n | `audio/flac` | FLAC (flac) | FLAC |\n | `audio/mpeg` | MPEG (mp3/m4a) | MP3 |\n | `audio/ogg` | Ogg (ogg/oga) | Auto-detect FLAC / OPUS |\n | `audio/webm` | WebM (webm) | OPUS |\n | `audio/x-matroska` | Matroska (mkv/mka) | Auto-detect: AAC / FLAC / MP3 / OPUS |\n | `audio/ogg;codecs=flac` | Ogg (ogg/oga) | FLAC |\n | `audio/ogg;codecs=opus` | Ogg (ogg/oga) | OPUS |\n | `audio/pcm;encoding=alaw;rate=8000` | - | PCM A-Law 8000 Hz (G.711) |\n | `audio/pcm;encoding=ulaw;rate=8000` | - | PCM µ-Law 8000 Hz (G.711) |\n | `audio/pcm;encoding=s16le;rate=8000` | - | PCM signed 16-bit little-endian 8000 Hz |\n | `audio/pcm;encoding=s16le;rate=16000` | - | PCM signed 16-bit little-endian 16000 Hz |\n | `audio/pcm;encoding=s16le;rate=44100` | - | PCM signed 16-bit little-endian 44100 Hz |\n | `audio/pcm;encoding=s16le;rate=48000` | - | PCM signed 16-bit little-endian 48000 Hz |\n | `audio/webm;codecs=opus` | WebM (webm) | OPUS |\n | `audio/x-matroska;codecs=aac` | Matroska (mkv/mka) | AAC |\n | `audio/x-matroska;codecs=flac` | Matroska (mkv/mka) | FLAC |\n | `audio/x-matroska;codecs=mp3` | Matroska (mkv/mka) | MP3 |\n | `audio/x-matroska;codecs=opus` | Matroska (mkv/mka) | OPUS |\n \n We recommend the following bitrates as good tradeoff between quality and bandwidth:\n - AAC: 96 kbps\n - FLAC: 256 kbps (16000 Hz)\n - MP3: 128 kbps\n - OPUS: 32 kbps (recommendation for low bandwidth scenarios)\n - PCM: 256 kbps (16000 Hz, default recommendation)\n " 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=alaw;rate=8000 - audio/pcm;encoding=ulaw;rate=8000 - 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: > The source language of the audio stream. It can be left empty or must be one of the supported Voice API source languages and comply with IETF BCP 47 language tags. Note: Some source transcription languages are provided through external service partners. See the [supported languages table](/api-reference/voice#show-supported-languages) for details. enum: - ar - bg - bn - cs - da - de - el - en - es - et - fi - fr - ga - he - hi - hr - hu - id - it - ja - ko - lt - lv - ms - mt - nb - nl - pl - pt - ro - ru - sk - sl - sv - ta - th - tl - tr - uk - vi - zh default: 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: fixed VoiceTargetLanguages: type: array description: > List of target languages for translation. The stream will emit translations for each language. Language identifiers must comply with IETF BCP 47. See the [supported languages table](/api-reference/voice#show-supported-languages) for details. items: type: string enum: - ar - bg - bn - cs - da - de - el - en - en-GB - en-US - es - et - fi - fr - ga - he - hi - hr - hu - id - it - ja - ko - lt - lv - ms - mt - nb - nl - pl - pt - pt-BR - pt-PT - ro - ru - sk - sl - sv - ta - th - tl - tr - uk - vi - zh - zh-HANS - zh-HANT maxItems: 5 default: [] example: ["de", "fr", "es"] VoiceTargetMediaLanguages: type: array description: > List of target languages for which to generate synthesized audio. Languages specified here will automatically be added to target_languages if not already present, ensuring you receive both text translation and audio synthesis for these languages. If omitted, only text transcription and translation will be provided (no audio synthesis). Language identifiers must comply with IETF BCP 47. Note: Some translated audio languages are provided through external service partners. See the [supported languages table](/api-reference/voice#show-supported-languages) for details. items: type: string enum: - ar - bg - cs - da - de - el - en - en-GB - en-US - es - fi - fr - hi - hu - id - it - ja - ko - ms - nb - nl - pl - pt - pt-BR - pt-PT - ro - ru - sk - sv - ta - tr - uk - vi - zh - zh-HANS - zh-HANT maxItems: 1 default: [] example: ["de"] VoiceTargetMediaContentType: type: string description: " The audio format for synthesized target media streaming.\n Specifies container, codec, and encoding parameters for the audio returned in target_media_chunk messages.\n If not specified, defaults to audio/webm;codecs=opus.\n Only applies when target_media_languages is specified.\n \n | Content Type | Container | Codec |\n | :--- | :--- | :--- |\n | `audio/flac` | FLAC (flac) | FLAC 24000 Hz |\n | `video/mp2t;codecs=aac` | MPEG Transport Stream (Audio only) | AAC 70 kbit/s |\n | `video/mp2t;codecs=opus` | MPEG Transport Stream (Audio only) | OPUS 32 kbit/s |\n | `audio/ogg` | Ogg (ogg/oga) | OPUS 32 kbit/s |\n | `audio/ogg;codecs=flac` | Ogg (ogg/oga) | FLAC 24000 Hz |\n | `audio/ogg;codecs=opus` | Ogg (ogg/oga) | OPUS 32 kbit/s |\n | `audio/opus` | - | OPUS 32 kbit/s |\n | `audio/pcm;encoding=alaw;rate=8000` | - | PCM A-Law 8000 Hz (G.711) |\n | `audio/pcm;encoding=ulaw;rate=8000` | - | PCM µ-Law 8000 Hz (G.711) |\n | `audio/pcm;encoding=s16le;rate=16000` | - | PCM signed 16-bit little-endian 16000 Hz |\n | `audio/pcm;encoding=s16le;rate=24000` | - | PCM signed 16-bit little-endian 24000 Hz |\n | `audio/webm` | WebM (webm) | OPUS 32 kbit/s |\n | `audio/webm;codecs=opus` | WebM (webm) | OPUS 32 kbit/s |\n | `audio/x-matroska;codecs=aac` | Matroska (mkv/mka) | AAC 70 kbit/s |\n | `audio/x-matroska;codecs=flac` | Matroska (mkv/mka) | FLAC 24000 Hz |\n | `audio/x-matroska;codecs=opus` | Matroska (mkv/mka) | OPUS 32 kbit/s |\n \n We recommend the following formats as good tradeoffs between quality and bandwidth:\n - OPUS (WebM): 32 kbps, recommended for low bandwidth scenarios (default)\n - PCM 24kHz: 384 kbps, high quality" enum: - audio/flac - video/mp2t;codecs=aac - video/mp2t;codecs=opus - audio/ogg - audio/ogg;codecs=flac - audio/ogg;codecs=opus - audio/opus - audio/pcm;encoding=alaw;rate=8000 - audio/pcm;encoding=ulaw;rate=8000 - audio/pcm;encoding=s16le;rate=16000 - audio/pcm;encoding=s16le;rate=24000 - audio/webm - audio/webm;codecs=opus - audio/x-matroska;codecs=aac - audio/x-matroska;codecs=flac - audio/x-matroska;codecs=opus default: audio/webm;codecs=opus example: audio/webm;codecs=opus VoiceStreamingResponse: type: object required: - streaming_url - token properties: streaming_url: type: string description: > The WebSocket URL to use for establishing [the stream connection](/api-reference/voice/websocket-streaming). 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 streaming URL](/api-reference/voice/websocket-streaming). This token is ephemeral and valid for a short time and one-time use only. example: VGhpcyBpcyBhIGZha2UgdG9rZW4K session_id: type: string description: > Internal use only. A unique identifier for the requested stream. example: 4f911080-cfe2-41d4-8269-0e6ec15a0354 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_minutes: type: number description: Duration of speech-to-text usage in minutes. example: 107.46 KeyAndDayUsageItem: type: object description: Usage statistics for a specific API key and optionally a 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. Only present when group_by is "key_and_day". example: "2025-09-29T00:00:00Z" usage: $ref: '#/components/schemas/UsageBreakdown' KeyUsageItem: type: object description: Usage statistics for a specific API key and optionally a 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: $ref: '#/components/schemas/UsageBreakdown' CustomTagUsageReport: type: object description: The response for admin custom tag usage statistics. properties: custom_tag_usage_report: $ref: '#/components/schemas/CustomTagUsageReportData' CustomTagUsageReportData: type: object description: Contains the detailed custom tag usage statistics for the specified date range. properties: aggregate_by: type: string description: The aggregation method used. enum: - period - day example: "period" start_date: type: string format: date-time description: Start date of the usage report period. example: "2026-05-03T00:00:00" end_date: type: string format: date-time description: End date of the usage report period. example: "2026-05-05T00:00:00" next_page: type: integer nullable: true description: Cursor for the next page of results. Null if there are no further pages. example: 2 usage: type: array description: List of custom tag usage entries. items: $ref: '#/components/schemas/CustomTagUsageItem' CustomTagUsageItem: type: object description: Usage statistics for a specific custom tag. properties: custom_tag: type: string description: The custom tag identifier. example: "example-custom-tag" usage_date: type: string format: date-time description: The day the usage was recorded. Only returned when `aggregate_by` is `day`. example: "2026-05-04T00:00:00Z" breakdown: $ref: '#/components/schemas/CustomTagBreakdown' CustomTagBreakdown: type: object description: Breakdown of usage by category for a custom tag. properties: total_characters: type: integer description: > Total number of characters used across character-based services. Voice usage is reported in minutes and is not included in this total. example: 380 text_translation_characters: type: integer description: Number of characters used for text translation. example: 380 text_improvement_characters: type: integer description: Number of characters used for text improvement. example: 0 speech_to_text_minutes: type: number description: Duration of speech-to-text usage in minutes. example: 12.5 speech_to_speech_minutes: type: number description: Duration of speech-to-speech usage in minutes. example: 4.2 ErrorResponse: type: object required: - message properties: message: type: string description: A human-readable description of the error. code: type: string description: A machine-readable identifier for the error, when available. Clients should match on this value rather than on `message` when branching on error types. example: "invalid_content_type" VoiceTranslateJobSourceContentType: type: string description: The MIME type of the source audio file. enum: - audio/mpeg - audio/wav - audio/ogg - audio/flac - audio/mp4 - audio/webm JobSourceFileRequest: type: object description: Metadata about the source audio file to be uploaded. required: - name - content_type - content_length properties: name: type: string minLength: 1 description: The file name of the source audio file. example: "podcast-episode-42.mp3" content_type: $ref: '#/components/schemas/VoiceTranslateJobSourceContentType' content_length: type: integer format: int64 minimum: 1 maximum: 1073741824 description: The size of the source audio file in bytes. Maximum 1 GB (1,073,741,824 bytes). example: 15728640 JobSourceFileResponse: type: object description: Metadata about the uploaded source audio file. required: - name - content_type - content_length properties: name: type: string description: The file name of the source audio file. content_type: type: string description: The MIME type of the source audio file. content_length: type: integer format: int64 description: The size of the source audio file in bytes. VoiceTranslateJobTargetOutputType: type: string description: The desired output format for the translation target. enum: - text/plain - application/x-subrip - audio/opus - audio/flac - "audio/pcm;encoding=s16le;rate=16000" - "audio/pcm;encoding=s16le;rate=24000" - "audio/pcm;encoding=ulaw;rate=8000" - "audio/pcm;encoding=alaw;rate=8000" - "audio/x-matroska;codecs=aac" - "audio/x-matroska;codecs=flac" - "audio/x-matroska;codecs=opus" - "audio/x-matroska;codecs=pcm_s16le;rate=16000" - "audio/x-matroska;codecs=pcm_s16le;rate=24000" - "video/mp2t;codecs=aac" - "video/mp2t;codecs=opus" - "audio/ogg;codecs=flac" - "audio/ogg;codecs=opus" - "audio/webm;codecs=opus" VoiceTranslateJobParametersRequest: type: object description: Processing parameters for the voice translation job. properties: source_language: allOf: - $ref: '#/components/schemas/SourceLanguage' - description: Language of the source audio. If omitted, the language is detected automatically. VoiceTranslateJobParametersResponse: type: object description: Processing parameters as applied to the voice translation job. properties: source_language: allOf: - $ref: '#/components/schemas/SourceLanguage' - description: Language of the source audio. VoiceTranslateJobTargetRequest: type: object description: A translation target specifying the desired output language and format. required: - language - type properties: language: $ref: '#/components/schemas/TargetLanguage' type: $ref: '#/components/schemas/VoiceTranslateJobTargetOutputType' VoiceTranslateJobTargetResponse: type: object description: A translation target as recorded on the job. required: - language - type properties: language: $ref: '#/components/schemas/TargetLanguage' type: $ref: '#/components/schemas/VoiceTranslateJobTargetOutputType' VoiceTranslateCreateJobRequest: type: object required: - source_file - targets properties: source_file: $ref: '#/components/schemas/JobSourceFileRequest' parameters: $ref: '#/components/schemas/VoiceTranslateJobParametersRequest' targets: type: array minItems: 1 description: One or more translation targets. Each target produces a separate result. items: $ref: '#/components/schemas/VoiceTranslateJobTargetRequest' VoiceTranslateCreateJobResponse: type: object required: - job_id - upload_url - signature properties: job_id: type: string format: uuid description: The unique identifier of the created job. upload_url: type: string format: uri description: |- The URL to upload the source audio file to via `PUT` with `Content-Type: application/octet-stream`. Requires the `Authorization: DeepL-Signature {signature}` header. See [Upload File](/api-reference/jobs-voice-translate#upload-file) for details. signature: type: string description: >- A short-lived token used to authorize the file upload. Pass it via the `Authorization` header as `DeepL-Signature {signature}` when uploading to the `upload_url`. signed_upload_url: type: string format: uri description: A pre-signed upload URL that does not require an authorization header. Only present when `?include=signed_url` is specified. JobUsage: type: object properties: storage_used: type: integer format: int64 description: Total storage used by this job in bytes, including source and output files. ResultStatus: type: string description: |- The processing status of a target result. - `pending`: Job created, awaiting file upload. - `uploaded`: File uploaded, awaiting processing. - `processing`: Translation in progress. - `complete`: Translation complete, result available for download. - `downloaded`: Result has been downloaded. Assets are marked for deletion. - `failed`: Processing failed. See the `error` field for details. enum: - pending - uploaded - processing - complete - downloaded - failed VoiceTranslateJobTargetResult: type: object description: The processing result for a single translation target. required: - status properties: status: $ref: '#/components/schemas/ResultStatus' download_url: type: string format: uri description: |- The URL to download the translated result via `GET`. Requires the `Authorization: DeepL-Signature {signature}` header. Only present when `status` is `complete`. See [Download Result](/api-reference/jobs-voice-translate#download-result) for details. signature: type: string description: A short-lived token used to authorize the result download. Only present when `status` is `complete`. signed_download_url: type: string format: uri description: A pre-signed download URL that does not require an authorization header. Only present when `status` is `complete` and `?include=signed_url` is specified. error: allOf: - $ref: '#/components/schemas/ErrorResponse' description: Details about the processing failure. Only present when `status` is `failed`. VoiceTranslateJobStatusResponse: type: object required: - job_id - product - operation - created_at - updated_at - usage - source_file - parameters - targets - results properties: job_id: type: string format: uuid description: The unique identifier of the job. product: type: string description: The product identifier. example: "voice" operation: type: string description: The operation identifier. example: "translate" created_at: type: string format: date-time description: When the job was created (ISO 8601). updated_at: type: string format: date-time description: When the job was last updated (ISO 8601). usage: $ref: '#/components/schemas/JobUsage' source_file: $ref: '#/components/schemas/JobSourceFileResponse' parameters: $ref: '#/components/schemas/VoiceTranslateJobParametersResponse' targets: type: array description: The translation targets as specified in the create request. items: $ref: '#/components/schemas/VoiceTranslateJobTargetResponse' results: type: array description: Per-target processing results, in the same order as the `targets` array. items: $ref: '#/components/schemas/VoiceTranslateJobTargetResult' QualityEvaluationRequest: type: object required: - metadata - segments properties: metadata: type: object required: - source_language - target_language description: Job-level metadata. properties: source_language: type: string description: Language code of the source text. See [Supported language pairs](/api-reference/quality-evaluation/submit#supported-language-pairs). example: en target_language: type: string description: Language code of the translated text. See [Supported language pairs](/api-reference/quality-evaluation/submit#supported-language-pairs). example: de segments: type: array minItems: 1 maxItems: 500 description: The segment pairs to evaluate. Up to 500 segments per request. items: type: object required: - source - target properties: source: type: string maxLength: 10000 description: The original text in the source language. example: Our Q3 revenue came in 5% above forecast. target: type: string maxLength: 10000 description: The translated text in the target language. example: Unser Q3-Umsatz lag 5 % unter der Prognose. QualityEvaluationJobCreated: type: object required: - job_id - poll_url properties: job_id: type: string format: uuid description: The job identifier. Use it with `GET /v1/quality-evaluation/{job_id}` to poll for the result. example: f3a8c5e1-9b7d-4e62-a1c4-8f5d2b6e3c19 poll_url: type: string description: Relative URL you can use to poll for the result. example: /v1/quality-evaluation/f3a8c5e1-9b7d-4e62-a1c4-8f5d2b6e3c19 QualityEvaluationProcessing: type: object required: - job_id - status properties: job_id: type: string format: uuid example: f3a8c5e1-9b7d-4e62-a1c4-8f5d2b6e3c19 status: type: string enum: - processing example: processing QualityEvaluationDone: title: Done type: object required: - job_id - status - segments - summary properties: job_id: type: string format: uuid example: f3a8c5e1-9b7d-4e62-a1c4-8f5d2b6e3c19 status: type: string enum: - done example: done segments: type: array description: One entry per submitted segment, in request order. items: $ref: '#/components/schemas/QualityEvaluationSegment' summary: type: object required: - overall_score - granular_counts description: Aggregate quality results across all segments. properties: overall_score: type: integer minimum: 0 maximum: 100 description: Overall translation quality, from 0 (lowest) to 100 (highest). See [Summary](/api-reference/quality-evaluation/poll#summary). example: 72 granular_counts: type: object description: Nested counts keyed by `type`, then `sub_type`, then `severity`. Leaf values are integer counts. additionalProperties: true example: Accuracy: Mistranslation: Critical: 1 Minor: 1 Omission: Major: 1 QualityEvaluationFailed: title: Error type: object required: - job_id - status - error properties: job_id: type: string format: uuid example: f3a8c5e1-9b7d-4e62-a1c4-8f5d2b6e3c19 status: type: string enum: - error example: error error: type: object required: - code - message properties: code: type: string description: Machine-readable error code. Currently always `evaluation_failed`. example: evaluation_failed message: type: string description: Error message. example: The evaluation pipeline encountered an unexpected error. QualityEvaluationSegment: type: object required: - segment_index - errors properties: segment_index: type: integer description: Zero-based index matching the position of this segment in the request. example: 0 errors: type: array description: Quality issues identified in this segment. Empty if no issues were found. items: $ref: '#/components/schemas/QualityEvaluationIssue' QualityEvaluationIssue: type: object required: - type - sub_type - severity - explanation - source_spans - target_spans properties: type: type: string description: Top-level category of the issue. See [Type and sub-type values](/api-reference/quality-evaluation/poll#type-and-sub-type-values). enum: - Accuracy - Fluency - Style - Miscellaneous example: Accuracy sub_type: type: string description: Finer-grained category within `type`. See [Type and sub-type values](/api-reference/quality-evaluation/poll#type-and-sub-type-values). enum: - Addition - Omission - Mistranslation - Over-translation - Under-translation - Untranslated text - Punctuation - Spelling - Grammar - Grammatical register - Inconsistency - Character encoding - Awkward - Inconsistent style example: Mistranslation severity: type: string description: How serious the issue is. See [Severity values](/api-reference/quality-evaluation/poll#severity-values). enum: - Critical - Major - Minor example: Critical explanation: type: string description: Description of the issue. May span multiple sentences. example: "The source says revenue was '5% above forecast' but the translation says '5 % unter der Prognose' (5% below forecast). This completely reverses the meaning and has financial implications." source_spans: type: array description: Spans on the segment's source text where this issue applies. Empty if no source-side highlight. See [About span ranges](/api-reference/quality-evaluation/poll#about-span-ranges). items: $ref: '#/components/schemas/QualityEvaluationSpan' target_spans: type: array description: Spans on the segment's target text where this issue applies. Empty if no target-side highlight. See [About span ranges](/api-reference/quality-evaluation/poll#about-span-ranges). items: $ref: '#/components/schemas/QualityEvaluationSpan' QualityEvaluationSpan: type: object required: - start - end description: A half-open `[start, end)` range of Unicode code points within a segment's source or target text. See [About span ranges](/api-reference/quality-evaluation/poll#about-span-ranges). properties: start: type: integer description: Inclusive start index. A 0-based Unicode code-point offset. example: 23 end: type: integer description: Exclusive end index. A 0-based Unicode code-point offset. example: 31 QualityEvaluationApiError: type: object required: - message properties: message: type: string description: Error message.