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"
}'
{
"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
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 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"}
{
"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)"
{
"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.
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)"
{
"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]'
{
"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
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
}
]
}
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]'
{
"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
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
}
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
{
"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'
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 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
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
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
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: