From fd2d6717df07a88503af6f7a71cfa5bf53264853 Mon Sep 17 00:00:00 2001
From: Kevin Abraham <kevin.abraham@deepl.com>
Date: Mon, 22 Jun 2026 11:13:32 -0400
Subject: [PATCH 1/3] docs: document tag_handling_version in translate response

---
 api-reference/openapi.yaml  | 10 ++++++++++
 api-reference/translate.mdx |  1 +
 2 files changed, 11 insertions(+)

diff --git a/api-reference/openapi.yaml b/api-reference/openapi.yaml
index ab81c4d..a623a2c 100644
--- a/api-reference/openapi.yaml
+++ b/api-reference/openapi.yaml
@@ -745,6 +745,16 @@ paths:
                             is included in the request.
                           type: string
                           example: quality_optimized
+                        tag_handling_version:
+                          description: The version of the tag handling algorithm used for the translation.
+                            Only present when the `tag_handling` parameter (`xml` or `html`) is set.
+                            If you don't specify `tag_handling_version`, this shows the default
+                            that was applied.
+                          type: string
+                          enum:
+                            - v2
+                            - v1
+                          example: v2
 
         400:
           $ref: '#/components/responses/BadRequest'
diff --git a/api-reference/translate.mdx b/api-reference/translate.mdx
index f817075..ff502ce 100644
--- a/api-reference/translate.mdx
+++ b/api-reference/translate.mdx
@@ -326,6 +326,7 @@ Note that we do not include examples for our client libraries in every single se
     <li><code>v2</code>: Use the improved v2 algorithm.</li>
     <li><code>v1</code>: Use the previous v1 algorithm.</li>
   </ul>
+  When `tag_handling` is set, the response includes a `tag_handling_version` field showing which version is used, including the default applied when you don't specify `tag_handling_version`.
 </ParamField>
 <ParamField body="outline_detection" type="boolean">
   The automatic detection of the XML structure won't yield best results in all XML files. You can disable this automatic mechanism altogether by setting the <code>outline_detection</code> parameter to <code>false</code> and selecting the tags that should be considered structure tags. This will split sentences using the <code>splitting_tags</code> parameter.

From 31aa8fcc960177de99f71584915da9e9c641abea Mon Sep 17 00:00:00 2001
From: kabraham13 <113049809+kabraham13@users.noreply.github.com>
Date: Mon, 22 Jun 2026 15:14:07 +0000
Subject: [PATCH 2/3] chore: update OpenAPI JSON files from YAML sources

---
 api-reference/openapi.json | 9 +++++++++
 1 file changed, 9 insertions(+)

diff --git a/api-reference/openapi.json b/api-reference/openapi.json
index d4727c1..cb88b5e 100644
--- a/api-reference/openapi.json
+++ b/api-reference/openapi.json
@@ -984,6 +984,15 @@
                             "description": "Indicates the translation model used. Only present if model_type parameter is included in the request.",
                             "type": "string",
                             "example": "quality_optimized"
+                          },
+                          "tag_handling_version": {
+                            "description": "The version of the tag handling algorithm used for the translation. Only present when the `tag_handling` parameter (`xml` or `html`) is set. If you don't specify `tag_handling_version`, this shows the default that was applied.",
+                            "type": "string",
+                            "enum": [
+                              "v2",
+                              "v1"
+                            ],
+                            "example": "v2"
                           }
                         }
                       }

From d07a058e07ff2fb79a63d159d4125c833d58a1df Mon Sep 17 00:00:00 2001
From: Kevin Abraham <kevin.abraham@deepl.com>
Date: Mon, 22 Jun 2026 11:22:45 -0400
Subject: [PATCH 3/3] docs: tighten tag_handling_version response wording

---
 api-reference/translate.mdx | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/api-reference/translate.mdx b/api-reference/translate.mdx
index ff502ce..43f3034 100644
--- a/api-reference/translate.mdx
+++ b/api-reference/translate.mdx
@@ -326,7 +326,7 @@ Note that we do not include examples for our client libraries in every single se
     <li><code>v2</code>: Use the improved v2 algorithm.</li>
     <li><code>v1</code>: Use the previous v1 algorithm.</li>
   </ul>
-  When `tag_handling` is set, the response includes a `tag_handling_version` field showing which version is used, including the default applied when you don't specify `tag_handling_version`.
+  When `tag_handling` is set, the response includes a `tag_handling_version` field showing which version was applied, including the default when you don't specify one.
 </ParamField>
 <ParamField body="outline_detection" type="boolean">
   The automatic detection of the XML structure won't yield best results in all XML files. You can disable this automatic mechanism altogether by setting the <code>outline_detection</code> parameter to <code>false</code> and selecting the tags that should be considered structure tags. This will split sentences using the <code>splitting_tags</code> parameter.