> ## 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.

# Migrating from v2/languages

> How to migrate from the v2/languages endpoint to the v3/languages endpoints.

This page covers the differences between the `/v2/languages` endpoint and the v3 endpoints, and how to update your integration.

<Warning>
  Only `GET` requests are supported on the v3 endpoints. Unlike `/v2/languages`, POST is not supported.
</Warning>

## What changed

### Single endpoint for source and target

v2 uses a single endpoint with a `type` query parameter to distinguish source from target:

```
GET /v2/languages?type=source
GET /v2/languages?type=target
```

v3 uses a single endpoint that returns all languages for a resource, with each language indicating whether it is
usable as a source, a target, or both:

```
GET /v3/languages?resource=translate_text
```

### New resource identifiers

v2 languages are implicitly tied to text and document translation. v3 introduces an explicit `resource` parameter that applies across all DeepL API resources:

| **v2**                                              | **v3 `resource` value** |
| --------------------------------------------------- | ----------------------- |
| *(implicit, text/document translation only)*        | `translate_text`        |
| *(implicit, text/document translation only)*        | `translate_document`    |
| *(separate `/v2/glossary-language-pairs` endpoint)* | `glossary`              |
| *(not supported)*                                   | `voice`                 |
| *(not supported)*                                   | `write`                 |

The v3 endpoints replace both `/v2/languages` and `/v2/glossary-language-pairs`.

### Features instead of `supports_formality`

v2 target languages include a boolean `supports_formality` field. v3 replaces this with a `features` object that covers additional capabilities per resource:

| **v2 field**                 | **v3 equivalent**                                             |
| ---------------------------- | ------------------------------------------------------------- |
| `"supports_formality": true` | `"formality"` key present in the language's `features` object |

For example, querying languages for text translation:

```sh theme={null}
curl -X GET 'https://api.deepl.com/v3/languages?resource=translate_text' \
--header 'Authorization: DeepL-Auth-Key [yourAuthKey]'
```

```json Example response (truncated) theme={null}
[
  {
    "lang": "de",
    "name": "German",
    "usable_as_source": true,
    "usable_as_target": true,
    "status": "stable",
    "features": {
      "formality": {"status": "stable"},
      "tag_handling": {"status": "stable"},
      "glossary": {"status": "stable"}
    }
  },
  {
    "lang": "en-US",
    "name": "English (American)",
    "usable_as_source": false,
    "usable_as_target": true,
    "status": "stable",
    "features": {
      "tag_handling": {"status": "stable"},
      "glossary": {"status": "stable"}
    }
  }
]
```

The response indicates German supports `formality` (key present in `features`), but English (American) does not (key absent).

See the [overview](/api-reference/languages/retrieve-supported-languages-by-resource) for the full list of features per resource.

### Response field names

| **v2 field**         | **v3 field**                           |
| -------------------- | -------------------------------------- |
| `language`           | `lang`                                 |
| `name`               | `name` *(unchanged)*                   |
| `supports_formality` | `"formality"` key in `features` object |
| *(not present)*      | `status`                               |

### Language code casing

v2 returned language codes in non-standard casing (e.g. `EN-US`, `ZH-HANT`). v3 returns codes compliant with BCP 47: lowercase base language (`en`, `de`), uppercase region subtag (`en-US`, `pt-BR`), and title-case script subtag (`zh-Hant`).

DeepL accepts language codes case-insensitively as input across all endpoints. However, if your integration stores or compares codes returned by `/v2/languages`, update those comparisons to be case-insensitive or to expect the new casing.

## Migrating glossary language pair queries

If you currently use `/v2/glossary-language-pairs` to discover which language pairs are supported for glossaries, use one of the following:

* `GET /v3/languages?resource=glossary` to check which languages support glossary management (i.e. creating a glossary for that language). Filter by `usable_as_source` and `usable_as_target` as needed. Any combination of a valid source and target language is a supported glossary language pair.
* `GET /v3/languages?resource=translate_text` to check which languages support using a glossary during text translation. Languages with a `"glossary"` key in their `features` object support the `glossary_id` parameter on the translate endpoint.
* Similarly, use `resource=translate_document` to check glossary support for document translation.