This page documents v2 glossary endpoints, legacy endpoints that let you create and manage glossaries for a single language pair.

See here for information on v3 endpoints, which allow you to create, manage, and edit glossaries with entries in multiple language pairs. See here for an overview of the difference.

This page describes how to use the v2 endpoints to work with monolingual glossaries - glossaries that map phrases in one language to phrases in another language. If you’re new to glossaries, we suggest you use v3 instead. v3 allows you to work with multilingual glossaries, and it lets you edit any glossaries as well.

​
Create a glossary

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/v2/glossaries' \
--header 'Authorization: DeepL-Auth-Key [yourAuthKey]' \
--header 'Content-Type: application/json' \
--data '{
  "name": "My Glossary",
  "source_lang": "en",
  "target_lang": "de",
  "entries": "Hello\tGuten Tag",
  "entries_format": "tsv"
}'
Example response
{
  "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
}

The following example shows how to create a glossary from an example csv file (glossary.csv, with 2 example entries) via the command line using jq. Note that you’ll need to install jq if you haven’t already. Installation instructions for various operating systems are available here.

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.

Create file + example request
cat >glossary.csv <<EOL
Hello,Hallo
World,Welt
EOL

curl -X POST 'https://api.deepl.com/v2/glossaries' \
--header 'Authorization: DeepL-Auth-Key [yourAuthKey]' \
--header 'Content-Type: application/json' \
--data "$(jq -Rs '{
  "name": "My Glossary",
  "source_lang": "en",
  "target_lang": "de",
  "entries": .,
  "entries_format": "csv"
}' glossary.csv)"
Example response
{
  "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": 2
}

​
List all glossaries

List all glossaries and their meta-information, but not the glossary 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 all glossaries
curl -X GET 'https://api.deepl.com/v2/glossaries' \
--header 'Authorization: DeepL-Auth-Key [yourAuthKey]'
Example response
{
  "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
    }
  ]
}

​
Retrieve glossary details

Retrieve meta information for a single glossary, omitting the glossary 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: retrieve glossary details
curl -X GET 'https://api.deepl.com/v2/glossaries/{glossary_id}' \
--header 'Authorization: DeepL-Auth-Key [yourAuthKey]'
Example response
{
  "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
}

​
Retrieve glossary entries

List the entries of a single glossary in the format specified by the Accept header.

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 entries
curl -X GET 'https://api.deepl.com/v2/glossaries/{glossary_id}/entries' \
--header 'Authorization: DeepL-Auth-Key [yourAuthKey]' \
--header 'Accept: text/tab-separated-values'
Example response
Hello!	Guten Tag!

​
Delete a glossary

Deletes the specified glossary.

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/v2/glossaries/{glossary_id}' \
--header 'Authorization: DeepL-Auth-Key [yourAuthKey]'

​
Listing language pairs

The /glossary-language-pairs endpoint lists all the language pairs - the source and target languages - that glossaries support. Since glossaries now work for all languages DeepL supports, this list will be quite long. We recommend that you instead use the /languages endpoint.

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 language pairs
curl -X GET 'https://api.deepl.com/v2/glossary-language-pairs' \
--header 'Authorization: DeepL-Auth-Key [yourAuthKey]'
Example response (partial—one language pair)
{
  "supported_languages": [
    {
      "source_lang": "de",
      "target_lang": "en"
    },
    {
      "source_lang": "en",
      "target_lang": "de"
    }
  ]
}

​
Editing a v2 glossary

v2 glossaries are immutable: once created, the glossary entries for a given glossary ID cannot be modified.

As a workaround for effectively editable glossaries, we suggest to identify glossaries by name instead of ID in your application and then use the following procedure for modifications: