openapi_gitbook.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.5.0
externalDocs:
  description: DeepL Pro - Plans and pricing
  url: https://www.deepl.com/pro#developer
servers:
- url: https://api.deepl.com
  description: DeepL API Pro
- url: https://api-free.deepl.com
  description: DeepL API Free
tags:
- name: TranslateText
  description: |-
    The text-translation API currently consists of a single endpoint, `translate`, which is described below.
- name: TranslateDocuments
  description: |-
    The document translation API allows you to translate whole documents and supports the following file types and extensions:
      * `docx` - Microsoft Word Document
      * `pptx` - Microsoft PowerPoint Document
      * `xlsx` - Microsoft Excel Document
      * `pdf` - Portable Document Format
      * `htm / html` - HTML Document
      * `txt` - Plain Text Document
      * `xlf / xliff` - XLIFF Document, version 2.1
      * `srt` - SRT Document
- name: RephraseText
  description: |-
    The `rephrase` endpoint  is used to make corrections and adjustments to texts based on style or tone.
- name: ManageMultilingualGlossaries
  description: |-
    The *glossary* functions allow you to create, inspect, edit and delete glossaries.
    Glossaries created with the glossary function can be used in translate requests by specifying the
    `glossary_id` parameter. A glossary contains (several) dictionaries.
    A dictionary is a mapping of source phrases to target phrases for a single language pair.
    If you encounter issues, please let us know at support@DeepL.com.

    Currently you can create glossaries with any of the languages DeepL supports.

    The maximum size limit for a glossary is 10 MiB = 10485760 bytes and each source/target text,
    as well as the name of the glossary, is limited to 1024 UTF-8 bytes.
    A total of 1000 glossaries are allowed per account.

    When creating a dictionary with target language `EN`, `PT`, or `ZH`, it's not necessary to specify a variant
    (e.g. `EN-US`, `EN-GB`, `PT-PT`, `PT-BR`, or `ZH-HANS`).
    Dictionaries with target language `EN` can be used in translations with either English variant.
    Similarly `PT`, and `ZH` dictionaries can be used in translations with their corresponding variants.
    (When you provide the ID of a glossary to a translation, the appropriate dictionary is automatically applied. Currently glossaries can not yet be used with source language detection.)

    Glossaries created via the DeepL API are now unified with glossaries created via the DeepL website and DeepL apps.
    Please only use the v3 glossary API in conjunction with multilingual or edited glossaries from the website.
- name: ManageGlossaries
  description: |-
    Please note that this is the spec for the (old) v2 glossary endpoint.
    We recommend users switch to the newer v3 glossary endpoints, which support editability and multilinguality.

    The *glossary* functions allow you to create, inspect, and delete glossaries.
    Glossaries created with the glossary function can be used in translate requests by specifying the
    `glossary_id` parameter.
    If you encounter issues, please let us know at support@DeepL.com.

    Currently you can create glossaries with any of the languages DeepL supports.
- name: MetaInformation
  description: Information about API usage and value ranges
