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

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-product) 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. 

api-reference/languages.mdx

@@ -1,17 +1,15 @@
 ---
-title: "Retrieve languages"
+title: "Retrieve languages (v2)"
 sidebarTitle: "Overview"
-description: "API reference for retrieving supported languages with the DeepL API."
+description: "API reference for the deprecated v2/languages endpoint."
 ---
 
+<Warning>
+  **`/v2/languages` is deprecated.** Use [`GET /v3/languages`](/api-reference/languages/retrieve-supported-languages-by-product) 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>
+
 Get all currently supported source and target languages that can be used for text and document translation.
 
-<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).
 
 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).

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

api-reference/languages/retrieve-languages-by-product.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>

api-reference/languages/retrieve-products.mdx

@@ -1,10 +1,5 @@
 ---
 openapi: get /v3/languages/resources
 title: "Retrieve language resources"
-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>
-

api-reference/languages/retrieve-supported-languages-by-product.mdx

@@ -1,6 +1,5 @@
 ---
 title: 'Retrieve supported languages by resource'
-tag: "BETA"
 sidebarTitle: 'Overview'
 description: "API reference for retrieving supported languages with the DeepL API across all resources."
 ---
@@ -9,15 +8,11 @@ Get information about all currently supported languages across all DeepL API res
 
 <Info>
     The `/v3/languages` endpoints provide a single source of truth for language and feature support across all DeepL
-    API resources. They replace the `/v2/languages` and `/v2/glossary-language-pairs` endpoints.
+    API resources. They replace the deprecated `/v2/languages` and `/v2/glossary-language-pairs` endpoints.
 
     If you're currently using `/v2/languages` or `/v2/glossary-language-pairs`, see the
     [migration guide](/api-reference/languages/migrate-from-v2-languages)
     for a full list of differences and code examples.
-
-    **These endpoints are available for testing in BETA.** Breaking changes may be pushed with little or no advance
-    notice, and we provide no guarantees of stability. Please do not use `/v3/languages` in production. See the
-    [changelog](/api-reference/languages/v3-languages-changelog) for recent changes.
 </Info>
 
 We also provide auto-generated API specs from DeepL's OpenAPI file, for use with API clients and code generation tools:

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-product) instead. See the [migration guide](/api-reference/languages/migrate-from-v2-languages) for details.
+</Warning>
+

api-reference/languages/v3-languages-changelog.mdx

@@ -1,18 +1,12 @@
 ---
 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 since the initial beta release.'
 ---
 
-<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 will list dated changes to the API since the initial beta release.
+This section lists dated changes to the API since the initial beta release.
 
 ### 5 May 2026
 

api-reference/openapi.yaml

@@ -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: |-
@@ -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-product) (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-product).
       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-product) (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-product).
       example: DE
     TargetLanguageWrite:
       type: string

docs.json

@@ -247,18 +247,18 @@
           {
             "group": "Languages",
             "pages": [
-              "api-reference/languages",
-              "api-reference/languages/retrieve-supported-languages",
+              "api-reference/languages/retrieve-supported-languages-by-product",
+              "api-reference/languages/language-feature-use-cases",
+              "api-reference/languages/retrieve-languages-by-product",
+              "api-reference/languages/retrieve-products",
+              "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-product",
-                  "api-reference/languages/language-feature-use-cases",
-                  "api-reference/languages/retrieve-languages-by-product",
-                  "api-reference/languages/retrieve-products",
-                  "api-reference/languages/migrate-from-v2-languages",
-                  "api-reference/languages/v3-languages-changelog"
+                  "api-reference/languages",
+                  "api-reference/languages/retrieve-supported-languages"
                 ],
                 "drilldown": false
               }

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-product) and [`GET /v3/languages/resources`](/api-reference/languages/retrieve-products) 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).
+</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>