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