openapi.yaml

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
      * `xlsm` - Microsoft Excel Macro-Enabled Workbook (currently in beta)
      * `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
      * `vtt` - WebVTT Subtitle Document (currently in beta)
      * `idml` - Adobe InDesign Markup Language
      * `xml` - XML Document
      * `json` - JSON Document
      * `yaml / yml` - YAML Document (currently in beta)
      * `properties` - Java Properties Document (currently in beta)
      * `strings` - iOS/macOS Strings Document (currently in beta)
      * `md / markdown` - Markdown Document (currently in beta)
      * `dita` - DITA topic (Darwin Information Typing Architecture)
      * `mif` - Adobe FrameMaker Interchange Format
      * `zip` - SCORM Package (e-learning content, currently in beta)
      * `odt` - OpenDocument Text Document (currently in beta)
      * `rtf` - Rich Text Format Document (currently in beta)
      * `resx` - .NET Resource Document (currently in beta)
      * `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: |-
    **Beta.** Retrieve a quality evaluation report for a document DeepL has translated. Reports are requested with `enable_quality_evaluation` on `POST /v2/document` and polled here. A report lists 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
      description: |-
        Create a developer key in your organization with the given label and return its
        metadata, including the `key_id`. Requires an Admin API key.
      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
      description: |-
        List every developer key in your organization, including labels, creation and
        deactivation timestamps, and any configured usage limits. Requires an Admin API key.
      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
      description: |-
        Deactivate a developer key so it can no longer authenticate API requests.
        Deactivation is permanent: create a new key to restore access. Requires an Admin API key.
      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
      description: |-
        Change the label of a developer key. Labels are for your own bookkeeping and do not
        affect the key's permissions. Requires an Admin API key.
      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
      description: |-
        Set per-key usage limits for characters and speech-to-text milliseconds. Requests made
        with the key fail with HTTP 456 once a limit is reached. Requires an Admin API key.
      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
      description: |-
        Translate one or more text strings into a target language. Send multiple strings in a
        single request, within the request size limit, and specify formatting, tag handling,
        and customization options such as glossaries, style rules, and translation memories.
      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. A list
                    created for a root language (for example `en`) applies to that language and all of its variants
                    (`EN-GB`, `EN-US`). A list created for a variant (for example `en-GB`) applies only when
                    `target_lang` is that variant.

                    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
      description: |-
        Upload a document for translation and receive a `document_id` and `document_key`. Use
        them to poll the document status and download the translated file. Translation is
        asynchronous: the upload response confirms the request, not a finished translation.
      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
              SuppressImages:
                summary: Suppressing translation of embedded images (pptx only)
                value:
                  target_lang: DE
                  file: '@document.pptx'
                  input_conversion_options: 'version:1,suppress-image-types:all'
              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
              QualityEvaluation:
                summary: Requesting a quality evaluation report (beta)
                value:
                  source_lang: EN
                  target_lang: DE
                  file: '@document.docx'
                  enable_quality_evaluation: true
            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
                      * `xlsm` - Microsoft Excel Macro-Enabled Workbook (currently in beta)
                      * `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
                      * `vtt` - WebVTT Subtitle Document (currently in beta)
                      * `idml` - Adobe InDesign Markup Language
                      * `xml` - XML Document
                      * `json` - JSON Document
                      * `yaml / yml` - YAML Document (currently in beta)
                      * `properties` - Java Properties Document (currently in beta)
                      * `strings` - iOS/macOS Strings Document (currently in beta)
                      * `md / markdown` - Markdown Document (currently in beta)
                      * `dita` - DITA topic (Darwin Information Typing Architecture)
                      * `mif` - Adobe FrameMaker Interchange Format
                      * `zip` - SCORM Package (e-learning content, currently in beta)
                      * `odt` - OpenDocument Text Document (currently in beta)
                      * `rtf` - Rich Text Format Document (currently in beta)
                      * `resx` - .NET Resource Document (currently in beta)
                      * `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.
                input_conversion_options:
                  description: |-
                    Comma-separated list of `key:value` conversion options, prefixed with a version, that control how the input document is converted before translation. For example: `version:1,suppress-image-types:all`.

                    Supported keys:

                      * `suppress-image-types` - Leaves the specified types of images embedded in the document untranslated. The value is a hyphen-separated list of image content types (for example `logo-photo` suppresses logos and photos), or `all` to suppress every embedded image. Recognized image content types: `logo`, `icon`, `decorative`, `barcode`, `formula`, `signature`, `handwriting`, `stamp`, `screenshot`, `diagram`, `chart`, `photo`, `illustration`, `comic`, `music`, `infographic`, `table`, `text`, `other`, `unknown`. Only `pptx` documents support this key.
                      * `json-placeholders` - Controls how brace-delimited placeholders in `json` string values are handled. `protect` (the default) keeps identifier-shaped placeholders such as `{stars}` or `{{userName}}` verbatim so they are not translated; `translate` translates them along with the surrounding text. ICU MessageFormat skeletons such as `{count, plural, one {# item} other {# items}}` are always protected, with only the branch text translated, in both modes. Multi-word groups such as `{see note}` are treated as translatable text in both modes.

                    For other file types this parameter is ignored. Unrecognized keys are ignored.
                  type: string
                  example: version:1,suppress-image-types:all
                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. A list
                    created for a root language (for example `en`) applies to that language and all of its variants
                    (`EN-GB`, `EN-US`). A list created for a variant (for example `en-GB`) applies only when
                    `target_lang` is that variant.
                  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_quality_evaluation:
                  description: |-
                    (beta) When `true`, DeepL also evaluates the finished translation and returns a `quality_evaluation_job_id`. Poll [`GET /v1/quality-evaluations/{job_id}`](/api-reference/quality-evaluations/poll) with it for a per-segment report of translation issues. The translation itself is unaffected.

                    **Important:** Available to select customers; contact your customer success manager to enable it. Supported for `docx`, `pptx`, `pdf`, `srt`, `idml`, `xml`, `dita`, `mif`, and XLIFF 2.1 uploads, and for the [supported language pairs](/api-reference/quality-evaluations/poll#supported-language-pairs) only.

                    Rejected before the upload is accepted: `403` if quality evaluation is not enabled for the account, `400` for an ineligible file type, an unsupported language pair, or a value other than `true` or `false`.
                  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
                  quality_evaluation_job_id:
                    description: |-
                      (beta) A unique ID assigned to the quality evaluation. Returned only when the request set `enable_quality_evaluation=true`. Use it to retrieve the report from [`GET /v1/quality-evaluations/{job_id}`](/api-reference/quality-evaluations/poll).
                    type: string
                    example: 04DE5AD98A02647D83285A36021911C6
              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
      description: |-
        Retrieve the translation status of an uploaded document. Poll this endpoint until the
        status is `done`, then download the result. The response includes an estimated
        remaining time while the document is still translating.
      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
      description: |-
        Download a translated document. The document must have a status of `done`. Each
        document can be downloaded only once: after a successful download DeepL deletes the
        file and invalidates the `document_id`.
      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
      description: |-
        Create a glossary containing one or more dictionaries, each holding entries for a
        single source and target language pair. Use the returned `glossary_id` with the
        translation endpoints to apply your own preferred translations.
      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
      description: |-
        Delete the dictionary for a single source and target language pair from a glossary,
        leaving the glossary and its other dictionaries in place.
      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
      description: |-
        Replace all entries in the dictionary for a source and target language pair, or create
        the dictionary if it does not exist yet. Entries not included in the request are removed.
      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
      description: |-
        **For new integrations we recommend `POST /v3/glossaries`**, which supports multiple
        language pairs in a single glossary.

        Create a glossary for one source and target language pair and return its `glossary_id`.
      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
      description: |-
        Rewrite one or more texts to improve fluency and readability, optionally targeting a
        specific writing style or tone. Use the `correct` endpoint instead when you want a
        minimal spelling and grammar pass rather than broader rewriting.
      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':
          $ref: '#/components/responses/UnsupportedMediaType'
        '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':
          $ref: '#/components/responses/UnsupportedMediaType'
        '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
      description: |-
        Retrieve character and minute usage for the current billing period together with the
        corresponding account limits. Poll this endpoint to track consumption and detect when
        an account is approaching its quota.
      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
      description: |-
        List the style rule lists in your account. Results are paginated. Set `detailed` to
        include each list's configured rules and custom instructions.
      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
      description: |-
        Create a style rule list for a single language, optionally with its configured rules
        and custom instructions. The `language` can be a root code such as `de` or a variant
        code such as `de-CH`. Use the returned `style_id` with the translation endpoints
        to apply the list.
      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
      description: |-
        Retrieve a single style rule list, including its configured rules and custom instructions.
      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
      description: |-
        Rename a style rule list. This does not change its configured rules or custom instructions.
      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
      description: |-
        Delete a style rule list and its custom instructions. Requests that reference the
        deleted `style_id` fail afterwards.
      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
      description: |-
        Replace the full set of configured rules on a style rule list. Rules not included in
        the request are removed, so send the complete set you want to keep.
      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
      description: |-
        Add a custom instruction to a style rule list to express a style preference that the
        predefined rules do not cover. Instructions apply to text in the given source language.
      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
      description: |-
        Retrieve a single custom instruction from a style rule list.
      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
      description: |-
        Replace a custom instruction. Send every field you want to keep, because omitted
        fields are overwritten.
      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
      description: |-
        Delete a custom instruction from a style rule list. The rest of the list is unchanged.
      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
      description: |-
        Create a real-time voice session and return the WebSocket URL and ephemeral token used
        to stream audio. Session options such as languages, message format, and media types are
        fixed at creation time. Invalid options are rejected with HTTP 400 before a session is
        created.
      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.

                    In realtime Voice, glossary terms are matched against the streaming source transcription,
                    which affects how and when terms are applied. See
                    [Glossaries in realtime Voice](/docs/voice/overview#glossaries-in-realtime-voice).

                    Cannot be used together with `glossary_id`. Requests that exceed the
                    [session limit](/docs/voice/voice-api-requirements#session-limits), 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_speaker_match:
                summary: With translated audio using a speaker-matched voice
                value:
                  source_media_content_type: 'audio/ogg;codecs=opus'
                  source_language: 'en'
                  target_languages: ['de']
                  target_media_languages: ['de']
                  target_media_voice: 'match'
              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
      description: |-
        Exchange a session token for a fresh WebSocket URL and token so a client can rejoin a
        voice session after the connection drops. Session options are carried over from the
        original session.
      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-evaluations/{job_id}:
    get:
      tags:
        - QualityEvaluation
      summary: Poll for the evaluation result
      operationId: pollQualityEvaluation
      description: |-
        Returns the current state of a quality evaluation. While the evaluation is in progress the response carries only status information; once it completes, the response carries the full report.

        Evaluations are requested with `enable_quality_evaluation` on [`POST /v2/document`](/api-reference/document/upload-and-translate-a-document). There is no public endpoint for starting one.
      parameters:
        - name: job_id
          in: path
          required: true
          description: The unique ID of the quality evaluation, returned as `quality_evaluation_job_id` when the document was [uploaded for translation](/api-reference/document/upload-and-translate-a-document).
          schema:
            type: string
            example: 04DE5AD98A02647D83285A36021911C6
      responses:
        '200':
          description: |-
            Polling result. The response shape depends on the `status` field. `done` carries the full report; `error` carries error details.
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: '#/components/schemas/QualityEvaluationDone'
                  - $ref: '#/components/schemas/QualityEvaluationFailed'
              example:
                job_id: 04DE5AD98A02647D83285A36021911C6
                status: done
                segments:
                  - segment_index: 0
                    segment_score: 38.5
                    source: Our Q3 revenue came in 5% above forecast.
                    target: Unser Q3-Umsatz lag 5 % unter der Prognose.
                    applied_glossary_term_pairs:
                      - source_term: forecast
                        target_term: Prognose
                        ranges:
                          - start: 34
                            end: 42
                    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
                    segment_score: 62
                    source: Please share these results with your teams by Friday.
                    target: Bitte teilen Sie diese Ergebnisse mit Ihrem Team.
                    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
        '202':
          description: The evaluation is still running. 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: 04DE5AD98A02647D83285A36021911C6
                status: processing
        '400':
          description: The `job_id` is not a well-formed identifier.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/QualityEvaluationApiError'
              example:
                message: job_id must be a valid UUID.
        '404':
          description: |-
            No evaluation exists for this `job_id`, it belongs to another account, or it has expired. See [Report retention](/api-reference/quality-evaluations/poll#report-retention).
          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.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    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.
      content:
        application/json:
          schema:
            oneOf:
              - $ref: '#/components/schemas/ErrorResponse'
              - $ref: '#/components/schemas/InfrastructureErrorResponse'
    UnsupportedMediaTypeGlossaries:
      description: The requested entries format specified in the `Accept` header is
        not supported.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    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.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    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.
      content:
        application/json:
          schema:
            oneOf:
              - $ref: '#/components/schemas/ErrorResponse'
              - $ref: '#/components/schemas/InfrastructureErrorResponse'
    ServiceUnavailable:
      description: Resource currently unavailable. Try again later.
      content:
        application/json:
          schema:
            oneOf:
              - $ref: '#/components/schemas/ErrorResponse'
              - $ref: '#/components/schemas/InfrastructureErrorResponse'
    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 <api-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 target language the style rule list applies to. Codes are matched case-insensitively;
        the response returns the canonical form (for example `de-CH`).

        A root code (for example `en`) applies to that language and all of its variants. A variant
        code (for example `en-GB`) applies only when `target_lang` is that variant.

        Variant lists for `de-CH`, `fr-CA`, `pt-BR`, and `pt-PT` are generally available. Variant
        lists for `de-DE`, `en-GB`, `en-US`, `es-419`, `es-ES`, `fr-FR`, `zh-Hans`, and `zh-Hant`
        are in beta. The current list and the status of each language are returned by
        [`GET /v3/languages?resource=style_rules&include=beta`](/docs/languages/using-the-languages-api).
      type: string
      enum:
      - ar
      - bg
      - cs
      - da
      - de
      - de-CH
      - de-DE
      - el
      - en
      - en-GB
      - en-US
      - es
      - es-419
      - es-ES
      - et
      - fi
      - fr
      - fr-CA
      - fr-FR
      - he
      - hu
      - id
      - it
      - ja
      - ko
      - lt
      - lv
      - nb
      - nl
      - pl
      - pt
      - pt-BR
      - pt-PT
      - ro
      - ru
      - sk
      - sl
      - sv
      - th
      - tr
      - uk
      - vi
      - zh
      - zh-Hans
      - zh-Hant
    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
      - 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
      - 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'
      - '1'
    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). A value below 50 is treated as 50.
      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:
        ```
        <par>The firm said it had been </par><par> conducting an internal investigation.</par>
        ```
         * Example response:
        ```
        <par>Die Firma sagte, es sei eine gute Idee gewesen.</par><par> Durchführung einer internen Untersuchung.</par>
        ```


        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:
        ```
        <par>The firm said it had been </par><par> conducting an internal investigation.</par>
        ```
         * Example response:
        ```
        <par>Die Firma sagte, dass sie</par><par> eine interne Untersuchung durchgeführt</par><par> habe</par><par>.</par>
        ```


        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](/docs/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.

        Use `match` for speaker match, which produces translated speech with a voice close to
        the speaker's voice. Speaker match is only available for target languages whose translated
        speech is provided by DeepL, not for languages provided through external service partners.
        See the [supported languages table](/docs/voice/supported-voice-languages) for details.

        Requesting `match` for a target language that does not support it is not an error: the
        session is created and that language's translated speech uses a preset voice instead.
      type: string
      enum:
      - male
      - female
      - match
      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](/docs/voice/supported-voice-languages) for details.
      enum:
        - ar
        - bg
        - bn
        - ca
        - cs
        - da
        - de
        - el
        - en
        - es
        - et
        - fi
        - fr
        - ga
        - gl
        - 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
      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](/docs/voice/supported-voice-languages) for details.
      items:
        type: string
        enum:
          - ar
          - bg
          - bn
          - ca
          - cs
          - da
          - de
          - el
          - en
          - en-GB
          - en-US
          - es
          - es-419
          - et
          - fi
          - fr
          - fr-CA
          - fr-FR
          - ga
          - gl
          - 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](/docs/voice/supported-voice-languages) for details.
      items:
        type: string
        enum:
          - ar
          - bg
          - ca
          - cs
          - da
          - de
          - el
          - en
          - en-GB
          - en-US
          - es
          - es-419
          - fi
          - fr
          - fr-CA
          - fr-FR
          - gl
          - he
          - hi
          - hr
          - hu
          - id
          - it
          - ja
          - ko
          - ms
          - 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: 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
    InfrastructureErrorResponse:
      description: >
        Error body returned by DeepL's edge infrastructure for failures that occur before a
        request reaches the API itself. The message is nested under `error`, unlike the
        application-level `ErrorResponse`. Clients that parse error bodies should handle both shapes.
      type: object
      required:
        - error
      properties:
        error:
          type: object
          required:
            - message
          properties:
            message:
              type: string
              description: A human-readable description of the error.
              example: Bad Gateway.
    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'
    QualityEvaluationProcessing:
      type: object
      required:
        - job_id
        - status
      properties:
        job_id:
          type: string
          example: 04DE5AD98A02647D83285A36021911C6
        status:
          type: string
          enum:
            - processing
          example: processing
    QualityEvaluationDone:
      title: Done
      type: object
      required:
        - job_id
        - status
        - segments
      properties:
        job_id:
          type: string
          example: 04DE5AD98A02647D83285A36021911C6
        status:
          type: string
          enum:
            - done
          example: done
        segments:
          type: array
          description: One entry per evaluated segment of the document, in reading order.
          items:
            $ref: '#/components/schemas/QualityEvaluationSegment'
    QualityEvaluationFailed:
      title: Error
      type: object
      required:
        - job_id
        - status
        - error
      properties:
        job_id:
          type: string
          example: 04DE5AD98A02647D83285A36021911C6
        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
        - segment_score
        - errors
      properties:
        segment_index:
          type: integer
          description: Zero-based index of this segment within the document, in reading order.
          example: 0
        segment_score:
          type: number
          format: float
          minimum: 0
          maximum: 100
          description: Quality score for this segment, where 0 is lowest and 100 is highest.
          example: 38.5
        source:
          type: string
          description: The segment's source text as the evaluation read it. `source_spans` are offsets into this text. Omitted when the text is unavailable. See [Segment text](/api-reference/quality-evaluations/poll#segment-text).
          example: Our Q3 revenue came in 5% above forecast.
        target:
          type: string
          description: The segment's translated text as the evaluation read it. `target_spans` are offsets into this text. Omitted when the text is unavailable. See [Segment text](/api-reference/quality-evaluations/poll#segment-text).
          example: Unser Q3-Umsatz lag 5 % unter der Prognose.
        applied_glossary_term_pairs:
          type: array
          description: Glossary term pairs applied to this segment when the document was translated, so you can tell which customizations were in play where an issue was reported. Omitted when no term pair was applied.
          items:
            $ref: '#/components/schemas/QualityEvaluationAppliedGlossaryTermPair'
        errors:
          type: array
          description: Quality issues identified in this segment. Empty if no issues were found.
          items:
            $ref: '#/components/schemas/QualityEvaluationIssue'
    QualityEvaluationAppliedGlossaryTermPair:
      type: object
      description: A glossary term pair that was applied to the segment's translation.
      required:
        - source_term
        - target_term
        - ranges
      properties:
        source_term:
          type: string
          description: The source term, as defined in the glossary.
          example: forecast
        target_term:
          type: string
          description: The target term, as applied to the translation.
          example: Prognose
        ranges:
          type: array
          description: Spans in `target` where the target term was applied, using the same convention as `source_spans` and `target_spans`. See [Span ranges](/api-reference/quality-evaluations/poll#span-ranges).
          items:
            $ref: '#/components/schemas/QualityEvaluationSpan'
    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-evaluations/poll#type-and-sub-type-values).
          enum:
            - Accuracy
            - Fluency
            - Style
            - Miscellaneous
            - InternalTQEError
          example: Accuracy
        sub_type:
          type: string
          description: Finer-grained category within `type`. See [Type and sub-type values](/api-reference/quality-evaluations/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
            - SegmentTooLarge
          example: Mistranslation
        severity:
          type: string
          description: How serious the issue is. See [Severity values](/api-reference/quality-evaluations/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 [Span ranges](/api-reference/quality-evaluations/poll#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 [Span ranges](/api-reference/quality-evaluations/poll#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 [Span ranges](/api-reference/quality-evaluations/poll#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.