DeepL Manage Glossaries API

openapi: 3.2.0
info:
  title: DeepL API Documentation Manage Glossaries API
  description: 'The DeepL API provides programmatic access to DeepL’s language AI technology.


    Note: this OpenAPI spec is embedded into our API documentation and has shortened descriptions.'
  termsOfService: https://www.deepl.com/pro-license
  contact:
    name: DeepL - Contact us
    url: https://www.deepl.com/contact-us
  version: 3.13.0
servers:
- url: https://api.deepl.com
  description: DeepL API Pro
- url: https://api-free.deepl.com
  description: DeepL API Free
tags:
- name: ManageGlossaries
  description: 'Please note that this is the spec for the (old) v2 glossary endpoint.

    We recommend users switch to the newer v3 glossary endpoints, which support editability and multilinguality.


    The *glossary* functions allow you to create, inspect, and delete glossaries.

    Glossaries created with the glossary function can be used in translate requests by specifying the

    `glossary_id` parameter.

    If you encounter issues, please let us know at support@DeepL.com.


    Currently you can create glossaries with any of the languages DeepL supports (with the exception of Thai).'
paths:
  /v2/glossary-language-pairs:
    get:
      deprecated: true
      tags:
      - ManageGlossaries
      summary: List Language Pairs Supported by Glossaries
      description: '**Deprecated.** Use `GET /v3/languages?resource=glossary` instead, which returns per-language

        availability including source and target roles.


        Retrieve the list of language pairs supported by the glossary feature.'
      operationId: listGlossaryLanguages
      responses:
        '200':
          description: A JSON object containing the language pairs in its `supported_languages` property.
          headers:
            X-Trace-ID:
              $ref: '#/components/headers/X-Trace-ID'
          content:
            application/json:
              schema:
                type: object
                properties:
                  supported_languages:
                    type: array
                    description: The list of supported languages
                    items:
                      type: object
                      required:
                      - source_lang
                      - target_lang
                      properties:
                        source_lang:
                          description: The language in which the source texts in the glossary are specified.
                          type: string
                          example: en
                        target_lang:
                          description: The language in which the target texts in the glossary are specified.
                          type: string
                          example: de
              example:
                supported_languages:
                - source_lang: de
                  target_lang: en
                - source_lang: en
                  target_lang: de
        '400':
          $ref: '#/components/responses/BadRequestGlossaries'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/ForbiddenGlossaries'
        '404':
          $ref: '#/components/responses/NotFound'
        '413':
          $ref: '#/components/responses/PayloadTooLarge'
        '415':
          $ref: '#/components/responses/UnsupportedMediaTypeGlossaries'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '456':
          $ref: '#/components/responses/QuotaExceededGlossaries'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
        '529':
          $ref: '#/components/responses/TooManyRequests'
      security:
      - auth_header: []
  /v2/glossaries:
    post:
      tags:
      - ManageGlossaries
      summary: Create a Glossary
      operationId: createGlossary
      description: '**For new integrations we recommend `POST /v3/glossaries`**, which supports multiple

        language pairs in a single glossary.


        Create a glossary for one source and target language pair and return its `glossary_id`.'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateGlossaryParameters'
            examples:
              Basic:
                value:
                  name: My Glossary
                  source_lang: en
                  target_lang: de
                  entries: "Hello\tGuten Tag"
                  entries_format: tsv
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/CreateGlossaryParameters'
      responses:
        '201':
          description: The function for creating a glossary returns a JSON object containing the ID of the newly created glossary and a boolean flag that indicates if the created glossary can already be used in translate requests.
          headers:
            X-Trace-ID:
              $ref: '#/components/headers/X-Trace-ID'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MonolingualGlossary'
        '400':
          $ref: '#/components/responses/BadRequestGlossaries'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/ForbiddenGlossaries'
        '404':
          $ref: '#/components/responses/NotFound'
        '413':
          $ref: '#/components/responses/PayloadTooLarge'
        '415':
          $ref: '#/components/responses/UnsupportedMediaTypeGlossaries'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '456':
          $ref: '#/components/responses/QuotaExceeded'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
        '529':
          $ref: '#/components/responses/TooManyRequests'
      security:
      - auth_header: []
    get:
      tags:
      - ManageGlossaries
      summary: List all Glossaries
      operationId: listGlossaries
      description: List all glossaries and their meta-information, but not the glossary entries.
      responses:
        '200':
          description: JSON object containing a the glossaries.
          headers:
            X-Trace-ID:
              $ref: '#/components/headers/X-Trace-ID'
          content:
            application/json:
              schema:
                type: object
                properties:
                  glossaries:
                    type: array
                    items:
                      $ref: '#/components/schemas/MonolingualGlossary'
              example:
                glossaries:
                - glossary_id: def3a26b-3e84-45b3-84ae-0c0aaf3525f7
                  name: My Glossary
                  ready: true
                  source_lang: EN
                  target_lang: DE
                  creation_time: '2021-08-03T14:16:18.329Z'
                  entry_count: 1
        '400':
          $ref: '#/components/responses/BadRequestGlossaries'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/ForbiddenGlossaries'
        '404':
          $ref: '#/components/responses/NotFound'
        '413':
          $ref: '#/components/responses/PayloadTooLarge'
        '415':
          $ref: '#/components/responses/UnsupportedMediaTypeGlossaries'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '456':
          $ref: '#/components/responses/QuotaExceeded'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
        '529':
          $ref: '#/components/responses/TooManyRequests'
      security:
      - auth_header: []
  /v2/glossaries/{glossary_id}:
    get:
      tags:
      - ManageGlossaries
      summary: Retrieve Glossary Details
      description: Retrieve meta information for a single glossary, omitting the glossary entries.
      operationId: getGlossary
      parameters:
      - $ref: '#/components/parameters/GlossaryID'
      responses:
        '200':
          description: JSON object containing the glossary meta-information.
          headers:
            X-Trace-ID:
              $ref: '#/components/headers/X-Trace-ID'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MonolingualGlossary'
              example:
                glossary_id: def3a26b-3e84-45b3-84ae-0c0aaf3525f7
                name: My Glossary
                ready: true
                source_lang: EN
                target_lang: DE
                creation_time: '2021-08-03T14:16:18.329Z'
                entry_count: 1
        '400':
          $ref: '#/components/responses/BadRequestGlossaries'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/ForbiddenGlossaries'
        '404':
          $ref: '#/components/responses/NotFound'
        '413':
          $ref: '#/components/responses/PayloadTooLarge'
        '415':
          $ref: '#/components/responses/UnsupportedMediaTypeGlossaries'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '456':
          $ref: '#/components/responses/QuotaExceeded'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
        '529':
          $ref: '#/components/responses/TooManyRequests'
      security:
      - auth_header: []
    delete:
      tags:
      - ManageGlossaries
      summary: Delete a Glossary
      description: Deletes the specified glossary.
      operationId: deleteGlossary
      parameters:
      - $ref: '#/components/parameters/GlossaryID'
      responses:
        '204':
          description: Returns no content upon success.
        '400':
          $ref: '#/components/responses/BadRequestGlossaries'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/ForbiddenGlossaries'
        '404':
          $ref: '#/components/responses/NotFound'
        '413':
          $ref: '#/components/responses/PayloadTooLarge'
        '415':
          $ref: '#/components/responses/UnsupportedMediaTypeGlossaries'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '456':
          $ref: '#/components/responses/QuotaExceeded'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
        '529':
          $ref: '#/components/responses/TooManyRequests'
      security:
      - auth_header: []
  /v2/glossaries/{glossary_id}/entries:
    get:
      tags:
      - ManageGlossaries
      summary: Retrieve Glossary Entries
      operationId: getGlossaryEntries
      description: List the entries of a single glossary in the format specified by the `Accept` header.
      parameters:
      - $ref: '#/components/parameters/GlossaryID'
      - name: Accept
        in: header
        schema:
          type: string
          default: text/tab-separated-values
        description: The requested format of the returned glossary entries. Currently, supports only `text/tab-separated-values`.
        examples:
          tsv:
            summary: Tab-separated Values
            value:
              in: header
              Accept: text/tab-separated-values
      responses:
        '200':
          description: The entries in the requested format.
          headers:
            X-Trace-ID:
              $ref: '#/components/headers/X-Trace-ID'
          content:
            text/tab-separated-values:
              example: "Hello!\tGuten Tag!"
        '400':
          $ref: '#/components/responses/BadRequestGlossaries'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/ForbiddenGlossaries'
        '404':
          $ref: '#/components/responses/NotFound'
        '413':
          $ref: '#/components/responses/PayloadTooLarge'
        '415':
          $ref: '#/components/responses/UnsupportedMediaTypeGlossaries'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '456':
          $ref: '#/components/responses/QuotaExceeded'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
        '529':
          $ref: '#/components/responses/TooManyRequests'
      security:
      - auth_header: []
