Glossaries - DeepL Documentation

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"
}

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"
}

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

POST /v3/glossaries HTTP/2
Host: api.deepl.com
Authorization: DeepL-Auth-Key [yourAuthKey] 
User-Agent: YourApp/1.2.3
Content-Length: 1234
Content-Type: application/json

{
  "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"
    }
  ]
}

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"
    }
  ]
}

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"
    }
  ]
}

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

POST /v2/translate HTTP/2
Host: api.deepl.com
Authorization: DeepL-Auth-Key [yourAuthKey] 
User-Agent: YourApp/1.2.3
Content-Length: 111
Content-Type: application/json

{
  "text": [
    "Hello there"
  ],
  "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"
    }
  ]
}

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"
    }
  ]
}

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 all glossaries

GET /v3/glossaries HTTP/2
Host: api.deepl.com
Authorization: DeepL-Auth-Key [yourAuthKey] 
User-Agent: YourApp/1.2.3

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": "2025-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"
}

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"
}

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

GET /v3/glossaries/{glossary_id} HTTP/2
Host: api.deepl.com
Authorization: DeepL-Auth-Key [yourAuthKey] 
User-Agent: YourApp/1.2.3

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",
  }]
}

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",
  }]
}

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

GET /v3/glossaries/{glossary_id}/entries HTTP/2
Host: api.deepl.com
Authorization: DeepL-Auth-Key [yourAuthKey] 
User-Agent: YourApp/1.2.3

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
}

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
}

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

PUT /v3/glossaries/{glossaryId}/dictionaries HTTP/2
Host: api.deepl.com
Authorization: DeepL-Auth-Key [yourAuthKey] 
User-Agent: YourApp/1.2.3
Content-Length: 210
Content-Type: application/json

{"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"
}

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"
}

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

PATCH /v3/glossaries/{glossaryId} HTTP/2
Host: api.deepl.com
Authorization: DeepL-Auth-Key [yourAuthKey] 
User-Agent: YourApp/1.2.3
Content-Length: 147
Content-Type: application/json

{"name": "My updated glossary", "dictionaries": [{"source_lang": "en","target_lang": "de","entries": "Hello\tGuten Tag", "entries_format": "tsv"}]}

Example response

{
  "glossary_id": "def3a26b-3e84-45b3-84ae-0c0aaf3525f7",
  "name": "My updated 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"
}

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"
}

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

PATCH /v3/glossaries/{glossaryId} HTTP/2
Host: api.deepl.com
Authorization: DeepL-Auth-Key [yourAuthKey] 
User-Agent: YourApp/1.2.3
Content-Length: 147
Content-Type: application/json

{"name": "My updated glossary", "dictionaries": [{"source_lang": "en","target_lang": "de","entries": "Hello\tGuten Tag", "entries_format": "tsv"}]}

Example response

{
  "glossary_id": "def3a26b-3e84-45b3-84ae-0c0aaf3525f7",
  "name": "My updated glossary",
  "dictionaries": [
    {
      "source_lang": "en",
      "target_lang": "de",
      "entry_count": 1
    }
  ],
  "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]'

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]'

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

DELETE /v3/glossaries/{glossary_id} HTTP/2
Host: api.deepl.com
Authorization: DeepL-Auth-Key [yourAuthKey] 
User-Agent: YourApp/1.2.3

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]'

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]'

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

DELETE /v3/glossaries/{glossary_id}/dictionaries?source_lang={source_lang}&target_lang={target_lang} HTTP/2
Host: api.deepl.com
Authorization: DeepL-Auth-Key [yourAuthKey] 
User-Agent: YourApp/1.2.3

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.

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.

On this page

Overview
Creating glossaries
Formats
Create a glossary
Using
Retrieving glossaries
List all glossaries
Get glossary metadata
Get glossary entries
Editing
Add a new dictionary, or replace an existing one
Add new entries to a dictionary, or replace existing entries
Deleting glossaries
Delete a glossary
Delete a glossary’s dictionary
Notes on usage
Language variants
Source language detection
Restrictions
Size
Sharing
Content

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

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

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

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"
}

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"
}

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

POST /v3/glossaries HTTP/2
Host: api.deepl.com
Authorization: DeepL-Auth-Key [yourAuthKey] 
User-Agent: YourApp/1.2.3
Content-Length: 1234
Content-Type: application/json

{
  "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"
    }
  ]
}

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"
    }
  ]
}

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"
    }
  ]
}

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

POST /v2/translate HTTP/2
Host: api.deepl.com
Authorization: DeepL-Auth-Key [yourAuthKey] 
User-Agent: YourApp/1.2.3
Content-Length: 111
Content-Type: application/json

{
  "text": [
    "Hello there"
  ],
  "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

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"
    }
  ]
}

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"
    }
  ]
}

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 all glossaries

GET /v3/glossaries HTTP/2
Host: api.deepl.com
Authorization: DeepL-Auth-Key [yourAuthKey] 
User-Agent: YourApp/1.2.3

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": "2025-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"
}

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"
}

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

GET /v3/glossaries/{glossary_id} HTTP/2
Host: api.deepl.com
Authorization: DeepL-Auth-Key [yourAuthKey] 
User-Agent: YourApp/1.2.3

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",
  }]
}

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",
  }]
}

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

