docs(v3-languages): promote to GA, deprecate v2/languages and v2/glossary-language-pairs

Daniel Jones · claude · Daniel Jones · commit cdbe25dab699 · 2026-05-15T07:39:03.000+02:00
- Remove BETA tags and notices from all v3/languages docs
- Rename retrieve-products.mdx to retrieve-resources.mdx
- Restructure Languages nav: v3 pages promoted to primary, v2 moved to DEPRECATED subgroup
- Add deprecated: true to GET /v2/languages and GET /v2/glossary-language-pairs in OpenAPI spec
- Add deprecation Warning to v2/languages overview and auto-generated reference page
- Add deprecation note to v2 glossaries overview for /v2/glossary-language-pairs
- Add May 5 release notes entry covering all GA changes and deprecations
- Remove v3/languages from "In active development" list

Co-Authored-By: Claude Sonnet 4.6 &lt;noreply@anthropic.com&gt;
diff --git a/api-reference/glossaries.mdx b/api-reference/glossaries.mdx
@@ -9,6 +9,8 @@ description: "Manage glossaries using the v2 endpoints"
 This page documents `v2` glossary endpoints, legacy endpoints that let you create and manage glossaries for a single language pair.
 
 [See here](/api-reference/multilingual-glossaries) for information on current `v3` endpoints. Using `v3` allows you to create, manage, and edit glossaries with entries in multiple language pairs, while still supporting monolingual functionality. [See here](/api-reference/glossaries/v2-vs-v3-endpoints) for an overview of the difference.
+
+The `/v2/glossary-language-pairs` endpoint is also deprecated. Use [`GET /v3/languages?resource=glossary`](/api-reference/languages/retrieve-supported-languages-by-resource) instead.
 </Info>
 
 This page describes how to use the `v2` endpoints to work with _monolingual_ glossaries - glossaries that map phrases in one language to phrases in another language. If you're new to glossaries, we suggest you use `v3` instead.
diff --git a/api-reference/languages.mdx b/api-reference/languages.mdx
@@ -1,20 +1,16 @@
 ---
-title: "Retrieve languages"
+title: "Retrieve languages (v2)"
 sidebarTitle: "Overview"
-description: "API reference for retrieving supported languages with the DeepL API."
+description: "Reference for the deprecated v2/languages endpoint. Migrate to v3/languages for new integrations."
 ---
 
-Get all currently supported source and target languages that can be used for text and document translation.
+<Warning>
+  **`/v2/languages` is deprecated.** Use [`GET /v3/languages`](/api-reference/languages/retrieve-supported-languages-by-resource) instead, which covers all DeepL API resources and provides richer feature information. See the [migration guide](/api-reference/languages/migrate-from-v2-languages) for details.
+</Warning>
 
-<Info>
-  As of April 2025, supported languages for [text improvement](/api-reference/improve-text) (DeepL API for Write) have not yet been added to the `/languages` endpoint; we'll be extending the `/languages` endpoint in the near future to include this information.
-</Info>
-<Info>
-  To get languages available for glossaries, please see [here](/api-reference/multilingual-glossaries).
-</Info>
-We also provide a spec that is auto-generated from DeepL's OpenAPI file. [You can find it here](/api-reference/languages/retrieve-supported-languages).
+`GET /v2/languages` returns the source and target languages supported for text and document translation. New integrations should use `/v3/languages`, which exposes the same translation languages along with feature support for glossaries, voice, write, and other resources.
 
-To understand how we'll update the `/languages` endpoint when we add translation support for a new language or language variant, please see [this article](/docs/resources/language-release-process).
+For background on how DeepL adds new translation languages and language variants, see [the language release process](/docs/resources/language-release-process). For the auto-generated reference spec for this endpoint, see [Retrieve supported languages](/api-reference/languages/retrieve-supported-languages).
 
 <Tabs>
 <Tab title="cURL">
diff --git a/api-reference/languages/language-feature-use-cases.mdx b/api-reference/languages/language-feature-use-cases.mdx
@@ -1,6 +1,5 @@
 ---
 title: 'Common use cases'
