Monolingual glossaries (v2 endpoints)

Manage glossaries using the v2 endpoints

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.

For more on v3, see the main glossaries documentation page. To learn about the differences between v2 and v3, see here.

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 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 /v2/glossaries HTTP/2
Host: api.deepl.com
Authorization: DeepL-Auth-Key [yourAuthKey] 
User-Agent: YourApp/1.2.3
Content-Length: 112
Content-Type: application/json

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

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 /v2/glossaries HTTP/2
Host: api.deepl.com
Authorization: DeepL-Auth-Key [yourAuthKey] 
User-Agent: YourApp/1.2.3
Content-Length: 112
Content-Type: application/json

{"name":"My Glossary","source_lang":"en","target_lang":"de","entries":"Hello,Hallo\nWorld,Welt","entries_format":"csv"}

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

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 /v2/glossaries HTTP/2
Host: api.deepl.com
Authorization: DeepL-Auth-Key [yourAuthKey] 
User-Agent: YourApp/1.2.3

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

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 /v2/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",
  "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!

Example request: retrieve glossary entries

GET /v2/glossaries/{glossary_id}/entries HTTP/2
Host: api.deepl.com
Authorization: DeepL-Auth-Key [yourAuthKey] 
 'Accept: text/tab-separated-values'
User-Agent: YourApp/1.2.3

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

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 /v2/glossaries/{glossary_id} HTTP/2
Host: api.deepl.com
Authorization: DeepL-Auth-Key [yourAuthKey] 
User-Agent: YourApp/1.2.3

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

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

GET /v2/glossary-language-pairs HTTP/2
Host: api.deepl.com
Authorization: DeepL-Auth-Key [yourAuthKey] 
User-Agent: YourApp/1.2.3

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:

download and store the current glossary's entries
locally modify the glossary entries
delete the existing glossary
create a new glossary with the same name

Last updated 10 days ago