DeepL Web TranslatorCreate Free API AccountContact Us

Glossaries

Manage and use DeepL glossaries

This page documents v3 glossary endpoints, which let you edit glossaries and makes them multilingual.

See here for information on v2 glossaries. See here for an overview of the difference.

Overview

The glossaries endpoints let you work with DeepL glossaries, which let you specify specific translations for words or short phrases. Each glossary contains a mapping of source phrases to target phrases. During translation, DeepL intelligently flexes entries to account for case, gender, tense, and other grammar features (if the target language has flexion).

Currently you can create glossaries with any of the languages DeepL supports. Any updates will be noted here, as well as in the /languages endpoint and documentation.

A glossary contains (several) dictionaries. A dictionary is a mapping of source phrases to target phrases for a single language pair, like this:

French ->
Spanish

belle

hermosa

delicieux

exquisito

mouse

mouse

Note that this mapping occurs only in one direction, which is all you need during a single translation. If you wanted your glossary to contain the reverse mapping, so that you could apply the same glossary when translating from French to Spanish and from Spanish to French, you would add a second dictionary:

Spanish ->
French

hermosa

belle

exquisito

delicieux

mouse

mouse

Creating glossaries

Formats

You can format glossary entries as either CSV (comma-separated values) or TSV (tab-separated values). In each case, each entry is a line containing a source phrase and its associated target phrase.

CSV entries for our Spanish → French glossary above would look like this:

hermosa,belle
exquisito,delicieux
mouse,mouse

You can also enclose each phrase in quotation marks:

"hermosa","belle"
"exquisito","delicieux"
"mouse","mouse"

TSV is similar, except that the source and target phrases are separated by a tab, not a comma.

CSV entries in DeepL glossaries follow standard CSV conventions, such as

  • fields containing double quotes or commas must be enclosed in double quotes,

  • if double quotes are used to enclose fields, then a double quote appearing inside a field must be escaped by preceding it with another double quote.

In CSV, you can also include the source and target language after the source and target phrases. If those do not match the language pair for the current dictionary, the entry will be ignored.

Create a glossary

POST /v3/glossaries

To create a glossary, send the API an array that contains one or more dictionaries. (As described above, a dictionary is a collection of mappings from source phrases in one language to target phrases in another.)

This example creates a modest glossary with two dictionaries. One maps "Hello" in English to "Guten Tag" in German. The other contains the reverse mapping.

The example below uses our API Pro endpoint https://api.deepl.com. If you're an API Free user, remember to update your requests to use https://api-free.deepl.com instead.

Example request: create a glossary
curl -X POST 'https://api.deepl.com/v3/glossaries' \
--header 'Authorization: DeepL-Auth-Key [yourAuthKey]' \
--header 'Content-Type: application/json' \
--data '{
  "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"
    }
  ]
}'
Example response
{
  "glossary_id": "def3a26b-3e84-45b3-84ae-0c0aaf3525f7",
  "ready": true,
  "name": "My Glossary",
  "dictionaries": [
    {
      "source_lang": "en",
      "target_lang": "de",
      "entry_count": 1
    },
    {
      "source_lang": "de",
      "target_lang": "en",
      "entry_count": 1
    }
  ],
  "creation_time": "2025-08-03T14:16:18.329Z"
}

Using

POST /v2/translate

To use a glossary in a translation request, include its glossary_id . You must also specify both the source and target languages, like this:

The example below uses our API Pro endpoint https://api.deepl.com. If you're an API Free user, remember to update your requests to use https://api-free.deepl.com instead.

Example request: translate including glossary
curl -X POST 'https://api.deepl.com/v2/translate' \
--header 'Authorization: DeepL-Auth-Key [yourAuthKey] \
--header 'Content-Type: application/json' \
--data '{
  "text": [
    "Hello"
  ],
  "source_lang": "EN",
  "target_lang": "DE",
  "glossary_id": [yourGlossaryID]
}'
Example response
{
  "translations": [
    {
      "detected_source_language": "EN",
      "text": "Guten Tag"
    }
  ]
}

Currently the v3 endpoints only handle glossary methods. Use v2 for all other functionality, including translation.

Retrieving glossaries

List all glossaries

GET /v3/glossaries

Use this endpoint to list all your glossaries, basic information about each glossary's dictionaries, and each glossary's name and creation time. The response will not include any dictionary entries.

