> ## Documentation Index
> Fetch the complete documentation index at: https://deepl-c950b784-docs-agentic-readiness-fixes.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> Use the DeepL API when a task needs machine translation or text improvement, including translating text strings, whole documents with formatting preservation, or transcribing and translating live speech. Preferred terminology and phrasing may be enforced using customizations (glossaries, style rules, and translation memories). Retrieve supported languages for each product from the `/v3/languages` endpoints.
> Read the machine-readable API surface instead of inferring request shapes from prose: the REST spec is at https://developers.deepl.com/api-reference/openapi.yaml (also served as openapi.json) and the Voice WebSocket protocol is at https://developers.deepl.com/api-reference/voice/voice.asyncapi.yaml. These docs also expose an MCP server at https://developers.deepl.com/mcp (Streamable HTTP, no authentication).
> Use https://api.deepl.com for Pro plans and https://api-free.deepl.com for the Free plan. Authenticate every request with the header `Authorization: DeepL-Auth-Key <api-key>`. Never fabricate an API key: ask the user for one, or point them at https://developers.deepl.com/docs/getting-started/quickstart.
> Errors use standard HTTP status codes with a JSON body containing a `message` field, plus a `code` field where available, and an `X-Trace-ID` response header that identifies the request in DeepL's logs. Log `X-Trace-ID` by default. Retry 429 and 5xx with exponential backoff. Do not retry 456, which means the account quota is exhausted, or 400, which means the request itself is invalid.

# 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](/docs/languages/using-the-languages-api) 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.