GET /v3/glossaries/{glossary_id}/entries HTTP/2
Host: api.deepl.com
Authorization: DeepL-Auth-Key [yourAuthKey] 
User-Agent: YourApp/1.2.3

Example response

{
  "dictionaries": [{
    "source_lang": "en",
    "target_lang": "de",
    "entries": "Hello\tGuten Tag",
    "entries_format": "tsv",
  }]
}

Editing

Add a new dictionary, or replace an existing one

PUT /v3/glossaries/{glossaryId}/dictionaries

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
}

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
}

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

PUT /v3/glossaries/{glossaryId}/dictionaries HTTP/2
Host: api.deepl.com
Authorization: DeepL-Auth-Key [yourAuthKey] 
User-Agent: YourApp/1.2.3
Content-Length: 210
Content-Type: application/json

{"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}

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"
}

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"
}

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

PATCH /v3/glossaries/{glossaryId} HTTP/2
Host: api.deepl.com
Authorization: DeepL-Auth-Key [yourAuthKey] 
User-Agent: YourApp/1.2.3
Content-Length: 147
Content-Type: application/json

{"name": "My updated glossary", "dictionaries": [{"source_lang": "en","target_lang": "de","entries": "Hello\tGuten Tag", "entries_format": "tsv"}]}

Example response

{
  "glossary_id": "def3a26b-3e84-45b3-84ae-0c0aaf3525f7",
  "name": "My updated glossary",
  "dictionaries": [
    {
      "source_lang": "en",
      "target_lang": "de",
      "entry_count": 1
    }
  ],
  "creation_time": "2025-08-03T14:16:18.329Z"
}

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"
}

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"
}

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

PATCH /v3/glossaries/{glossaryId} HTTP/2
Host: api.deepl.com
Authorization: DeepL-Auth-Key [yourAuthKey] 
User-Agent: YourApp/1.2.3
Content-Length: 147
Content-Type: application/json

{"name": "My updated glossary", "dictionaries": [{"source_lang": "en","target_lang": "de","entries": "Hello\tGuten Tag", "entries_format": "tsv"}]}

Example response

{
  "glossary_id": "def3a26b-3e84-45b3-84ae-0c0aaf3525f7",
  "name": "My updated glossary",
  "dictionaries": [
    {
      "source_lang": "en",
      "target_lang": "de",
      "entry_count": 1
    }
  ],
  "creation_time": "2025-08-03T14:16:18.329Z"
}

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]'

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]'

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

DELETE /v3/glossaries/{glossary_id} HTTP/2
Host: api.deepl.com
Authorization: DeepL-Auth-Key [yourAuthKey] 
User-Agent: YourApp/1.2.3

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]'

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]'

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

DELETE /v3/glossaries/{glossary_id}/dictionaries?source_lang={source_lang}&target_lang={target_lang} HTTP/2
Host: api.deepl.com
Authorization: DeepL-Auth-Key [yourAuthKey] 
User-Agent: YourApp/1.2.3

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

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.

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.

On this page

Overview
Creating glossaries
Formats
Create a glossary
Using
Retrieving glossaries
List all glossaries
Get glossary metadata
Get glossary entries
Editing
Add a new dictionary, or replace an existing one
Add new entries to a dictionary, or replace existing entries
Deleting glossaries
Delete a glossary
Delete a glossary’s dictionary
Notes on usage
Language variants
Source language detection
Restrictions
Size
Sharing
Content

​Overview

​Creating glossaries

​Formats

​Create a glossary

​Using

​Retrieving glossaries

​List all glossaries

​Get glossary metadata

​Get glossary entries

​Editing

​Add a new dictionary, or replace an existing one

​Add new entries to a dictionary, or replace existing entries

​Deleting glossaries

​Delete a glossary

​Delete a glossary’s dictionary

​Notes on usage

​Language variants

​Source language detection

​Restrictions

​Size

​Sharing

​Content

API Reference

​Overview

​Creating glossaries

​Formats

​Create a glossary

​Using

​Retrieving glossaries

​List all glossaries

​Get glossary metadata

​Get glossary entries

​Editing

​Add a new dictionary, or replace an existing one

​Add new entries to a dictionary, or replace existing entries

​Deleting glossaries

​Delete a glossary

​Delete a glossary’s dictionary

​Notes on usage

​Language variants

​Source language detection

​Restrictions

​Size

​Sharing

​Content

Overview

Creating glossaries

Formats

Create a glossary

Using

Retrieving glossaries

List all glossaries

Get glossary metadata

Get glossary entries

Editing

Add a new dictionary, or replace an existing one

Add new entries to a dictionary, or replace existing entries

Deleting glossaries

Delete a glossary

Delete a glossary’s dictionary

Notes on usage

Language variants

Source language detection

Restrictions

Size

Sharing

Content

Overview

Creating glossaries

Formats

Create a glossary

Using

Retrieving glossaries

List all glossaries

Get glossary metadata

Get glossary entries

Editing

Add a new dictionary, or replace an existing one

Add new entries to a dictionary, or replace existing entries

Deleting glossaries

Delete a glossary

Delete a glossary’s dictionary

Notes on usage

Language variants

Source language detection

Restrictions

Size

Sharing

Content