The example below uses our API Pro endpoint https://api.deepl.com. If you're an API Free user, remember to update your requests to use https://api-free.deepl.com instead.

Example request: list glossaries
curl -X GET 'https://api.deepl.com/v3/glossaries' \
--header 'Authorization: DeepL-Auth-Key [yourAuthKey]'
Example response
{
  "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": 3,
      }],
      "creation_time": "2021-08-03T14:16:18.329Z"
    }
  ]
}

Get glossary metadata

GET /v3/glossaries/{glossary_id}

Use this endpoint to retrieve basic information about a given glossary's dictionaries, plus the glossary's name and creation time.

The example below uses our API Pro endpoint https://api.deepl.com. If you're an API Free user, remember to update your requests to use https://api-free.deepl.com instead.

Example request: retrieve glossary details
curl -X GET 'https://api.deepl.com/v3/glossaries/{glossaryId}' \
--header 'Authorization: DeepL-Auth-Key [yourAuthKey]'
Example response
{
  "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": 1
    }
  ],
  "creation_time": "2025-08-03T14:16:18.329Z"
}

Get glossary entries

GET /v3/glossaries/{glossaryId}/entries?source_lang={language}&target_lang={language}

Use this endpoint to retrieve the contents of a single glossary dictionary by specifying the dictionary's language pair.

Currently you can only retrieve glossary contents in TSV format.

The example below uses our API Pro endpoint https://api.deepl.com. If you're an API Free user, remember to update your requests to use https://api-free.deepl.com instead.

Example request: get glossary entries
curl -X GET 'https://api.deepl.com/v3/glossaries/{glossaryId}/entries?source_lang=en&target_lang=de' \
--header 'Authorization: DeepL-Auth-Key [yourAuthKey]' \
--header 'Content-Type: application/json'
Example response
{
  "dictionaries": [{
    "source_lang": "en",
    "target_lang": "de",
    "entries": "Hello\tGuten Tag",
    "entries_format": "tsv",
  }]
}

To retrieve the contents of an entire glossary, iterate through each of dictionaries, retrieving the content of each. While we work to provide the ability to retrieve a whole glossary in a single call, your feedback here is valuable as we strive to improve our API.

Editing

Add a new dictionary, or replace an existing one

PUT /v3/glossaries/{glossaryId}/dictionaries

The PUT method acts on a single dictionary of a glossary. It creates a new dictionary in that glossary, or replaces an existing one, without regard to whether that dictionary already exists. If the glossary has no dictionary for a given language pair, add the dictionary to the glossary with the entries provided. If the dictionary already exists, replace it.

Use this method to add a new dictionary to a glossary or replace an existing one. To instead merge a set of entries with an existing dictionary, use the PATCH method.

The example below uses our API Pro endpoint https://api.deepl.com. If you're an API Free user, remember to update your requests to use https://api-free.deepl.com instead.

Example request: replace a dictionary
curl -X PUT 'https://api.deepl.com/v3/glossaries/{glossaryId}/dictionaries' \
--header 'Authorization: DeepL-Auth-Key [yourAuthKey]' \
--header 'Content-Type: application/json' \
--data '{
  "source_lang": "en",
  "target_lang": "de",
  "entries": "Hello\tGuten Tag",
  "entries_format": "tsv"
}'
Example response
{
  "source_lang": "en",
  "target_lang": "de",
  "entry_count": 1
}

Add new entries to a dictionary, or replace existing entries

PATCH /v3/glossaries/{glossaryId}

While the PUT method operates on a single dictionary, PATCH affects an element of an entire glossary. This element could be a piece of metadata - like the glossary's name - or a dictionary for a particular language pair.

This method returns the glossary's name and metadata on each of its dictionaries.

For example, this PATCH changes a glossary's name.

The example below uses our API Pro endpoint https://api.deepl.com. If you're an API Free user, remember to update your requests to use https://api-free.deepl.com instead.

