> ## Documentation Index
> Fetch the complete documentation index at: https://developers.deepl.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Glossaries
> Manage and use DeepL glossaries
This page documents `v3` glossary endpoints, which let you **edit** glossaries and allow for **multilingual** functionality.
The current`v3` endpoints are used for working with **both multilingual and monolingual** glossaries. Thus, we recommend you start using the `v3` endpoints described below for all glossary needs.
The previously used [v2 glossary endpoints](/api-reference/glossaries) can only be used with **monolingual** glossaries. [See here](/api-reference/glossaries/v2-vs-v3-endpoints) for more on the difference between `v2` and `v3` glossary endpoints.
## Overview
The `glossaries` endpoints let you work with [DeepL glossaries](https://support.deepl.com/hc/en-us/articles/360021634540-About-the-glossary), 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). You can create glossaries with [any of the languages listed here](/docs/getting-started/supported-languages).
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 |
Both glossaries and style rules are unique to each of DeepL's global data centers and are not shared between them. Clients using the `api-us.deepl.com` endpoint will not be able to access glossaries or style rules created in the UI at this time.
## 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:
```
"hermosa","belle"
"exquisito","delicieux"
"mouse","mouse"
```
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.
```sh Example request: create a glossary theme={null}
curl -X POST 'https://api.deepl.com/v3/glossaries' \
--header 'Authorization: DeepL-Auth-Key [yourAuthKey]' \
--header 'Content-Type: application/json' \
--data '{
"name": "My Glossary",
"dictionaries": [
{
"source_lang": "en",
"target_lang": "de",
"entries": "Hello\tGuten Tag",
"entries_format": "tsv"
},
{
"source_lang": "de",
"target_lang": "en",
"entries": "Guten Tag\tHello",
"entries_format": "tsv"
}
]
}'
```
```json Example response theme={null}
{
"glossary_id": "def3a26b-3e84-45b3-84ae-0c0aaf3525f7",
"ready": true,
"name": "My Glossary",
"dictionaries": [
{
"source_lang": "en",
"target_lang": "de",
"entry_count": 1
},
{
"source_lang": "de",
"target_lang": "en",
"entry_count": 1
}
],
"creation_time": "2025-08-03T14:16:18.329Z"
}
```
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.
```http Example request: create a glossary theme={null}
POST /v3/glossaries HTTP/2
Host: api.deepl.com
Authorization: DeepL-Auth-Key [yourAuthKey]
User-Agent: YourApp/1.2.3
Content-Length: 1234
Content-Type: application/json
{
"name": "My Glossary",
"dictionaries": [
{
"source_lang": "en",
"target_lang": "de",
"entries": "Hello\tGuten Tag",
"entries_format": "tsv"
},
{
"source_lang": "de",
"target_lang": "en",
"entries": "Guten Tag\tHello",
"entries_format": "tsv"
}
]
}
```
## Using a glossary
`POST /v2/translate`
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.
```sh Example request: translate including glossary theme={null}
curl -X POST 'https://api.deepl.com/v2/translate' \
--header 'Authorization: DeepL-Auth-Key [yourAuthKey] \
--header 'Content-Type: application/json' \
--data '{
"text": [
"Hello"
],
"source_lang": "EN",
"target_lang": "DE",
"glossary_id": [yourGlossaryID]
}'
```
```json Example response theme={null}
{
"translations": [
{
"detected_source_language": "EN",
"text": "Guten Tag"
}
]
}
```
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.
```http Example request: translate including glossary theme={null}
POST /v2/translate HTTP/2
Host: api.deepl.com
Authorization: DeepL-Auth-Key [yourAuthKey]
User-Agent: YourApp/1.2.3
Content-Length: 111
Content-Type: application/json
{
"text": [
"Hello there"
],
"source_lang": "EN",
"target_lang": "DE",
"glossary_id": [yourGlossaryID]
}
```
```json Example response theme={null}
{
"translations": [
{
"detected_source_language": "EN",
"text": "Guten Tag"
}
]
}
```
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.
```sh Example request: list glossaries theme={null}
curl -X GET 'https://api.deepl.com/v3/glossaries' \
--header 'Authorization: DeepL-Auth-Key [yourAuthKey]'
```
```json Example response theme={null}
{
"glossaries": [
{
"glossary_id": "def3a26b-3e84-45b3-84ae-0c0aaf3525f7",
"name": "My Glossary",
"dictionaries": [{
"source_lang": "en",
"target_lang": "de",
"entry_count": 1,
},
{
"source_lang": "de",
"target_lang": "en",
"entry_count": 3,
}],
"creation_time": "2021-08-03T14:16:18.329Z"
}
]
}
```
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.
```http Example request: list all glossaries theme={null}
GET /v3/glossaries HTTP/2
Host: api.deepl.com
Authorization: DeepL-Auth-Key [yourAuthKey]
User-Agent: YourApp/1.2.3
```
```json Example response theme={null}
{
"glossaries": [
{
"glossary_id": "def3a26b-3e84-45b3-84ae-0c0aaf3525f7",
"name": "My Glossary",
"dictionaries": [{
"source_lang": "en",
"target_lang": "de",
"entry_count": 1,
},
{
"source_lang": "de",
"target_lang": "en",
"entry_count": 3,
}],
"creation_time": "2025-08-03T14:16:18.329Z"
}
]
}
```
### Get glossary metadata
`GET /v3/glossaries/{glossary_id}`
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.
```sh Example request: retrieve glossary details theme={null}
curl -X GET 'https://api.deepl.com/v3/glossaries/{glossaryId}' \
--header 'Authorization: DeepL-Auth-Key [yourAuthKey]'
```
```json Example response theme={null}
{
"glossary_id": "def3a26b-3e84-45b3-84ae-0c0aaf3525f7",
"name": "My Glossary",
"dictionaries": [
{
"source_lang": "en",
"target_lang": "de",
"entry_count": 1
},
{
"source_lang": "de",
"target_lang": "en",
"entry_count": 1
}
],
"creation_time": "2025-08-03T14:16:18.329Z"
}
```
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.
```http Example request: retrieve glossary details theme={null}
GET /v3/glossaries/{glossary_id} HTTP/2
Host: api.deepl.com
Authorization: DeepL-Auth-Key [yourAuthKey]
User-Agent: YourApp/1.2.3
```
```json Example response theme={null}
{
"glossary_id": "def3a26b-3e84-45b3-84ae-0c0aaf3525f7",
"name": "My Glossary",
"dictionaries": [
{
"source_lang": "en",
"target_lang": "de",
"entry_count": 1
},
{
"source_lang": "de",
"target_lang": "en",
"entry_count": 1
}
],
"creation_time": "2025-08-03T14:16:18.329Z"
}
```
### Get glossary entries
`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.
```sh Example request: get glossary entries theme={null}
curl -X GET 'https://api.deepl.com/v3/glossaries/{glossaryId}/entries?source_lang=en&target_lang=de' \
--header 'Authorization: DeepL-Auth-Key [yourAuthKey]' \
--header 'Content-Type: application/json'
```
```json Example response theme={null}
{
"dictionaries": [{
"source_lang": "en",
"target_lang": "de",
"entries": "Hello\tGuten Tag",
"entries_format": "tsv",
}]
}
```
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.
```http Example request: get glossary entries theme={null}
GET /v3/glossaries/{glossary_id}/entries HTTP/2
Host: api.deepl.com
Authorization: DeepL-Auth-Key [yourAuthKey]
User-Agent: YourApp/1.2.3
```
```json Example response theme={null}
{
"dictionaries": [{
"source_lang": "en",
"target_lang": "de",
"entries": "Hello\tGuten Tag",
"entries_format": "tsv",
}]
}
```
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](/docs/resources/deepl-developer-community) is valuable as we strive to improve our API.
## Editing a glossary
### 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`](/api-reference/multilingual-glossaries#add-new-entries-to-a-dictionary%2C-or-replace-existing-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.
```sh Example request: replace a dictionary theme={null}
curl -X PUT 'https://api.deepl.com/v3/glossaries/{glossaryId}/dictionaries' \
--header 'Authorization: DeepL-Auth-Key [yourAuthKey]' \
--header 'Content-Type: application/json' \
--data '{
"source_lang": "en",
"target_lang": "de",
"entries": "Hello\tGuten Tag",
"entries_format": "tsv"
}'
```
```json Example response theme={null}
{
"source_lang": "en",
"target_lang": "de",
"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.
```http Example request: replace a dictionary theme={null}
PUT /v3/glossaries/{glossaryId}/dictionaries HTTP/2
Host: api.deepl.com
Authorization: DeepL-Auth-Key [yourAuthKey]
User-Agent: YourApp/1.2.3
Content-Length: 210
Content-Type: application/json
{"source_lang": "en","target_lang": "de","entries": "Hello\tGuten Tag", "entries_format": "tsv"}
```
```json Example response theme={null}
{
"source_lang": "en",
"target_lang": "de",
"entry_count": 1
}
```
### 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.
```sh Example request: update glossary entries theme={null}
curl -X PATCH 'https://api.deepl.com/v3/glossaries/{glossaryId}' \
--header 'Authorization: DeepL-Auth-Key [yourAuthKey]' \
--header 'Content-Type: application/json' \
--data '{
"name": "Gus the glossary"
}'
```
```json Example response theme={null}
{
"glossary_id": "def3a26b-3e84-45b3-84ae-0c0aaf3525f7",
"name": "Gus the glossary",
"dictionaries": [
{
"source_lang": "en",
"target_lang": "de",
"entry_count": 1
}
],
"creation_time": "2025-08-03T14:16:18.329Z"
}
```
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.
```http Example request: update glossary entries theme={null}
PATCH /v3/glossaries/{glossaryId} HTTP/2
Host: api.deepl.com
Authorization: DeepL-Auth-Key [yourAuthKey]
User-Agent: YourApp/1.2.3
Content-Length: 147
Content-Type: application/json
{"name": "My updated glossary", "dictionaries": [{"source_lang": "en","target_lang": "de","entries": "Hello\tGuten Tag", "entries_format": "tsv"}]}
```
```json Example response theme={null}
{
"glossary_id": "def3a26b-3e84-45b3-84ae-0c0aaf3525f7",
"name": "My updated glossary",
"dictionaries": [
{
"source_lang": "en",
"target_lang": "de",
"entry_count": 1
}
],
"creation_time": "2025-08-03T14:16:18.329Z"
}
```
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](./#add-a-new-dictionary-or-replace-an-existing-one).
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.
```sh Example request: update glossary entries theme={null}
curl -X PATCH 'https://api.deepl.com/v3/glossaries/{glossaryId}' \
--header 'Authorization: DeepL-Auth-Key [yourAuthKey]' \
--header 'Content-Type: application/json' \
--data '{
"name": "Gertrude the glossary",
"dictionaries": [{
"source_lang": "en",
"target_lang": "de",
"entries": "Goodbye\tTschüß",
"entries_format": "tsv"
}]
}'
```
```json Example response theme={null}
{
"glossary_id": "def3a26b-3e84-45b3-84ae-0c0aaf3525f7",
"name": "Gertrude the glossary",
"dictionaries": [
{
"source_lang": "en",
"target_lang": "de",
"entry_count": 2
}
],
"creation_time": "2025-08-03T14:16:18.329Z"
}
```
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.
```http Example request: update glossary entries theme={null}
PATCH /v3/glossaries/{glossaryId} HTTP/2
Host: api.deepl.com
Authorization: DeepL-Auth-Key [yourAuthKey]
User-Agent: YourApp/1.2.3
Content-Length: 147
Content-Type: application/json
{"name": "My updated glossary", "dictionaries": [{"source_lang": "en","target_lang": "de","entries": "Hello\tGuten Tag", "entries_format": "tsv"}]}
```
```json Example response theme={null}
{
"glossary_id": "def3a26b-3e84-45b3-84ae-0c0aaf3525f7",
"name": "My updated glossary",
"dictionaries": [
{
"source_lang": "en",
"target_lang": "de",
"entry_count": 1
}
],
"creation_time": "2025-08-03T14:16:18.329Z"
}
```
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](/docs/resources/deepl-developer-community) 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.
```sh Example request: delete a glossary theme={null}
curl -X DELETE 'https://api.deepl.com/v3/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.
```http Example request: delete a glossary theme={null}
DELETE /v3/glossaries/{glossary_id} HTTP/2
Host: api.deepl.com
Authorization: DeepL-Auth-Key [yourAuthKey]
User-Agent: YourApp/1.2.3
```
### Delete a glossary's dictionary
`DELETE /v3/glossaries/{glossary_id}/dictionaries?source_lang={source_lang}&target_lang={target_lang}`
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.
```sh Example request: delete a dictionary theme={null}
curl -X DELETE 'https://api.deepl.com/v3/glossaries/{glossary_id}/dictionaries?source_lang={source_lang}&target_lang={target_lang}' \
--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.
```http Example request: delete a dictionary theme={null}
DELETE /v3/glossaries/{glossary_id}/dictionaries?source_lang={source_lang}&target_lang={target_lang} HTTP/2
Host: api.deepl.com
Authorization: DeepL-Auth-Key [yourAuthKey]
User-Agent: YourApp/1.2.3
```
## Notes on usage
### Languages supported
The DeepL API supports [these languages for glossaries](/docs/getting-started/supported-languages).
To retrieve supported glossary languages programmatically, call [`GET /v3/languages?resource=glossary`](/api-reference/languages/retrieve-supported-languages-by-resource).
### Language variants
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 `PT` 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](/docs/resources/deepl-developer-community) 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.
The number of glossaries you can make is [limited by your plan](https://www.deepl.com/en/pro-api).
### Content
* Duplicate source entries are not allowed.
* Neither the source nor the target entry may be empty.
* The source and target entries must not contain any C0 or C1 control characters (including, e.g., `\t` or `\n`) or any Unicode newline.
* Source and target entries must not contain any leading or trailing Unicode whitespace characters.