docs: document custom_instructions on POST /v2/document

api-reference/openapi.json

@@ -1154,6 +1154,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": {
@@ -1223,6 +1231,11 @@
                   "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\"]"
+                  },
                   "enable_watermark": {
                     "description": "When `true`, adds a \"Translated by DeepL\" watermark to the translated document.\n\nOnly supported for `docx` and `pdf` output. For all other output formats the parameter is ignored and the document is returned without a watermark.",
                     "type": "boolean",

api-reference/openapi.yaml

@@ -927,6 +927,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:
@@ -1028,6 +1034,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"]'
                 enable_watermark:
                   description: |-
                     When `true`, adds a "Translated by DeepL" watermark to the translated document.

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)