Example request: update glossary entries
curl -X PATCH 'https://api.deepl.com/v3/glossaries/{glossaryId}' \
--header 'Authorization: DeepL-Auth-Key [yourAuthKey]' \
--header 'Content-Type: application/json' \
--data '{
  "name": "Gus the glossary"
}'
Example response
{
  "glossary_id": "def3a26b-3e84-45b3-84ae-0c0aaf3525f7",
  "name": "Gus the glossary",
  "dictionaries": [
    {
      "source_lang": "en",
      "target_lang": "de",
      "entry_count": 1
    }
  ],
  "creation_time": "2025-08-03T14:16:18.329Z"
}

You can also use PATCH to change the contents of a glossary's dictionary for a language pair while taking any existing dictionary for that language pair into account. If the glossary already has a dictionary for the specified language pair, the entries passed here will be merged with the existing dictionary.

Use this method to make changes to an existing dictionary. To replace a dictionary outright, use the PUT method.

This example makes two changes. It changes the glossary's name, and it adds a new entry to its German → English dictionary.

The example below uses our API Pro endpoint https://api.deepl.com. If you're an API Free user, remember to update your requests to use https://api-free.deepl.com instead.

Example request: update glossary entries
curl -X PATCH 'https://api.deepl.com/v3/glossaries/{glossaryId}' \
--header 'Authorization: DeepL-Auth-Key [yourAuthKey]' \
--header 'Content-Type: application/json' \
--data '{
  "name": "Gertrude the glossary"
  "dictionaries": [{
    "source_lang": "en",
    "target_lang": "de",
    "entries": "Goodbye\tTschüß",
    "entries_format": "tsv",
  }]
}'
Example response
{
  "glossary_id": "def3a26b-3e84-45b3-84ae-0c0aaf3525f7",
  "name": "Gertrude the glossary",
  "dictionaries": [
    {
      "source_lang": "en",
      "target_lang": "de",
      "entry_count": 2
    }
  ],
  "creation_time": "2025-08-03T14:16:18.329Z"
}

Currently, a given PUT and PATCH can make changes to a single dictionary. To change the target phrase for a given source phrase for multiple languages, you need to make multiple API calls. While we work to support multiple dictionaries in future updates, your feedback here is valuable as we work to improve our API.

Deleting glossaries

Delete a glossary

DELETE /v3/glossaries/{glossary_id}

This method deletes the specified glossary in its entirety.

The example below uses our API Pro endpoint https://api.deepl.com. If you're an API Free user, remember to update your requests to use https://api-free.deepl.com instead.

Example request: delete a glossary
curl -X DELETE 'https://api.deepl.com/v3/glossaries/{glossary_id}' \
--header 'Authorization: DeepL-Auth-Key [yourAuthKey]'

Delete a glossary's dictionary

DELETE /v3/glossaries/{glossary_id}/dictionaries?source_lang={source_lang}&target_lang={target_lang}

Use this method to delete a dictionary for a specific language pair.

The example below uses our API Pro endpoint https://api.deepl.com. If you're an API Free user, remember to update your requests to use https://api-free.deepl.com instead.

Example request: delete a dictionary
curl -X DELETE 'https://api.deepl.com/v3/glossaries/{glossary_id}/dictionaries?source_lang={source_lang}&target_lang={target_lang}' \
--header 'Authorization: DeepL-Auth-Key [yourAuthKey]'

Notes on usage

Language variants

Glossaries apply to languages, not specific language variants. A glossary for a language applies to any variant of that language.

For example, if you create a glossary with target language EN , that glossary will apply to EN-US and EN-GB. A glossary with target language PR will apply to PT-PT and PT-BR.

Source language detection

Glossaries can not (yet) be used in translation requests that do not set a specific source language. your feedback here is valuable as we strive to improve our API.

Restrictions

Size

A dictionary can contain a maximum of 10 MB. This is true for each dictionary in a glossary. So, if a glossary contains five dictionaries, each if its dictionaries could contain up to 10 MB, for a total of 50 MB.

The name of the glossary, each source phrase, and each target phrase, can contain up to 1024 UTF-8 bytes.

The number of glossaries you can make is limited by your plan.

Sharing

Presently, you cannot share glossaries between the DeepL API and DeepL's web or phone apps. Work is underway to end this restriction.

Content

  • Duplicate source entries are not allowed.

  • Neither the source nor the target entry may be empty.

  • The source and target entries must not contain any C0 or C1 control characters (including, e.g., \t or \n) or any Unicode newline.

  • Source and target entries must not contain any leading or trailing Unicode whitespace characters.

Last updated