-tag: "BETA"
 description: "Pseudocode examples for common language and feature lookup patterns using the v3/languages endpoints."
 ---
 
diff --git a/api-reference/languages/retrieve-languages-by-resource.mdx b/api-reference/languages/retrieve-languages-by-resource.mdx
@@ -1,9 +1,5 @@
 ---
 openapi: get /v3/languages
 title: "Retrieve languages"
-tag: "BETA"
 ---
 
-<Info>
-This endpoint is available for testing in BETA. Breaking changes may be pushed with little or no advance notice, and we provide no guarantees of stability.
-</Info>
diff --git a/api-reference/languages/retrieve-resources.mdx b/api-reference/languages/retrieve-resources.mdx
@@ -1,11 +1,6 @@
 ---
 openapi: get /v3/languages/resources
 title: "Retrieve language resources"
-tag: "BETA"
 description: "Learn how to retrieve the list of DeepL API resources and their supported language features."
 ---
 
-<Info>
-This endpoint is available for testing in BETA. Breaking changes may be pushed with little or no advance notice, and we provide no guarantees of stability.
-</Info>
-
diff --git a/api-reference/languages/retrieve-supported-languages-by-resource.mdx b/api-reference/languages/retrieve-supported-languages-by-resource.mdx
@@ -1,14 +1,13 @@
 ---
 title: 'Retrieve supported languages by resource'
-tag: "BETA"
 sidebarTitle: 'Overview'
 description: "Learn how to retrieve supported language and feature data across all DeepL API resources using the v3/languages endpoints."
 ---
 
 Get information about all currently supported languages across all DeepL API resources.
 
 <Info>
-    These **BETA** endpoints replace `/v2/languages` and `/v2/glossary-language-pairs` (see the [migration guide](/api-reference/languages/migrate-from-v2-languages)). Do not use them in production; breaking changes may be pushed without advance notice (see the [changelog](/api-reference/languages/v3-languages-changelog)).
+    The `/v3/languages` endpoints replace the deprecated `/v2/languages` and `/v2/glossary-language-pairs` endpoints. If you're currently using either, see the [migration guide](/api-reference/languages/migrate-from-v2-languages) for differences and code examples.
 </Info>
 
 We also provide auto-generated API specs from DeepL's OpenAPI file, for use with API clients and code generation tools:
diff --git a/api-reference/languages/retrieve-supported-languages.mdx b/api-reference/languages/retrieve-supported-languages.mdx
@@ -1,4 +1,10 @@
 ---
 openapi: get /v2/languages
-title: "Retrieve supported languages"
+title: "Retrieve supported languages (v2)"
+tag: "DEPRECATED"
 ---
+
+<Warning>
+  **`/v2/languages` is deprecated.** Use [`GET /v3/languages`](/api-reference/languages/retrieve-supported-languages-by-resource) instead. See the [migration guide](/api-reference/languages/migrate-from-v2-languages) for details.
+</Warning>
+
diff --git a/api-reference/languages/v3-languages-changelog.mdx b/api-reference/languages/v3-languages-changelog.mdx
@@ -1,18 +1,18 @@
 ---
 title: 'v3/languages changelog'
-tag: "BETA"
 sidebarTitle: 'Changelog'
-description: 'Changes and planned updates to the v3/languages endpoints during the beta period.'
+description: 'Changes to the v3/languages endpoints, including the GA release and prior breaking changes.'
 ---
 
-<Info>
-  These endpoints are in **BETA**. We will try to announce breaking changes here before they land, but cannot guarantee
-    advance notice. Do not use these endpoints in production.
-</Info>
-
 ## Changes since the initial beta release
 
-This section lists dated changes to the API since the initial beta release.
+This section lists dated changes to the API.
+
+### 5 May 2026 — General Availability
+
+`/v3/languages` is now generally available. The endpoint replaces the deprecated `/v2/languages` and `/v2/glossary-language-pairs`. See the [migration guide](/api-reference/languages/migrate-from-v2-languages) for differences and code examples.
+
+The breaking changes listed below were applied alongside the GA release.
 
 ### 5 May 2026
 
