docs: document custom_instructions on POST /v2/document

api-reference/openapi.json

@@ -1173,6 +1173,14 @@
                     "translation_memory_threshold": 75
                   }
                 },
+                "CustomInstructions": {
+                  "summary": "Using Custom Instructions",
+                  "value": {
+                    "target_lang": "DE",
+                    "file": "@document.docx",
+                    "custom_instructions": "[\"Use a friendly, diplomatic tone\", \"Keep sentences short\"]"
+                  }
+                },
                 "QualityEvaluation": {
                   "summary": "Requesting a quality evaluation report (beta)",
                   "value": {
@@ -1242,8 +1250,13 @@
                   "translation_memory_threshold": {
                     "$ref": "#/components/schemas/TranslationMemoryThreshold"
                   },
+                  "custom_instructions": {
+                    "description": "Specify a list of instructions to customize the translation behavior, as a JSON array of strings, for example `[\"Use a friendly, diplomatic tone\"]`. Up to 10 custom instructions can be specified, each with a maximum of 300 characters.\n\nRejected with `400` before the upload is accepted if the value is not a JSON array of strings or exceeds these limits.",
+                    "type": "string",
+                    "example": "[\"Use a friendly, diplomatic tone\"]"
+                  },
                   "style_profile_id": {
-                    "description": "Translate with a [style profile](/api-reference/style-profiles/list-all-style-profiles): its glossaries,\nstyle rule lists and translation memories through one ID. The profile is applied once the\ndocument's source language is known: the glossaries with a dictionary for the language pair, the\nstyle rule list for the target language, and the translation memories whose source language matches\nthe document. A component that does not fit the language pair is left out; this is not an error.\n\nCannot be combined with `glossary_id`, `glossary_ids`, `style_id`, `translation_memory_id` or\n`translation_memory_threshold`. A request that combines them is rejected with `400 Bad Request`.\nA style profile that does not exist or that your account cannot access is not rejected at upload:\nthe document status reports an error with the message `Style profile not found.`.",
+                    "description": "Translate with a [style profile](/api-reference/style-profiles/list-all-style-profiles): its glossaries,\nstyle rule lists and translation memories through one ID. The profile is applied once the\ndocument's source language is known: the glossaries with a dictionary for the language pair, the\nstyle rule list for the target language, and the translation memories whose source language matches\nthe document. A component that does not fit the language pair is left out; this is not an error.\n\nCannot be combined with `glossary_id`, `glossary_ids`, `style_id`, `translation_memory_id`,\n`translation_memory_threshold` or `custom_instructions`. A request that combines them is rejected\nwith `400 Bad Request`.\nA style profile that does not exist or that your account cannot access is not rejected at upload:\nthe document status reports an error with the message `Style profile not found.`.",
                     "type": "string",
                     "format": "uuid",
                     "example": "3f1c9d0e-7a24-4b58-9c31-8f0e5d2a1b47"

api-reference/openapi.yaml

@@ -991,6 +991,12 @@ paths:
                   file: '@document.docx'
                   translation_memory_id: '[yourTranslationMemoryId]'
                   translation_memory_threshold: 75
+              CustomInstructions:
+                summary: Using Custom Instructions
+                value:
+                  target_lang: DE
+                  file: '@document.docx'
+                  custom_instructions: '["Use a friendly, diplomatic tone", "Keep sentences short"]'
               QualityEvaluation:
                 summary: Requesting a quality evaluation report (beta)
                 value:
@@ -1096,6 +1102,13 @@ paths:
                   $ref: '#/components/schemas/TranslationMemoryId'
                 translation_memory_threshold:
                   $ref: '#/components/schemas/TranslationMemoryThreshold'
+                custom_instructions:
+                  description: |-
+                    Specify a list of instructions to customize the translation behavior, as a JSON array of strings, for example `["Use a friendly, diplomatic tone"]`. Up to 10 custom instructions can be specified, each with a maximum of 300 characters.
+
+                    Rejected with `400` before the upload is accepted if the value is not a JSON array of strings or exceeds these limits.
+                  type: string
+                  example: '["Use a friendly, diplomatic tone"]'
                 style_profile_id:
                   description: |-
                     Translate with a [style profile](/api-reference/style-profiles/list-all-style-profiles): its glossaries,
@@ -1104,8 +1117,9 @@ paths:
                     style rule list for the target language, and the translation memories whose source language matches
                     the document. A component that does not fit the language pair is left out; this is not an error.
 
-                    Cannot be combined with `glossary_id`, `glossary_ids`, `style_id`, `translation_memory_id` or
-                    `translation_memory_threshold`. A request that combines them is rejected with `400 Bad Request`.
+                    Cannot be combined with `glossary_id`, `glossary_ids`, `style_id`, `translation_memory_id`,
+                    `translation_memory_threshold` or `custom_instructions`. A request that combines them is rejected
+                    with `400 Bad Request`.
                     A style profile that does not exist or that your account cannot access is not rejected at upload:
                     the document status reports an error with the message `Style profile not found.`.
                   type: string

docs/customize/custom-instructions.mdx

@@ -116,6 +116,7 @@ When using custom instructions, keep these constraints in mind:
 ## Related documentation
 
 - [Text translation API reference](/api-reference/translate/request-translation)
+- [Document translation API reference](/api-reference/document/upload-and-translate-a-document)
 - [Working with context](/docs/learning-how-tos/examples-and-guides/how-to-use-context-parameter)
 - [Style rules API](/docs/customize/using-style-rules)
 - [Multilingual glossaries](/docs/customize/managing-glossaries)

docs/resources/roadmap-and-release-notes.mdx

@@ -8,6 +8,13 @@ rss: true
 - Editing the contents of an existing [translation memory](/docs/customize/using-translation-memories) via API
 </Update>
 
+<Update label="November 2026">
+## November 2 - Custom Instructions for Document Translation
+- [Custom instructions](/docs/customize/custom-instructions) are natural language directives, such as "Use a friendly, diplomatic tone", that guide how DeepL translates. [`POST /v2/document`](/api-reference/document/upload-and-translate-a-document) now accepts them in the `custom_instructions` parameter, as they already work in text translation.
+- Send the instructions as a JSON array of strings in a single form field, for example `["Use a friendly, diplomatic tone"]`. The same limits as text translation apply: up to 10 instructions, each with a maximum of 300 characters.
+- The upload is rejected with `400` if the value is not a JSON array of strings, exceeds these limits, or is combined with `style_profile_id`.
+</Update>
+
 <Update label="October 2026">
 ## October 29 - Higher Character Limit Per Document
 - Documents submitted with [`POST /v2/document`](/api-reference/document/upload-and-translate-a-document) on DeepL API paid plans can now contain up to 5 million characters for Word, PowerPoint, and PDF, increased from 1 million. Other formats keep their existing per-document character limit.