x-hideTryItPanel: true
x-codeSamples: false
paths:
  /v2/translate:
    post:
      tags:
      - TranslateText
      summary: Request Translation
      operationId: translateText
      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.
                  type: array
                  items:
                    type: string
                    example: Hello, World!
                source_lang:
                  $ref: '#/components/schemas/SourceLanguage'
                target_lang:
                  $ref: '#/components/schemas/TargetLanguageText'
                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.
                  type: string
                  example: def3a26b-3e84-45b3-84ae-0c0aaf3525f7
                tag_handling:
                  $ref: '#/components/schemas/TagHandlingOption'
                tag_handling_version:
                  $ref: '#/components/schemas/TagHandlingVersionOption'
                outline_detection:
                  $ref: '#/components/schemas/OutlineDetectionOption'
                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.
                  type: array
                  items:
                    type: string
                    example: Hello, World!
                source_lang:
                  $ref: '#/components/schemas/SourceLanguage'
                target_lang:
                  $ref: '#/components/schemas/TargetLanguageText'
                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.
                  type: string
                  example: def3a26b-3e84-45b3-84ae-0c0aaf3525f7
                tag_handling:
                  $ref: '#/components/schemas/TagHandlingOption'
                outline_detection:
                  $ref: '#/components/schemas/OutlineDetectionOptionStr'
                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.
          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

        400:
          $ref: '#/components/responses/BadRequest'
        403:
          $ref: '#/components/responses/Forbidden'
        404:
          $ref: '#/components/responses/NotFound'
        413:
          $ref: '#/components/responses/PayloadTooLarge'
        414:
          $ref: '#/components/responses/URITooLong'
        429:
          $ref: '#/components/responses/TooManyRequests'
        456:
          $ref: '#/components/responses/QuotaExceeded'
        500:
          $ref: '#/components/responses/InternalServerError'
        504:
          $ref: '#/components/responses/ServiceUnavailable'
        529:
          $ref: '#/components/responses/TooManyRequests'
      security:
      - auth_header: []
  /v2/document:
    post:
      tags:
      - TranslateDocuments
      summary: Upload and Translate a Document
      operationId: translateDocument
      requestBody:
        required: true
        content:
          multipart/form-data:
            examples:
              Basic:
                summary: Basic Document Translation
                value:
                  target_lang: DE
                  file: '@document.docx'
              Glossary:
                summary: Using a Glossary
                value:
                  source_lang: EN
                  target_lang: DE
                  file: '@document.docx'
                  glossary_id: '[yourGlossaryId]'
            schema:
              type: object
              required:
              - target_lang
              - file
              properties:
                source_lang:
                  $ref: '#/components/schemas/SourceLanguage'
                target_lang:
                  $ref: '#/components/schemas/TargetLanguage'
                file:
                  type: string
                  format: binary
                  description: |-
                    The document file to be translated. The file name should be included in this part's content disposition. As an alternative, the filename parameter can be used. The following file types and extensions are supported:
                      * `docx` - Microsoft Word Document
                      * `pptx` - Microsoft PowerPoint Document
                      * `xlsx` - Microsoft Excel Document
                      * `pdf` - Portable Document Format
                      * `htm / html` - HTML Document
                      * `txt` - Plain Text Document
                      * `xlf / xliff` - XLIFF Document, version 2.1
                      * `srt` - SRT Document
                filename:
                  type: string
                  description: The name of the uploaded file. Can be used as an alternative
                    to including the file name in the file part's content disposition.
                output_format:
                  type: string
                  description: |
                    File extension of desired format of translated file, for example: `docx`. If unspecified, by default the translated file will be in the same format as the input file.
                formality:
                  $ref: '#/components/schemas/Formality'
                glossary_id:
                  $ref: '#/components/schemas/GlossaryId'
      responses:
        200:
          description: The document function returns a JSON object containing the
            ID and encryption key assigned to the uploaded document. Once received
            by the server, uploaded documents are immediately encrypted using a uniquely
            generated encryption key. This key is not persistently stored on the server.
            Therefore, it must be stored by the client and sent back to the server
            with every subsequent request that refers to this particular document.
          content:
            application/json:
              schema:
                type: object
                properties:
                  document_id:
                    description: A unique ID assigned to the uploaded document and
                      the translation process. Must be used when referring to this
                      particular document in subsequent API requests.
                    type: string
                    example: 04DE5AD98A02647D83285A36021911C6
                  document_key:
                    description: A unique key that is used to encrypt the uploaded
                      document as well as the resulting translation on the server
                      side. Must be provided with every subsequent API request regarding
                      this particular document.
                    type: string
                    example: 0CB0054F1C132C1625B392EADDA41CB754A742822F6877173029A6C487E7F60A
              example:
                document_id: 04DE5AD98A02647D83285A36021911C6
                document_key: 0CB0054F1C132C1625B392EADDA41CB754A742822F6877173029A6C487E7F60A
        400:
          $ref: '#/components/responses/BadRequest'
        403:
          $ref: '#/components/responses/Forbidden'
        404:
          $ref: '#/components/responses/NotFound'
        413:
          $ref: '#/components/responses/PayloadTooLarge'
        429:
          $ref: '#/components/responses/TooManyRequests'
        456:
          $ref: '#/components/responses/QuotaExceeded'
        500:
          $ref: '#/components/responses/InternalServerError'
        504:
          $ref: '#/components/responses/ServiceUnavailable'
        529:
          $ref: '#/components/responses/TooManyRequests'
      security:
      - auth_header: []
  /v2/document/{document_id}:
    post:
      tags:
      - TranslateDocuments
      summary: Check Document Status
      operationId: getDocumentStatus
      parameters:
      - $ref: '#/components/parameters/DocumentID'
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/DocumentKey'
            examples:
              basic:
                summary: Basic
                value:
                  document_key: 0CB0054F1C132C1625B392EADDA41CB754A742822F6877173029A6C487E7F60A
          application/json:
            schema:
              $ref: '#/components/schemas/DocumentKey'
      responses:
        200:
          description: The document status request returns a JSON object containing
            the document ID that was used in the request as well as string indicating
            the current status of the translation process. While the translation is
            running, the estimated number of seconds remaining until the process is
            done is also included in the response.
          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/Forbidden'
        404:
          $ref: '#/components/responses/NotFound'
        413:
          $ref: '#/components/responses/PayloadTooLarge'
        429:
          $ref: '#/components/responses/TooManyRequests'
        456:
          $ref: '#/components/responses/QuotaExceeded'
        500:
          $ref: '#/components/responses/InternalServerError'
        504:
          $ref: '#/components/responses/ServiceUnavailable'
        529:
          $ref: '#/components/responses/TooManyRequests'
      security:
      - auth_header: []
  /v2/document/{document_id}/result:
    post:
      tags:
      - TranslateDocuments
      summary: Download Translated Document
      operationId: downloadDocument
      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.
          content:
            application/octet-stream:
              schema:
                type: string
                format: binary
              examples:
                OK:
                  summary: OK
                  description: binary document data
        400:
          $ref: '#/components/responses/BadRequest'
        403:
          $ref: '#/components/responses/Forbidden'
        404:
          $ref: '#/components/responses/NotFound404DocTransDownload'
        413:
          $ref: '#/components/responses/PayloadTooLarge'
        429:
          $ref: '#/components/responses/TooManyRequests'
        456:
          $ref: '#/components/responses/QuotaExceeded'
        500:
          $ref: '#/components/responses/InternalServerError'
        503:
          $ref: '#/components/responses/ServiceUnavailable503DocTransDownload'
        504:
          $ref: '#/components/responses/ServiceUnavailable'
        529:
          $ref: '#/components/responses/TooManyRequests'
      security:
      - auth_header: []
  /v2/glossary-language-pairs:
    get:
      tags:
      - ManageGlossaries
      summary: List Language Pairs Supported by Glossaries
      description: Retrieve the list of language pairs supported by the glossary feature.
      operationId: listGlossaryLanguages
      responses:
        200:
          description: A JSON object containing the language pairs in its `supported_languages`
            property.
          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
        401:
          $ref: '#/components/responses/Unauthorized'
        403:
          $ref: '#/components/responses/Forbidden'
        429:
          $ref: '#/components/responses/TooManyRequests'
        500:
          $ref: '#/components/responses/InternalServerError'
        503:
          $ref: '#/components/responses/ServiceUnavailable'
        529:
          $ref: '#/components/responses/TooManyRequests'
      security:
      - auth_header: []
  /v3/glossaries:
    post:
      tags:
      - ManageMultilingualGlossaries
      summary: Create a Glossary
      operationId: createMultilingualGlossary
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateMultilingualGlossaryParameters'
            examples:
              Basic:
                value:
                  name: My Glossary
                  dictionaries:
                  - source_lang: en
                    target_lang: de
                    entries: "Hello\tGuten Tag"
                    entries_format: tsv
                  - source_lang: de
                    target_lang: en
                    entries: "Guten Tag\tHello"
                    entries_format: tsv
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/CreateMultilingualGlossaryParameters'
      responses:
        201:
          description: The function for creating a glossary returns a JSON object
            containing the ID of the newly created glossary and a boolean flag that
            indicates if the created glossary can already be used in translate requests.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MultilingualGlossary'
        400:
          $ref: '#/components/responses/BadRequestGlossaries'
        401:
          $ref: '#/components/responses/Unauthorized'
        403:
          $ref: '#/components/responses/ForbiddenGlossaries'
        413:
          $ref: '#/components/responses/PayloadTooLarge'
        429:
          $ref: '#/components/responses/TooManyRequests'
        456:
          $ref: '#/components/responses/QuotaExceededGlossaries'
        500:
          $ref: '#/components/responses/InternalServerError'
        503:
          $ref: '#/components/responses/ServiceUnavailable'
        529:
          $ref: '#/components/responses/TooManyRequests'
      security:
      - auth_header: []
    get:
      tags:
      - ManageMultilingualGlossaries
      summary: List all Glossaries
      operationId: listMultilingualGlossaries
      description: List all glossaries and their meta-information, but not the glossary
        entries.
      responses:
        200:
          description: JSON object containing a the glossaries.
          content:
            application/json:
              schema:
                type: object
                properties:
                  glossaries:
                    type: array
                    items:
                      $ref: '#/components/schemas/MultilingualGlossary'
              example:
                glossaries:
                - glossary_id: def3a26b-3e84-45b3-84ae-0c0aaf3525f7
                  name: My Glossary
                  dictionaries:
                  - source_lang: EN
                    target_lang: DE
                    entry_count: 1
                  - source_lang: DE
                    target_lang: EN
                    entry_count: 2
                  creation_time: '2021-08-03T14:16:18.329Z'
        401:
          $ref: '#/components/responses/Unauthorized'
        403:
          $ref: '#/components/responses/Forbidden'
        429:
          $ref: '#/components/responses/TooManyRequests'
        500:
          $ref: '#/components/responses/InternalServerError'
        503:
          $ref: '#/components/responses/ServiceUnavailable'
        529:
          $ref: '#/components/responses/TooManyRequests'
      security:
      - auth_header: []
  /v3/glossaries/{glossary_id}:
    get:
      tags:
      - ManageMultilingualGlossaries
      summary: Retrieve Glossary Details
      description: Retrieve meta information for a single glossary, omitting the glossary
        entries.
      operationId: getMultilingualGlossary
      parameters:
      - $ref: '#/components/parameters/GlossaryID'
      responses:
        200:
          description: JSON object containing the glossary meta-information.
          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'
        401:
          $ref: '#/components/responses/Unauthorized'
        403:
          $ref: '#/components/responses/ForbiddenGlossaries'
        404:
          $ref: '#/components/responses/NotFound'
        429:
          $ref: '#/components/responses/TooManyRequests'
        500:
          $ref: '#/components/responses/InternalServerError'
        503:
          $ref: '#/components/responses/ServiceUnavailable'
        529:
          $ref: '#/components/responses/TooManyRequests'
      security:
      - auth_header: []
    patch:
      tags:
      - ManageMultilingualGlossaries
      summary: Edit glossary details
      description: Edit glossary details, such as name or a dictionary for a source and target language.
      operationId: patchMultilingualGlossary
      parameters:
      - $ref: '#/components/parameters/GlossaryID'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PatchMultilingualGlossaryParameters'
            examples:
              Basic:
                value:
                  name: My Glossary
                  dictionaries:
                    - source_lang: en
                      target_lang: de
                      entries: "Hello\tGuten Tag"
                      entries_format: tsv
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/PatchMultilingualGlossaryParameters'
      responses:
        200:
          description: JSON object containing the glossary meta-information.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MultilingualGlossary'
              example:
                glossary_id: def3a26b-3e84-45b3-84ae-0c0aaf3525f7
                name: My Glossary
                dictionaries:
                - source_lang: EN
                  target_lang: DE
                  creation_time: '2021-08-03T14:16:18.329Z'
                  entry_count: 1
                - source_lang: DE
                  target_lang: EN
                  creation_time: '2021-08-03T14:16:18.429Z'
                  entry_count: 2
        400:
          $ref: '#/components/responses/BadRequestGlossaries'
        401:
          $ref: '#/components/responses/Unauthorized'
        403:
          $ref: '#/components/responses/ForbiddenGlossaries'
        404:
          $ref: '#/components/responses/NotFound'
        413:
          $ref: '#/components/responses/PayloadTooLarge'
        429:
          $ref: '#/components/responses/TooManyRequests'
        456:
          $ref: '#/components/responses/QuotaExceededGlossaries'
        500:
          $ref: '#/components/responses/InternalServerError'
        503:
          $ref: '#/components/responses/ServiceUnavailable'
        529:
          $ref: '#/components/responses/TooManyRequests'
      security:
      - auth_header: []
    delete:
      tags:
      - ManageMultilingualGlossaries
      summary: Delete a Glossary
      description: Deletes the specified glossary.
      operationId: deleteMultilingualGlossary
      parameters:
      - $ref: '#/components/parameters/GlossaryID'
      responses:
        204:
          description: Returns no content upon success.
        400:
          $ref: '#/components/responses/BadRequestGlossaries'
        401:
          $ref: '#/components/responses/Unauthorized'
        403:
          $ref: '#/components/responses/ForbiddenGlossaries'
        404:
          $ref: '#/components/responses/NotFound'
        429:
          $ref: '#/components/responses/TooManyRequests'
        500:
          $ref: '#/components/responses/InternalServerError'
        503:
          $ref: '#/components/responses/ServiceUnavailable'
        529:
          $ref: '#/components/responses/TooManyRequests'
      security:
      - auth_header: []
  /v3/glossaries/{glossary_id}/entries:
    get:
      tags:
      - ManageMultilingualGlossaries
      summary: Retrieve Glossary Entries
      operationId: getMultilingualGlossaryEntries
      description: List the entries of a single glossary in tsv format.
      parameters:
      - $ref: '#/components/parameters/GlossaryID'
      - name: source_lang
        in: query
        required: true
        schema:
          $ref: '#/components/schemas/GlossarySourceLanguage'
      - name: target_lang
        in: query
        required: true
        schema:
          $ref: '#/components/schemas/GlossaryTargetLanguage'
      responses:
        200:
          description: The entries in tsv, wrapped in a JSON object.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GlossaryDictionary'
        400:
          $ref: '#/components/responses/BadRequestGlossaries'
        401:
          $ref: '#/components/responses/Unauthorized'
        403:
          $ref: '#/components/responses/ForbiddenGlossaries'
        404:
          $ref: '#/components/responses/NotFound'
        429:
          $ref: '#/components/responses/TooManyRequests'
        500:
          $ref: '#/components/responses/InternalServerError'
        503:
          $ref: '#/components/responses/ServiceUnavailable'
        529:
          $ref: '#/components/responses/TooManyRequests'
      security:
      - auth_header: []
  /v3/glossaries/{glossary_id}/dictionaries:
    delete:
      tags:
        - ManageMultilingualGlossaries
      summary: Deletes the dictionary associated with the given language pair with the given glossary ID.
      operationId: deleteDictionary
      parameters:
      - $ref: '#/components/parameters/GlossaryID'
      - name: source_lang
        in: query
        required: true
        schema:
          $ref: '#/components/schemas/GlossarySourceLanguage'
      - name: target_lang
        in: query
        required: true
        schema:
          $ref: '#/components/schemas/GlossaryTargetLanguage'
      responses:
        204:
          description: Returns no content upon success.
        400:
          $ref: '#/components/responses/BadRequestGlossaries'
        401:
          $ref: '#/components/responses/Unauthorized'
        403:
          $ref: '#/components/responses/ForbiddenGlossaries'
        404:
          $ref: '#/components/responses/NotFound'
        429:
          $ref: '#/components/responses/TooManyRequests'
        500:
          $ref: '#/components/responses/InternalServerError'
        503:
          $ref: '#/components/responses/ServiceUnavailable'
        529:
          $ref: '#/components/responses/TooManyRequests'
      security:
      - auth_header: []
    put:
      tags:
        - ManageMultilingualGlossaries
      summary: "Replaces or creates a dictionary in the glossary with the specified entries."
      operationId: replaceDictionary
      parameters:
        - $ref: '#/components/parameters/GlossaryID'
      requestBody:
        description: "The dictionary to insert into (or overwrite in) the multilingual glossary."
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/MultilingualGlossaryEntries'
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/PutMultilingualGlossaryParameters'
      responses:
        200:
          description: JSON object containing the dictionary meta-information.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MultilingualGlossaryEntriesInformation'
              example:
                source_lang: EN
                target_lang: DE
                entry_count: 1
        400:
          $ref: '#/components/responses/BadRequestGlossaries'
        401:
          $ref: '#/components/responses/Unauthorized'
        403:
          $ref: '#/components/responses/ForbiddenGlossaries'
        404:
          $ref: '#/components/responses/NotFound'
        413:
          $ref: '#/components/responses/PayloadTooLarge'
        429:
          $ref: '#/components/responses/TooManyRequests'
        456:
          $ref: '#/components/responses/QuotaExceededGlossaries'
        500:
          $ref: '#/components/responses/InternalServerError'
        503:
          $ref: '#/components/responses/ServiceUnavailable'
        529:
          $ref: '#/components/responses/TooManyRequests'
      security:
      - auth_header: []
  /v2/glossaries:
    post:
      tags:
      - ManageGlossaries
      summary: Create a Glossary
      operationId: createGlossary
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateGlossaryParameters'
            examples:
              Basic:
                value:
                  name: My Glossary
                  source_lang: en
                  target_lang: de
                  entries: "Hello\tGuten Tag"
                  entries_format: tsv
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/CreateGlossaryParameters'
      responses:
        201:
          description: The function for creating a glossary returns a JSON object
            containing the ID of the newly created glossary and a boolean flag that
            indicates if the created glossary can already be used in translate requests.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MonolingualGlossary'
        400:
          $ref: '#/components/responses/BadRequestGlossaries'
        401:
          $ref: '#/components/responses/Unauthorized'
        403:
          $ref: '#/components/responses/ForbiddenGlossaries'
        413:
          $ref: '#/components/responses/PayloadTooLarge'
        429:
          $ref: '#/components/responses/TooManyRequests'
        456:
          $ref: '#/components/responses/QuotaExceededGlossaries'
        500:
          $ref: '#/components/responses/InternalServerError'
        503:
          $ref: '#/components/responses/ServiceUnavailable'
        529:
          $ref: '#/components/responses/TooManyRequests'
      security:
      - auth_header: []
    get:
      tags:
      - ManageGlossaries
      summary: List all Glossaries
      operationId: listGlossaries
      description: List all glossaries and their meta-information, but not the glossary
        entries.
      responses:
        200:
          description: JSON object containing a the glossaries.
          content:
            application/json:
              schema:
                type: object
                properties:
                  glossaries:
                    type: array
                    items:
                      $ref: '#/components/schemas/MonolingualGlossary'
              example:
                glossaries:
                - glossary_id: def3a26b-3e84-45b3-84ae-0c0aaf3525f7
                  name: My Glossary
                  ready: true
                  source_lang: EN
                  target_lang: DE
                  creation_time: '2021-08-03T14:16:18.329Z'
                  entry_count: 1
        401:
          $ref: '#/components/responses/Unauthorized'
        403:
          $ref: '#/components/responses/Forbidden'
        429:
          $ref: '#/components/responses/TooManyRequests'
        500:
          $ref: '#/components/responses/InternalServerError'
        503:
          $ref: '#/components/responses/ServiceUnavailable'
        529:
          $ref: '#/components/responses/TooManyRequests'
      security:
      - auth_header: []
  /v2/glossaries/{glossary_id}:
    get:
      tags:
      - ManageGlossaries
      summary: Retrieve Glossary Details
      description: Retrieve meta information for a single glossary, omitting the glossary
        entries.
      operationId: getGlossary
      parameters:
      - $ref: '#/components/parameters/GlossaryID'
      responses:
        200:
          description: JSON object containing the glossary meta-information.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MonolingualGlossary'
              example:
                glossary_id: def3a26b-3e84-45b3-84ae-0c0aaf3525f7
                name: My Glossary
                ready: true
                source_lang: EN
                target_lang: DE
                creation_time: '2021-08-03T14:16:18.329Z'
                entry_count: 1
        400:
          $ref: '#/components/responses/BadRequestGlossaries'
        401:
          $ref: '#/components/responses/Unauthorized'
        403:
          $ref: '#/components/responses/ForbiddenGlossaries'
        404:
          $ref: '#/components/responses/NotFound'
        429:
          $ref: '#/components/responses/TooManyRequests'
        500:
          $ref: '#/components/responses/InternalServerError'
        503:
          $ref: '#/components/responses/ServiceUnavailable'
        529:
          $ref: '#/components/responses/TooManyRequests'
      security:
      - auth_header: []
    delete:
      tags:
      - ManageGlossaries
      summary: Delete a Glossary
      description: Deletes the specified glossary.
      operationId: deleteGlossary
      parameters:
      - $ref: '#/components/parameters/GlossaryID'
      responses:
        204:
          description: Returns no content upon success.
        400:
          $ref: '#/components/responses/BadRequestGlossaries'
        401:
          $ref: '#/components/responses/Unauthorized'
        403:
          $ref: '#/components/responses/ForbiddenGlossaries'
        404:
          $ref: '#/components/responses/NotFound'
        429:
          $ref: '#/components/responses/TooManyRequests'
        500:
          $ref: '#/components/responses/InternalServerError'
        503:
          $ref: '#/components/responses/ServiceUnavailable'
        529:
          $ref: '#/components/responses/TooManyRequests'
      security:
      - auth_header: []
  /v2/glossaries/{glossary_id}/entries:
    get:
      tags:
      - ManageGlossaries
      summary: Retrieve Glossary Entries
      operationId: getGlossaryEntries
      description: List the entries of a single glossary in the format specified by
        the `Accept` header.
      parameters:
      - $ref: '#/components/parameters/GlossaryID'
      - name: Accept
        in: header
        schema:
          type: string
          enum:
          - text/tab-separated-values
          default: text/tab-separated-values
        description: The requested format of the returned glossary entries. Currently,
          supports only `text/tab-separated-values`.
        examples:
          tsv:
            summary: Tab-separated Values
            value:
              in: header
              Accept: text/tab-separated-values
      responses:
        200:
          description: The entries in the requested format.
          content:
            text/tab-separated-values:
              example: "Hello!\tGuten Tag!"
        400:
          $ref: '#/components/responses/BadRequestGlossaries'
        401:
          $ref: '#/components/responses/Unauthorized'
        403:
          $ref: '#/components/responses/ForbiddenGlossaries'
        404:
          $ref: '#/components/responses/NotFound'
        415:
          $ref: '#/components/responses/UnsupportedMediaTypeGlossaries'
        429:
          $ref: '#/components/responses/TooManyRequests'
        500:
          $ref: '#/components/responses/InternalServerError'
        503:
          $ref: '#/components/responses/ServiceUnavailable'
        529:
          $ref: '#/components/responses/TooManyRequests'
      security:
      - auth_header: []
  /v2/write/rephrase:
    post:
      tags:
        - RephraseText
      summary: Request text improvement
      operationId: rephraseText
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - text
              properties:
                text:
                  description: Text to be improved. Only UTF-8-encoded plain text is supported. Improvements are
                    returned in the same order as they are requested.
                  type: array
                  items:
                    type: string
                    example: this is a example sentence to imprve
                target_lang:
                  $ref: '#/components/schemas/TargetLanguageWrite'
                writing_style:
                  $ref: '#/components/schemas/WritingStyle'
                tone:
                  $ref: '#/components/schemas/WritingTone'
          application/x-www-form-urlencoded:
            schema:
              type: object
              required:
                - text
              properties:
                text:
                  description: Text to be improved. Only UTF-8-encoded plain text is supported. Improvements are
                    returned in the same order as they are requested.
                  type: array
                  items:
                    type: string
                    example: this is a example sentence to imprve
                target_lang:
                  $ref: '#/components/schemas/TargetLanguageWrite'
                writing_style:
                  $ref: '#/components/schemas/WritingStyle'
                tone:
                  $ref: '#/components/schemas/WritingTone'
      responses:
        200:
          description: Successful text improvement.
          content:
            application/json:
              schema:
                type: object
                properties:
                  improvements:
                    type: array
                    minItems: 1
                    items:
                      type: object
                      properties:
                        detected_source_language:
                          description: The language detected in the source text.
                          type: string
                          example: en
                        text:
                          description: The improved text.
                          type: string
                          example: This is a sample sentence to improve.
      security:
        - auth_header: [ ]
  /v2/usage:
    get:
      tags:
      - MetaInformation
      summary: Check Usage and Limits
      operationId: getUsage
      responses:
        200:
          description: The account's usage and limits.
          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
                        api_key_character_count: 0
                        character_count: 5643
                      - product_type: translate
                        api_key_character_count: 636
                        character_count: 5941580
                    api_key_character_count: 636
                    api_key_character_limit: 1000000000000
                    start_time: '2025-05-13T09:18:42Z'
                    end_time: '2025-06-13T09:18:42Z'
        400:
          $ref: '#/components/responses/BadRequest'
        403:
          $ref: '#/components/responses/Forbidden'
        404:
          $ref: '#/components/responses/NotFound'
        413:
          $ref: '#/components/responses/PayloadTooLarge'
        429:
          $ref: '#/components/responses/TooManyRequests'
        456:
          $ref: '#/components/responses/QuotaExceeded'
        500:
          $ref: '#/components/responses/InternalServerError'
        504:
          $ref: '#/components/responses/ServiceUnavailable'
        529:
          $ref: '#/components/responses/TooManyRequests'
      security:
      - auth_header: []
  /v2/languages:
    get:
      tags:
      - MetaInformation
      summary: Retrieve Supported Languages
      operationId: getLanguages
      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.
          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
                supports_formality: false
              - language: BG
                name: Bulgarian
                supports_formality: false
              - language: CS
                name: Czech
                supports_formality: false
              - language: DA
                name: Danish
                supports_formality: false
              - language: DE
                name: German
                supports_formality: true
              - language: EL
                name: Greek
                supports_formality: false
              - language: EN-GB
                name: English (British)
                supports_formality: false
              - language: EN-US
                name: English (American)
                supports_formality: false
              - language: ES
                name: Spanish
                supports_formality: true
              - language: ES-419
                name: Spanish (Latin American)
                supports_formality: true
              - language: ET
                name: Estonian
                supports_formality: false
              - language: FI
                name: Finnish
                supports_formality: false
              - language: FR
                name: French
                supports_formality: true
              - language: HU
                name: Hungarian
                supports_formality: false
              - language: ID
                name: Indonesian
                supports_formality: false
              - language: IT
                name: Italian
                supports_formality: true
              - language: JA
                name: Japanese
                supports_formality: true
              - language: KO
                name: Korean
                supports_formality: false
              - language: LT
                name: Lithuanian
                supports_formality: false
              - language: LV
                name: Latvian
                supports_formality: false
              - language: NB
                name: Norwegian (Bokmål)
                supports_formality: false
              - language: NL
                name: Dutch
                supports_formality: true
              - language: PL
                name: Polish
                supports_formality: true
              - language: PT-BR
                name: Portuguese (Brazilian)
                supports_formality: true
              - language: PT-PT
                name: Portuguese (European)
                supports_formality: true
              - language: RO
                name: Romanian
                supports_formality: false
              - language: RU
                name: Russian
                supports_formality: true
              - language: SK
                name: Slovak
                supports_formality: false
              - language: SL
                name: Slovenian
                supports_formality: false
              - language: SV
                name: Swedish
                supports_formality: false
              - language: TR
                name: Turkish
                supports_formality: false
              - language: UK
                name: Ukrainian
                supports_formality: false
              - language: ZH
                name: Chinese (simplified)
                supports_formality: false
              - language: ZH-HANS
                name: Chinese (simplified)
                supports_formality: false
              - language: ZH-HANT
                name: Chinese (traditional)
                supports_formality: false
        400:
          $ref: '#/components/responses/BadRequest'
        403:
          $ref: '#/components/responses/Forbidden'
        404:
          $ref: '#/components/responses/NotFound'
        413:
          $ref: '#/components/responses/PayloadTooLarge'
        429:
          $ref: '#/components/responses/TooManyRequests'
        456:
          $ref: '#/components/responses/QuotaExceeded'
        500:
          $ref: '#/components/responses/InternalServerError'
        504:
          $ref: '#/components/responses/ServiceUnavailable'
        529:
          $ref: '#/components/responses/TooManyRequests'
      security:
      - auth_header: []
  /v2/admin/developer-keys:
    post:
      tags:
        - AdminApi
      summary: Create a developer key as an admin
      operationId: adminCreateDeveloperKey
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                label:
                  $ref: '#/components/schemas/ApiKeyLabel'
      responses:
        200:
          description: The create function returns a JSON representation of the created API key.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiKey'
        400:
          $ref: '#/components/responses/BadRequest'
        403:
          $ref: '#/components/responses/Forbidden'
        404:
          $ref: '#/components/responses/NotFound'
        500:
          $ref: '#/components/responses/InternalServerError'
      security:
        - auth_header: [ ]
    get:
      tags:
        - AdminApi
      summary: Get all developer keys as an admin
      operationId: adminGetDeveloperKeys
      responses:
        200:
          description: The get function returns a JSON representation of all developer API keys in the organization.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/ApiKey'
        400:
          $ref: '#/components/responses/BadRequest'
        403:
          $ref: '#/components/responses/Forbidden'
        404:
          $ref: '#/components/responses/NotFound'
        500:
          $ref: '#/components/responses/InternalServerError'
      security:
        - auth_header: [ ]
  /v2/admin/developer-keys/deactivate:
    put:
      tags:
        - AdminApi
      summary: Deactivate a developer key as an admin
      operationId: adminDeactivateDeveloperKey
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - key_id
              properties:
                key_id:
                  $ref: '#/components/schemas/ApiKeyId'          
      responses:
        200:
          description: The deactivate function returns a JSON representation of the deactivated API key.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiKey'
        400:
          $ref: '#/components/responses/BadRequest'
        403:
          $ref: '#/components/responses/Forbidden'
        404:
          $ref: '#/components/responses/NotFound'
        500:
          $ref: '#/components/responses/InternalServerError'
      security:
        - auth_header: [ ]
  /v2/admin/developer-keys/label:
    put:
      tags:
        - AdminApi
      summary: Rename a developer key as an admin
      operationId: adminRenameDeveloperKey
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - key_id
              - label
              properties:
                key_id:
                  $ref: '#/components/schemas/ApiKeyId'
                label:
                  type: string
                  description: API key label.
                  example: developer key prod
      responses:
        200:
          description: The set label function returns a JSON representation of the renamed API key.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiKey'
        400:
          $ref: '#/components/responses/BadRequest'
        403:
          $ref: '#/components/responses/Forbidden'
        404:
          $ref: '#/components/responses/NotFound'
        500:
          $ref: '#/components/responses/InternalServerError'
      security:
        - auth_header: [ ]
  /v2/admin/developer-keys/limits:
    put:
      tags:
        - AdminApi
      summary: Set developer key usage limits as an admin
      operationId: adminSetDeveloperKeyUsageLimits
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - key_id
              properties:
                key_id:
                  $ref: '#/components/schemas/ApiKeyId'
                characters:
                  $ref: '#/components/schemas/ApiKeyUsageCharacters'
      responses:
        200:
          description: The set usage limits function returns a JSON representation of the modified API key.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiKey'
        400:
          $ref: '#/components/responses/BadRequest'
        403:
          $ref: '#/components/responses/Forbidden'
        404:
          $ref: '#/components/responses/NotFound'
        500:
          $ref: '#/components/responses/InternalServerError'
      security:
        - auth_header: []
  /v2/admin/analytics:
    get:
      tags:
        - AdminApi
      summary: Get usage statistics as an admin
      operationId: adminGetAnalytics
      description: |-
        Retrieve usage statistics for the organization within a specified date range.
        Optionally group the results by API key or by API key and day.
      parameters:
      - name: start_date
        in: query
        required: true
        description: Start date for the usage report (ISO 8601 date format).
        schema:
          type: string
          format: date
        example: "2025-09-29"
      - name: end_date
        in: query
        required: true
        description: End date for the usage report (ISO 8601 date format).
        schema:
          type: string
          format: date
        example: "2025-10-01"
      - name: group_by
        in: query
        required: false
        description: |-
          Optional parameter to group usage statistics. Possible values:
           * `key` - Group by API key
           * `key_and_day` - Group by API key and usage date
        schema:
          type: string
          enum:
          - key
          - key_and_day
        example: "key_and_day"
      responses:
        200:
          description: The usage statistics for the specified date range.
          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
                      group_by: "key_and_day"
                      start_date: "2025-09-29T00:00:00"
                      end_date: "2025-10-01T00:00:00"
                      grouped_usage:
                      - 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
                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
                      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.
          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: [ ]