@@ -111,17 +111,3 @@ from `GET /v3/languages` are sufficient to determine feature support for all pai
 ### 19 March 2026
 
 Initial beta release.
-
----
-
-## Possible additions
-
-These are under consideration and may or may not land before GA.
-
-- **`native_name` field** on language objects — the language's name in that language (e.g. `"Deutsch"` for German).
-
----
-
-## Current beta state
-
-For the current API contract, see the [overview](/api-reference/languages/retrieve-supported-languages-by-resource) and the auto-generated reference pages linked there.
diff --git a/api-reference/multilingual-glossaries/list-language-pairs-supported-by-glossaries.mdx b/api-reference/multilingual-glossaries/list-language-pairs-supported-by-glossaries.mdx
@@ -1,8 +1,13 @@
 ---
 openapi: "get /v2/glossary-language-pairs"
 title: "List language pairs supported for glossaries"
+tag: "DEPRECATED"
 playground: none
 ---
 
+<Warning>
+  **`/v2/glossary-language-pairs` is deprecated.** Use [`GET /v3/languages?resource=glossary`](/api-reference/languages/retrieve-supported-languages-by-resource) instead. See the [migration guide](/api-reference/languages/migrate-from-v2-languages) for details.
+</Warning>
+
 <Info>This endpoint returns all possible language pairs for glossaries.
 [This list of supported languages](/docs/getting-started/supported-languages) may also be useful.</Info>
diff --git a/api-reference/openapi.yaml b/api-reference/openapi.yaml
@@ -438,10 +438,10 @@ paths:
                   example: def3a26b-3e84-45b3-84ae-0c0aaf3525f7
                 style_id:
                   description: |-
-                    Specify the [style rule list](/api-reference/style-rules) to use for the translation. 
+                    Specify the [style rule list](/api-reference/style-rules) to use for the translation.
+
+                    **Important:**  The target language has to match the language of the style rule list.
 
-                    **Important:**  The target language has to match the language of the style rule list. 
-                    
                     **Note:** Any request with the `style_id` parameter enabled will use `quality_optimized` models. Requests combining `style_id` and `model_type: latency_optimized` will be rejected.
                   type: string
                   example: 7ff9bfd6-cd85-4190-8503-d6215a321519
@@ -928,10 +928,15 @@ paths:
         - auth_header: [ ]
   /v2/glossary-language-pairs:
     get:
+      deprecated: true
       tags:
         - ManageGlossaries
       summary: List Language Pairs Supported by Glossaries
-      description: Retrieve the list of language pairs supported by the glossary feature.
+      description: |-
+        **Deprecated.** Use `GET /v3/languages?resource=glossary` instead, which returns per-language
+        availability including source and target roles.
+
+        Retrieve the list of language pairs supported by the glossary feature.
       operationId: listGlossaryLanguages
       responses:
         200:
@@ -1830,10 +1835,15 @@ paths:
         - auth_header: [ ]
   /v2/languages:
     get:
+      deprecated: true
       tags:
         - MetaInformation
       summary: Retrieve Supported Languages
