v2 vs v3 endpoints

Overview

With the v2 endpoints, you can create, delete, and retrieve information on monolingual glossaries - glossaries that map one language to another.

The v3 endpoints include all the functionality of v2 endpoints, plus:

• v3 lets you edit glossaries

• v3 lets you work with multilingual glossaries - a collection of mappings for a set of language pairs.

Thus, we recommend you use v3. v2 is kept for backward compatibility. If you already use v2 endpoints, moving to v3 will give you additional functionality, but there is no need to migrate your glossaries. You can simply start using v3 endpoints with any glossary.

We strongly discourage using both v2 and v3 endpoints in your code. If you use v3 endpoints to edit a glossary, v2 endpoints may return unexpected results for that glossary, and v2 endpoints will no longer be able to delete it.

Glossaries from either endpoint can be used in all translation endpoints - which includes both /translate and /document .

Going forward, we will continue to add features and functionality to v3.

Differences between v2 and v3

v2 lets you work with monolingual glossaries - glossaries that contain a list of mappings from source phrases in one language to target phrases in another. For example, a short glossary containing translations from English to German could look like this:

{
  "glossary_id": "def3a26b-3e84-45b3-84ae-0c0aaf3525f7",
  "name": "My Glossary",
  "source_lang": "en",
  "target_lang": "de",
  "entries": {
    "Hello": "Hallo"
  },
  "creation_time": "2025-08-03T14:16:18.329Z"
}
​

v3 works with multlingual glossaries - a collection of dictionaries each of which contain mappings from source phrases in one language to target phrases in another. We could use v3 to add to the glossary above a dictionary that maps phrases from German to English, like this:

{
  "glossary_id": "def3a26b-3e84-45b3-84ae-0c0aaf3525f7",
  "name": "My Glossary",
  "dictionaries": [
    {
      "source_lang": "en",
      "target_lang": "de",
      "entries": {
        "Hello": "Hallo"
      }
    },
    {
      "source_lang": "de",
      "target_lang": "en",
      "entries": {
        "Hallo": "Hello"
      }
    }
  ],
  "creation_time": "2025-08-03T14:16:18.329Z"
}

Can I keep using v2?

We strongly recommend switching to the latest version of the API, in order to benefit from the latest features, and as we might as some point deprecate or even remove the v2 glossary API. However, an immediate switch is not possible in all use cases, so this section outlines the implications of continuing to use the v2 glossary endpoints.

• Once a glossary has been edited via the v3 glossary API, it can no longer be correctly queried through the v2 glossary API (e.g. via the "get entries" call). To avoid data loss, we disable deletion (for this glossary) through the v2 glossary API in this case, and require users to use the v3 glossary deletion endpoint.

• We strongly discourage some users starting to use the v3 glossary endpoints, while having others still using v2 glossary endpoints. This is due to glossaries created via the v3 API still being queriable via the v2 API, which might cause confusion, as they cannot be displayed correctly.

Client libraries

For each of our client libraries, we provide a guide that explains how you can migrate to v3.