Monolingual glossaries (v2 endpoints)
Manage glossaries using the v2 endpoints
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.
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"
}'
{
"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.
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)"
{
"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.
curl -X GET 'https://api.deepl.com/v2/glossaries' \
--header 'Authorization: DeepL-Auth-Key [yourAuthKey]'
{
"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.
curl -X GET 'https://api.deepl.com/v2/glossaries/{glossary_id}' \
--header 'Authorization: DeepL-Auth-Key [yourAuthKey]'
{
"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.
curl -X GET 'https://api.deepl.com/v2/glossaries/{glossary_id}/entries' \
--header 'Authorization: DeepL-Auth-Key [yourAuthKey]' \
--header 'Accept: text/tab-separated-values'
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.
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.
curl -X GET 'https://api.deepl.com/v2/glossary-language-pairs' \
--header 'Authorization: DeepL-Auth-Key [yourAuthKey]'
{
"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