-      operationId: getLanguages
+      description: |-
+        **Deprecated.** Use `GET /v3/languages?resource=translate_text` (or the appropriate resource)
+        instead. See the [migration guide](https://developers.deepl.com/api-reference/languages/migrate-from-v2-languages)
+        for details.
+      operationId: getLanguagesV2
       parameters:
         - name: type
           in: query
@@ -1970,8 +1980,6 @@ paths:
     get:
       tags:
         - MetaInformation
-        - beta
-      x-beta: true
       summary: Retrieve Language Resources
       operationId: getLanguageResources
       description: |-
@@ -2075,8 +2083,6 @@ paths:
     get:
       tags:
         - MetaInformation
-        - beta
-      x-beta: true
       summary: Retrieve Languages
       operationId: getLanguages
       description: |-
@@ -3247,8 +3253,8 @@ components:
     auth_header:
       type: apiKey
       description: >
-        Authentication with `Authorization` header and 
-        `DeepL-Auth-Key` authentication scheme. Example: 
+        Authentication with `Authorization` header and
+        `DeepL-Auth-Key` authentication scheme. Example:
         `DeepL-Auth-Key <api-key>`
       name: Authorization
       in: header
@@ -4662,8 +4668,8 @@ components:
     Formality:
       description: |-
         Sets whether the translated text should lean towards formal or informal language.
-        This feature is only available for certain target languages. Setting this parameter 
-        with a target language that does not support formality will fail, unless one of the 
+        This feature is only available for certain target languages. Setting this parameter
+        with a target language that does not support formality will fail, unless one of the
         `prefer_...` options are used.
         Possible options are:
           * `default` (default)
@@ -4893,15 +4899,15 @@ components:
           $ref: '#/components/schemas/GlossaryEntryCount'
     OutlineDetectionOption:
       description: |-
-        Disable the automatic detection of XML structure by setting the `outline_detection` parameter 
-        to `false` and selecting the tags that should be considered structure tags. This will split sentences 
+        Disable the automatic detection of XML structure by setting the `outline_detection` parameter
+        to `false` and selecting the tags that should be considered structure tags. This will split sentences
         using the `splitting_tags` parameter.
       type: boolean
       default: true
     OutlineDetectionOptionStr:
       description: |-
-        Disable the automatic detection of XML structure by setting the `outline_detection` parameter 
-        to `false` and selecting the tags that should be considered structure tags. This will split sentences 
+        Disable the automatic detection of XML structure by setting the `outline_detection` parameter
+        to `false` and selecting the tags that should be considered structure tags. This will split sentences
         using the `splitting_tags` parameter.
       type: string
       default: '1'
@@ -4919,13 +4925,13 @@ components:
             $ref: '#/components/schemas/GlossaryDictionary'
     PreserveFormattingOption:
       description: |-
-        Sets whether the translation engine should respect the original formatting, even if it would usually 
+        Sets whether the translation engine should respect the original formatting, even if it would usually
         correct some aspects.
       type: boolean
       default: false
     PreserveFormattingOptionStr:
       description: |-
-        Sets whether the translation engine should respect the original formatting, even if it would usually 
+        Sets whether the translation engine should respect the original formatting, even if it would usually
         correct some aspects.
       type: string
       enum:
@@ -4934,12 +4940,12 @@ components:
       default: '0'
     ShowBilledCharacters:
       description: |-
-        When true, the response will include the billed_characters parameter, giving the 
+        When true, the response will include the billed_characters parameter, giving the
         number of characters from the request that will be counted by DeepL for billing purposes.
       type: boolean
     SplitSentencesOption:
       description: |-
-        Sets whether the translation engine should first split the input into sentences. 
+        Sets whether the translation engine should first split the input into sentences.
 
         Possible values are:
           * 0 - no splitting at all, whole input is treated as one sentence
@@ -4958,7 +4964,7 @@ components:
         Language of the text to be translated. If this parameter is omitted, the API will attempt to
         detect the language of the text and translate it.
 
-        For the full list of supported source languages, see [supported languages](https://developers.deepl.com/docs/getting-started/supported-languages) or query the [`GET /v3/languages` endpoint](https://developers.deepl.com/api-reference/languages/retrieve-supported-languages-by-resource) (beta).
+        For the full list of supported source languages, see [supported languages](https://developers.deepl.com/docs/getting-started/supported-languages) or query the [`GET /v3/languages` endpoint](https://developers.deepl.com/api-reference/languages/retrieve-supported-languages-by-resource).
       example: EN
     TranslationMemory:
       type: object
@@ -5130,7 +5136,7 @@ components:
       description: |-
         The language into which the text should be translated.
 
-        For the full list of supported target languages, see [supported languages](https://developers.deepl.com/docs/getting-started/supported-languages) or query the [`GET /v3/languages` endpoint](https://developers.deepl.com/api-reference/languages/retrieve-supported-languages-by-resource) (beta).
+        For the full list of supported target languages, see [supported languages](https://developers.deepl.com/docs/getting-started/supported-languages) or query the [`GET /v3/languages` endpoint](https://developers.deepl.com/api-reference/languages/retrieve-supported-languages-by-resource).
       example: DE
     TargetLanguageWrite:
       type: string
diff --git a/docs.json b/docs.json
@@ -257,18 +257,18 @@
           {
             "group": "Languages",
             "pages": [
-              "api-reference/languages",
-              "api-reference/languages/retrieve-supported-languages",
+              "api-reference/languages/retrieve-supported-languages-by-resource",
+              "api-reference/languages/language-feature-use-cases",
+              "api-reference/languages/retrieve-languages-by-resource",
+              "api-reference/languages/retrieve-resources",
+              "api-reference/languages/migrate-from-v2-languages",
+              "api-reference/languages/v3-languages-changelog",
               {
-                "group": "Languages By Resource",
-                "tag": "BETA",
+                "group": "v2 Languages",
+                "tag": "DEPRECATED",
                 "pages": [
-                  "api-reference/languages/retrieve-supported-languages-by-resource",
-                  "api-reference/languages/language-feature-use-cases",
-                  "api-reference/languages/retrieve-languages-by-resource",
-                  "api-reference/languages/retrieve-resources",
-                  "api-reference/languages/migrate-from-v2-languages",
-                  "api-reference/languages/v3-languages-changelog"
+                  "api-reference/languages",
+                  "api-reference/languages/retrieve-supported-languages"
                 ],
                 "drilldown": false
               }
diff --git a/docs/getting-started/supported-languages.mdx b/docs/getting-started/supported-languages.mdx
@@ -19,9 +19,5 @@ import { LanguageTable } from "/snippets/language-table.jsx"
 </Info>
 
 <Info>
-  Text improvement languages have not yet been added to the [`/languages` endpoint](/api-reference/languages/retrieve-supported-languages). For `/write/rephrase`, `writing_style` and `tone` currently work in `DE`, `EN-GB`, and `EN-US`.
-</Info>
-
-<Info>
-  Style rules are supported for the following target languages: `de`, `en`, `es`, `fr`, `it`, `ja`, `ko`, and `zh`. For more details, see the [Style Rules API documentation](/api-reference/style-rules).
+  Style rules are supported for the following target languages: `de`, `en`, `es`, `fr`, `it`, `ja`, `ko`, and `zh`. For more details, see the [Style Rules API documentation](/api-reference/style-rules). Writing style and tone availability for `/write/rephrase` can also be retrieved via [`GET /v3/languages?resource=write`](/api-reference/languages/retrieve-supported-languages-by-resource).
 </Info>
diff --git a/docs/resources/roadmap-and-release-notes.mdx b/docs/resources/roadmap-and-release-notes.mdx
@@ -4,9 +4,20 @@ description: "The latest features and improvements in the DeepL API, plus what's
 rss: true
 ---
 
+<Update label="May 2026">
+## May 5 - v3/languages General Availability
+
+- [`GET /v3/languages`](/api-reference/languages/retrieve-supported-languages-by-resource) and [`GET /v3/languages/resources`](/api-reference/languages/retrieve-resources) are now generally available.
+- The `resource` query parameter replaces `product`. The `/v3/languages/products` endpoint has been renamed to `/v3/languages/resources`.
+- The `features` field on language objects is now an object keyed by feature name (e.g. `{"formality": {"status": "stable"}}`), replacing the previous array of strings.
+- Language objects now include a `status` field (`stable`, `beta`, `early_access`).
+- A new `include` query parameter controls whether beta (`?include=beta`) or external-provider (`?include=external`) languages and features are returned.
+- The `custom_instructions` feature key has been renamed to `style_rules`. The `custom_instructions` parameter on the translate endpoint is unaffected.
+- **`/v2/languages` and `/v2/glossary-language-pairs` are now deprecated.** Migrate to `/v3/languages`. See the [migration guide](/api-reference/languages/migrate-from-v2-languages) for details.
+</Update>
+
 <Update label="In active development">
 - Support for uploading, modifying, and deleting [translation memories](/docs/learning-how-tos/examples-and-guides/how-to-use-translation-memories) via API
-- `v3/languages` endpoint with improved language code handling and additional functionality
 - API key-level endpoint restrictions
 - Usage reporting by custom tag and language pair
 </Update>