components:
  responses:
    QuotaExceededGlossaries:
      description: Quota exceeded. Too many requests were made to the glossary endpoints recently.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    Unauthorized:
      description: Authorization failed. Please supply a valid `DeepL-Auth-Key` via the `Authorization` header.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    ServiceUnavailable:
      description: Resource currently unavailable. Try again later.
      content:
        application/json:
          schema:
            oneOf:
            - $ref: '#/components/schemas/ErrorResponse'
            - $ref: '#/components/schemas/InfrastructureErrorResponse'
    TooManyRequests:
      description: Too many requests. Please wait and resend your request.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    InternalServerError:
      description: Internal error.
      content:
        application/json:
          schema:
            oneOf:
            - $ref: '#/components/schemas/ErrorResponse'
            - $ref: '#/components/schemas/InfrastructureErrorResponse'
    ForbiddenGlossaries:
      description: Forbidden. The access to the requested resource is denied, because of insufficient access rights. This error is also returned when the API key is scoped but does not include the scope required for this endpoint.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    NotFound:
      description: The requested resource could not be found.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    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)
    PayloadTooLarge:
      description: The request size exceeds the limit.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    UnsupportedMediaTypeGlossaries:
      description: The requested entries format specified in the `Accept` header is not supported.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    QuotaExceeded:
      description: Quota exceeded. The character limit has been reached.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
  headers:
    X-Trace-ID:
      description: A unique identifier for the request that can be included in bug reports to DeepL support.
      schema:
        type: string
      example: 501c3d93cc0c4f11ae2f60a226c2f0f0
  schemas:
    InfrastructureErrorResponse:
      description: 'Error body returned by DeepL''s edge infrastructure for failures that occur before a request reaches the API itself. The message is nested under `error`, unlike the application-level `ErrorResponse`. Clients that parse error bodies should handle both shapes.

        '
      type: object
      required:
      - error
      properties:
        error:
          type: object
          required:
          - message
          properties:
            message:
              type: string
              description: A human-readable description of the error.
              example: Bad Gateway.
    ErrorResponse:
      type: object
      required:
      - message
      properties:
        message:
          type: string
          description: A human-readable description of the error.
        code:
          type: string
          description: A machine-readable identifier for the error, when available. Clients should match on this value rather than on `message` when branching on error types.
          example: invalid_content_type
    GlossaryTargetLanguage:
      type: string
      description: The language in which the target texts in the glossary are specified.
      enum:
      - ar
      - bg
      - cs
      - da
      - de
      - el
      - en
      - es
      - et
      - fi
      - fr
      - he
      - hu
      - id
      - it
      - ja
      - ko
      - lt
      - lv
      - nb
      - nl
      - pl
      - pt
      - ro
      - ru
      - sk
      - sl
      - sv
      - tr
      - uk
      - vi
      - zh
      example: de
    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
    GlossaryId:
      type: string
      description: A unique ID assigned to a glossary.
      example: def3a26b-3e84-45b3-84ae-0c0aaf3525f7
    CreateGlossaryParameters:
      type: object
      required:
      - name
      - source_lang
      - target_lang
      - entries
      - entries_format
      properties:
        name:
          description: Name to be associated with the glossary.
          type: string
          example: My Glossary
        source_lang:
          $ref: '#/components/schemas/GlossarySourceLanguage'
        target_lang:
          $ref: '#/components/schemas/GlossaryTargetLanguage'
        entries:
          description: The entries of the glossary. The entries have to be specified in the format provided by the `entries_format` parameter.
          type: string
          example: "Hello\tGuten Tag"
        entries_format:
          description: 'The format in which the glossary entries are provided. Formats currently available:

            - `tsv` (default) - tab-separated values

            - `csv` - comma-separated values


            See [Supported Glossary Formats](/docs/customize/managing-glossaries#entry-formats) for details about each format.'
          type: string
          enum:
          - tsv
          - csv
          example: tsv
          default: tsv
    GlossarySourceLanguage:
      type: string
      description: The language in which the source texts in the glossary are specified.
      enum:
      - ar
      - bg
      - cs
      - da
      - de
      - el
      - en
      - es
      - et
      - fi
      - fr
      - he
      - hu
      - id
      - it
      - ja
      - ko
      - lt
      - lv
      - nb
      - nl
      - pl
      - pt
      - ro
      - ru
      - sk
      - sl
      - sv
      - tr
      - uk
      - vi
      - zh
      example: en
  parameters:
    GlossaryID:
      name: glossary_id
      description: A unique ID assigned to the glossary.
      in: path
      required: true
      schema:
        type: string
  securitySchemes:
    auth_header:
      type: apiKey
      description: 'Authentication with `Authorization` header and `DeepL-Auth-Key` authentication scheme. Example: `DeepL-Auth-Key <api-key>`

        '
      name: Authorization
      in: header
      x-default: 'DeepL-Auth-Key '
externalDocs:
  description: DeepL Pro - Plans and pricing
  url: https://www.deepl.com/pro#developer
x-hideTryItPanel: true
x-codeSamples: false
x-provenance:
  method: harvested
  publisher: DeepL
  source: https://developers.deepl.com/api-reference/openapi.yaml
  note: split by refine-openapis from the provider's own published document, verified by fetch (openapi/_original/*.fetch.json);
    stamped by stamp-openapi-provenance.py (roadmap#793)