components:
  parameters:
    DocumentID:
      name: document_id
      description: The document ID that was sent to the client when the document was
        uploaded to the API.
      in: path
      required: true
      schema:
        type: string
      example: 04DE5AD98A02647D83285A36021911C6
    GlossaryID:
      name: glossary_id
      description: A unique ID assigned to the glossary.
      in: path
      required: true
      schema:
        type: string
    SourceLanguage:
      name: source_lang
      in: query
      schema:
        $ref: '#/components/schemas/SourceLanguage'
    TargetLanguage:
      name: target_lang
      in: query
      required: true
      schema:
        $ref: '#/components/schemas/TargetLanguage'
  responses:
    BadRequest:
      description: Bad request. Please check error message and your parameters.
    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.
    Forbidden:
      description: Authorization failed. Please supply a valid `DeepL-Auth-Key` via
        the `Authorization` header.
    ForbiddenGlossaries:
      description: Forbidden. The access to the requested resource is denied, because
        of insufficient access rights.
    NotFound:
      description: The requested resource could not be found.
    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.
    URITooLong:
      description: The request URL is too long. You can avoid this error by using
        a POST request instead of a GET request, and sending the parameters in the
        HTTP body.
    UnsupportedMediaTypeGlossaries:
      description: The requested entries format specified in the `Accept` header is
        not supported.
    TooManyRequests:
      description: Too many requests. Please wait and resend your request.
    QuotaExceeded:
      description: Quota exceeded. The character limit has been reached.
    QuotaExceededGlossaries:
      description: Quota exceeded. Too many requests were made to the glossary endpoints recently.
    InternalServerError:
      description: Internal error.
    ServiceUnavailable:
      description: Resource currently unavailable. Try again later.
    ServiceUnavailable503DocTransDownload:
      description: |-
        A 503 result will be returned if the user tries to download a translated document that is currently being processed and is not yet ready for download.
        Please make sure to check that the document status is 'done' before trying to send a download request.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/DocumentTranslationError'
          examples:
            AlreadyDownloaded:
              summary: Already Downloaded
              value:
                message: Document already downloaded
  securitySchemes:
    auth_header:
      type: apiKey
      description: Authentication with `Authorization` header and `DeepL-Auth-Key`
        authentication scheme
      name: Authorization
      in: header
  schemas:
    ApiKeyId:
      description: API key ID. Consists of two valid GUIDs separated by a colon.
      type: string
      example: ca7d5694-96eb-4263-a9a4-7f7e4211529e:20c2abcf-4c3c-4cd6-8ae8-8bd2a7d4da38
    ApiKeyLabel:
      description: API key label. The default value is `DeepL API Key`.
      type: string
      example: "developer key prod"
    ApiKeyUsageCharacters:
      description: |
        Restricts the number of total characters (across text translation, document translation, and text improvement) that can be consumed by an API key in a one-month usage period.
        Setting the limit to `0` means the API key will not be able to consume characters.
        Setting the limit to `null` disables the limit, effectively allowing unlimited usage.
      type: number
      example: 5000
    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'
    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](https://developers.deepl.com/docs/api-reference/glossaries#formats) for details about each format.
          type: string
          enum:
          - tsv
          - csv
          example: tsv
          default: tsv
    CreateMultilingualGlossaryParameters:
      type: object
      required:
      - name
      - dictionaries
      properties:
        name:
          description: Name to be associated with the glossary.
          type: string
          example: My Glossary
        dictionaries:
          description: Dictionaries to populate the glossary with.
          type: array
          items:
            $ref: '#/components/schemas/GlossaryDictionary'
    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'
    GlossaryEntries:
      type: string
      description: The entries of the glossary. The entries have to be specified
        in the format provided by the `entries_format` parameter.
      example: "Hello\tGuten Tag"
    GlossaryEntriesFormat:
      description: |-
        The format in which the glossary entries are provided. Formats currently available:
        - `tsv` (default) - tab-separated values
        - `csv` - comma-separated values

        See [Supported Glossary Formats](https://www.deepl.com/docs-api/glossaries/formats) for details about each format.
      type: string
      enum:
      - tsv
      - csv
      example: tsv
      default: tsv
    GlossaryEntryCount:
      description: The number of entries in the glossary.
      type: integer
    GlossaryId:
      type: string
      description: A unique ID assigned to a glossary.
      example: def3a26b-3e84-45b3-84ae-0c0aaf3525f7
    GlossaryName:
      description: Name associated with the glossary.
      type: string
    GlossarySourceLanguage:
      type: string
      description: The language in which the source texts in the glossary are specified.
      enum:
      - ar
      - bg
      - cs
      - da
      - de
      - el
      - en
      - es
      - et
      - fi
      - fr
      - he
      - hu
      - id
      - it
      - ja
      - ko
      - lt
      - lv
      - nb
      - nl
      - pl
      - pt
      - ro
      - ru
      - sk
      - sl
      - sv
      - th
      - tr
      - uk
      - vi
      - zh
      example: en
    GlossaryTargetLanguage:
      type: string
      description: The language in which the target texts in the glossary are specified.
      enum:
      - ar
      - bg
      - cs
      - da
      - de
      - el
      - en
      - es
      - et
      - fi
      - fr
      - he
      - hu
      - id
      - it
      - ja
      - ko
      - lt
      - lv
      - nb
      - nl
      - pl
      - pt
      - ro
      - ru
      - sk
      - sl
      - sv
      - th
      - tr
      - uk
      - vi
      - zh
      example: de
    ModelType:
      type: string
      description: Specifies which DeepL model should be used for translation.
      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.

        Note: for requests sent as URL-encoded forms, boolean values should be specified as "1" or "0".
      type: boolean
      default: true
    OutlineDetectionOptionStr:
      description: |-
        Disable the automatic detection of XML structure by setting the `outline_detection` parameter 
        to `false` and selecting the tags that should be considered structure tags. This will split sentences 
        using the `splitting_tags` parameter.
      type: string
      default: '1'
      enum:
      - '0'
    PatchMultilingualGlossaryParameters:
      type: object
      properties:
        name:
          $ref: '#/components/schemas/GlossaryId'
        dictionaries:
          description: Dictionaries to edit the glossary with. Currently only supports 0 or 1 dictionaries in the array.
          type: array
          items:
            $ref: '#/components/schemas/GlossaryDictionary'
    PreserveFormattingOption:
      description: |-
        Sets whether the translation engine should respect the original formatting, even if it would usually 
        correct some aspects.

        Note: for requests sent as URL-encoded forms, boolean values should be specified as "1" or "0".
      type: boolean
      default: false
    PreserveFormattingOptionStr:
      description: |-
        Sets whether the translation engine should respect the original formatting, even if it would usually 
        correct some aspects.
      type: string
      enum:
      - '0'
      - '1'
      default: '0'
    PutMultilingualGlossaryParameters:
      $ref: '#/components/schemas/MultilingualGlossaryEntries'
    ShowBilledCharacters:
      description: |-
        When true, the response will include the billed_characters parameter, giving the 
        number of characters from the request that will be counted by DeepL for billing purposes.

        Note: for requests sent as URL-encoded forms, boolean values should be specified as "1" or "0".
      type: boolean  
    SplitSentencesOption:
      description: |-
        Sets whether the translation engine should first split the input into sentences. 

        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.
      enum:
      - AR
      - BG
      - CS
      - DA
      - DE
      - EL
      - EN
      - ES
      - ET
      - FI
      - FR
      - HU
      - ID
      - IT
      - JA
      - KO
      - LT
      - LV
      - NB
      - NL
      - PL
      - PT
      - RO
      - RU
      - SK
      - SL
      - SV
      - TR
      - UK
      - ZH
      example: EN
    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:
         * `v2`: Improved algorithm released in October 2025 (default as of December 2025).
         * `v1`: Traditional algorithm (default until December 2025).
      type: string
      enum:
      - v1
      - v2
    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.
      enum:
      - AR
      - BG
      - CS
      - DA
      - DE
      - EL
      - EN-GB
      - EN-US
      - ES
      - ES-419
      - ET
      - FI
      - FR
      - HU
      - ID
      - IT
      - JA
      - KO
      - LT
      - LV
      - NB
      - NL
      - PL
      - PT-BR
      - PT-PT
      - RO
      - RU
      - SK
      - SL
      - SV
      - TR
      - UK
      - ZH
      - ZH-HANS
      - ZH-HANT
      example: DE
    TargetLanguageText:
      type: string
      description: |-
        The language into which the text should be translated.
      enum:
      - AR
      - BG
      - CS
      - DA
      - DE
      - EL
      - EN-GB
      - EN-US
      - ES
      - ES-419
      - ET
      - FI
      - FR
      - HU
      - ID
      - IT
      - JA
      - KO
      - LT
      - LV
      - NB
      - NL
      - PL
      - PT-BR
      - PT-PT
      - RO
      - RU
      - SK
      - SL
      - SV
      - TR
      - UK
      - ZH
      - ZH-HANS
      - ZH-HANT
      example: DE
    TargetLanguageWrite:
      type: string
      description: |-
        The language for the text improvement.
      enum:
      - de
      - en
      - en-GB
      - en-US
      - es
      - fr
      - it
      - pt
      - pt-BR
      - pt-PT
      example: de
    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"
        grouped_usage:
          type: array
          description: Array of usage statistics grouped by the specified criteria. Only present when group_by parameter is provided.
          items:
            $ref: '#/components/schemas/GroupedUsageItem'
    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
    GroupedUsageItem:
      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'
    UsageResponse:
      type: object
      properties:
        character_count:
          description: Characters translated so far in the current billing period.
          type: integer
          format: int64
          example: 180118
        character_limit:
          description: Current maximum number of characters that can be translated per billing period. If cost control is set, the cost control limit will be returned in this field.
          type: integer
          format: int64
          example: 1250000
        products:
          type: array
          description: Only present for API Pro users. Per-product usage details.
          items:
            type: object
            properties:
              product_type:
                type: string
                description: The type of product (e.g., 'write', 'translate').
                example: write
              api_key_character_count:
                type: integer
                description: Characters used for this product by this API key in the current period.
                example: 0
              character_count:
                type: integer
                description: Total characters used for this product in the current period.
                example: 5643
        api_key_character_count:
          type: integer
          description: Only present for API Pro users. Total characters used by this API key in the current period.
          example: 636
        api_key_character_limit:
          type: integer
          description: Only present for API Pro users. Character limit for this API key in the current period.
          example: 1000000000000
        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'