From 8a05f8531050ae3e5d243913e5aa8a77c131f8c4 Mon Sep 17 00:00:00 2001 From: Maxim Brunnmeier Date: Mon, 14 Sep 2026 14:19:58 +0200 Subject: [PATCH 1/3] docs: add style_profile_id to POST /v2/translate A request names a style profile instead of listing its components. Documents how the profile is applied per text once the source language is known, that components which do not fit a text's language pair are left out, the exclusivity with the customizations object and the individual parameters (400), unknown profiles (404), and accounts without style profiles (403). Adds the style profiles row to the customize overview. --- api-reference/openapi.json | 12 ++++++++++++ api-reference/openapi.yaml | 38 +++++++++++++++++++++++++++++++++++++ docs/customize/overview.mdx | 1 + 3 files changed, 51 insertions(+) diff --git a/api-reference/openapi.json b/api-reference/openapi.json index 28dc1266..8cfa8258 100644 --- a/api-reference/openapi.json +++ b/api-reference/openapi.json @@ -836,6 +836,12 @@ "example": "Use a friendly, diplomatic tone" } }, + "style_profile_id": { + "description": "Translate with a [style profile](/api-reference/style-profiles/get-style-profile): its glossaries,\nstyle rule lists, translation memories and example documents through one ID. The profile is applied\nper text once the source language is known: the glossaries with a dictionary for the text's language\npair, the style rule list for the target language, the translation memories whose source language\nmatches the text, and the example documents written in the target language. A component that does\nnot fit a text's language pair is left out for that text; this is not an error.\n\nA style profile is a complete set of customizations, so it cannot be combined with `customizations`,\n`glossary_id`, `glossary_ids`, `style_id`, `translation_memory_id`, `translation_memory_threshold` or\n`custom_instructions`. A request that combines them is rejected with `400 Bad Request`. A style\nprofile that does not exist or that your account cannot access is rejected with `404 Not Found`.\n\nAvailable for accounts with style profiles enabled; otherwise the request is rejected with\n`403 Forbidden`.", + "type": "string", + "format": "uuid", + "example": "3f1c9d0e-7a24-4b58-9c31-8f0e5d2a1b47" + }, "tag_handling": { "$ref": "#/components/schemas/TagHandlingOption" }, @@ -938,6 +944,12 @@ "translation_memory_threshold": { "$ref": "#/components/schemas/TranslationMemoryThreshold" }, + "style_profile_id": { + "description": "Translate with a [style profile](/api-reference/style-profiles/get-style-profile): its glossaries,\nstyle rule lists, translation memories and example documents through one ID. The profile is applied\nper text once the source language is known: the glossaries with a dictionary for the text's language\npair, the style rule list for the target language, the translation memories whose source language\nmatches the text, and the example documents written in the target language. A component that does\nnot fit a text's language pair is left out for that text; this is not an error.\n\nA style profile is a complete set of customizations, so it cannot be combined with `customizations`,\n`glossary_id`, `glossary_ids`, `style_id`, `translation_memory_id`, `translation_memory_threshold` or\n`custom_instructions`. A request that combines them is rejected with `400 Bad Request`. A style\nprofile that does not exist or that your account cannot access is rejected with `404 Not Found`.\n\nAvailable for accounts with style profiles enabled; otherwise the request is rejected with\n`403 Forbidden`.", + "type": "string", + "format": "uuid", + "example": "3f1c9d0e-7a24-4b58-9c31-8f0e5d2a1b47" + }, "tag_handling": { "$ref": "#/components/schemas/TagHandlingOption" }, diff --git a/api-reference/openapi.yaml b/api-reference/openapi.yaml index 3686cf76..a8e09b83 100644 --- a/api-reference/openapi.yaml +++ b/api-reference/openapi.yaml @@ -668,6 +668,25 @@ paths: items: type: string example: "Use a friendly, diplomatic tone" + style_profile_id: + description: |- + Translate with a [style profile](/api-reference/style-profiles/get-style-profile): its glossaries, + style rule lists, translation memories and example documents through one ID. The profile is applied + per text once the source language is known: the glossaries with a dictionary for the text's language + pair, the style rule list for the target language, the translation memories whose source language + matches the text, and the example documents written in the target language. A component that does + not fit a text's language pair is left out for that text; this is not an error. + + A style profile is a complete set of customizations, so it cannot be combined with `customizations`, + `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 rejected with `404 Not Found`. + + Available for accounts with style profiles enabled; otherwise the request is rejected with + `403 Forbidden`. + type: string + format: uuid + example: 3f1c9d0e-7a24-4b58-9c31-8f0e5d2a1b47 tag_handling: $ref: '#/components/schemas/TagHandlingOption' tag_handling_version: @@ -755,6 +774,25 @@ paths: $ref: '#/components/schemas/TranslationMemoryId' translation_memory_threshold: $ref: '#/components/schemas/TranslationMemoryThreshold' + style_profile_id: + description: |- + Translate with a [style profile](/api-reference/style-profiles/get-style-profile): its glossaries, + style rule lists, translation memories and example documents through one ID. The profile is applied + per text once the source language is known: the glossaries with a dictionary for the text's language + pair, the style rule list for the target language, the translation memories whose source language + matches the text, and the example documents written in the target language. A component that does + not fit a text's language pair is left out for that text; this is not an error. + + A style profile is a complete set of customizations, so it cannot be combined with `customizations`, + `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 rejected with `404 Not Found`. + + Available for accounts with style profiles enabled; otherwise the request is rejected with + `403 Forbidden`. + type: string + format: uuid + example: 3f1c9d0e-7a24-4b58-9c31-8f0e5d2a1b47 tag_handling: $ref: '#/components/schemas/TagHandlingOption' outline_detection: diff --git a/docs/customize/overview.mdx b/docs/customize/overview.mdx index b1184a2c..4491cbbf 100644 --- a/docs/customize/overview.mdx +++ b/docs/customize/overview.mdx @@ -16,6 +16,7 @@ DeepL's customization features let you control terminology, style, and consisten | [Custom instructions](/docs/customize/custom-instructions) | Tone, phrasing, and domain-specific behavior via natural-language directives | Inline per request via `custom_instructions`, or stored in a style rule list | | [Translation memories](/docs/customize/using-translation-memories) | Reuse of your previously approved translations for matching segments | Stored on your account; passed per request via `translation_memory_id` | | [Spoken terms](/docs/customize/improving-transcription-with-spoken-terms) | Recognition of specific terms during Voice API speech transcription | Stored on your account; passed per voice session via `spoken_terms_id` | +| [Style profiles](/api-reference/style-profiles/list-all-style-profiles) | A named bundle of glossaries, style rules, translation memories and example documents for one purpose | Stored on your account; passed per request via `style_profile_id`, which stands in for the individual parameters | Glossaries, style rules, custom instructions, and translation memories work with both [text translation](/docs/translate/translate-text-quickstart) and [document translation](/docs/translate/translate-documents-quickstart), support all `model_type` values, and can be combined in a single request. Spoken terms apply to [Voice API](/docs/voice/overview) sessions, where they can be combined with glossaries. From 4887dbcb48e01aa0219a8dea61818225e9e8a45b Mon Sep 17 00:00:00 2001 From: Maxim Brunnmeier Date: Tue, 13 Oct 2026 14:16:43 +0200 Subject: [PATCH 2/3] fix: answer 400 for style_profile_id on an account without style profiles The translate endpoint rejects a gated style_profile_id with 400 Bad Request, like the customizations object. --- api-reference/openapi.json | 4 ++-- api-reference/openapi.yaml | 4 ++-- 2 files changed, 4 insertions(+), 4 deletions(-) diff --git a/api-reference/openapi.json b/api-reference/openapi.json index 8cfa8258..5ea93b7f 100644 --- a/api-reference/openapi.json +++ b/api-reference/openapi.json @@ -837,7 +837,7 @@ } }, "style_profile_id": { - "description": "Translate with a [style profile](/api-reference/style-profiles/get-style-profile): its glossaries,\nstyle rule lists, translation memories and example documents through one ID. The profile is applied\nper text once the source language is known: the glossaries with a dictionary for the text's language\npair, the style rule list for the target language, the translation memories whose source language\nmatches the text, and the example documents written in the target language. A component that does\nnot fit a text's language pair is left out for that text; this is not an error.\n\nA style profile is a complete set of customizations, so it cannot be combined with `customizations`,\n`glossary_id`, `glossary_ids`, `style_id`, `translation_memory_id`, `translation_memory_threshold` or\n`custom_instructions`. A request that combines them is rejected with `400 Bad Request`. A style\nprofile that does not exist or that your account cannot access is rejected with `404 Not Found`.\n\nAvailable for accounts with style profiles enabled; otherwise the request is rejected with\n`403 Forbidden`.", + "description": "Translate with a [style profile](/api-reference/style-profiles/get-style-profile): its glossaries,\nstyle rule lists, translation memories and example documents through one ID. The profile is applied\nper text once the source language is known: the glossaries with a dictionary for the text's language\npair, the style rule list for the target language, the translation memories whose source language\nmatches the text, and the example documents written in the target language. A component that does\nnot fit a text's language pair is left out for that text; this is not an error.\n\nA style profile is a complete set of customizations, so it cannot be combined with `customizations`,\n`glossary_id`, `glossary_ids`, `style_id`, `translation_memory_id`, `translation_memory_threshold` or\n`custom_instructions`. A request that combines them is rejected with `400 Bad Request`. A style\nprofile that does not exist or that your account cannot access is rejected with `404 Not Found`.\n\nAvailable for accounts with style profiles enabled; otherwise the request is rejected with\n`400 Bad Request`.", "type": "string", "format": "uuid", "example": "3f1c9d0e-7a24-4b58-9c31-8f0e5d2a1b47" @@ -945,7 +945,7 @@ "$ref": "#/components/schemas/TranslationMemoryThreshold" }, "style_profile_id": { - "description": "Translate with a [style profile](/api-reference/style-profiles/get-style-profile): its glossaries,\nstyle rule lists, translation memories and example documents through one ID. The profile is applied\nper text once the source language is known: the glossaries with a dictionary for the text's language\npair, the style rule list for the target language, the translation memories whose source language\nmatches the text, and the example documents written in the target language. A component that does\nnot fit a text's language pair is left out for that text; this is not an error.\n\nA style profile is a complete set of customizations, so it cannot be combined with `customizations`,\n`glossary_id`, `glossary_ids`, `style_id`, `translation_memory_id`, `translation_memory_threshold` or\n`custom_instructions`. A request that combines them is rejected with `400 Bad Request`. A style\nprofile that does not exist or that your account cannot access is rejected with `404 Not Found`.\n\nAvailable for accounts with style profiles enabled; otherwise the request is rejected with\n`403 Forbidden`.", + "description": "Translate with a [style profile](/api-reference/style-profiles/get-style-profile): its glossaries,\nstyle rule lists, translation memories and example documents through one ID. The profile is applied\nper text once the source language is known: the glossaries with a dictionary for the text's language\npair, the style rule list for the target language, the translation memories whose source language\nmatches the text, and the example documents written in the target language. A component that does\nnot fit a text's language pair is left out for that text; this is not an error.\n\nA style profile is a complete set of customizations, so it cannot be combined with `customizations`,\n`glossary_id`, `glossary_ids`, `style_id`, `translation_memory_id`, `translation_memory_threshold` or\n`custom_instructions`. A request that combines them is rejected with `400 Bad Request`. A style\nprofile that does not exist or that your account cannot access is rejected with `404 Not Found`.\n\nAvailable for accounts with style profiles enabled; otherwise the request is rejected with\n`400 Bad Request`.", "type": "string", "format": "uuid", "example": "3f1c9d0e-7a24-4b58-9c31-8f0e5d2a1b47" diff --git a/api-reference/openapi.yaml b/api-reference/openapi.yaml index a8e09b83..064e79fb 100644 --- a/api-reference/openapi.yaml +++ b/api-reference/openapi.yaml @@ -683,7 +683,7 @@ paths: profile that does not exist or that your account cannot access is rejected with `404 Not Found`. Available for accounts with style profiles enabled; otherwise the request is rejected with - `403 Forbidden`. + `400 Bad Request`. type: string format: uuid example: 3f1c9d0e-7a24-4b58-9c31-8f0e5d2a1b47 @@ -789,7 +789,7 @@ paths: profile that does not exist or that your account cannot access is rejected with `404 Not Found`. Available for accounts with style profiles enabled; otherwise the request is rejected with - `403 Forbidden`. + `400 Bad Request`. type: string format: uuid example: 3f1c9d0e-7a24-4b58-9c31-8f0e5d2a1b47 From 31a8992e200b3fd58af9f15b9a2e020105ea2e4c Mon Sep 17 00:00:00 2001 From: Maxim Brunnmeier Date: Tue, 13 Oct 2026 15:31:28 +0200 Subject: [PATCH 3/3] fix: describe style_profile_id without example documents Example documents and the customizations object ship later, so style_profile_id only names the components and conflicting parameters that are available now. --- api-reference/openapi.json | 4 ++-- api-reference/openapi.yaml | 28 ++++++++++++++-------------- docs/customize/overview.mdx | 2 +- 3 files changed, 17 insertions(+), 17 deletions(-) diff --git a/api-reference/openapi.json b/api-reference/openapi.json index 5ea93b7f..161c1aa6 100644 --- a/api-reference/openapi.json +++ b/api-reference/openapi.json @@ -837,7 +837,7 @@ } }, "style_profile_id": { - "description": "Translate with a [style profile](/api-reference/style-profiles/get-style-profile): its glossaries,\nstyle rule lists, translation memories and example documents through one ID. The profile is applied\nper text once the source language is known: the glossaries with a dictionary for the text's language\npair, the style rule list for the target language, the translation memories whose source language\nmatches the text, and the example documents written in the target language. A component that does\nnot fit a text's language pair is left out for that text; this is not an error.\n\nA style profile is a complete set of customizations, so it cannot be combined with `customizations`,\n`glossary_id`, `glossary_ids`, `style_id`, `translation_memory_id`, `translation_memory_threshold` or\n`custom_instructions`. A request that combines them is rejected with `400 Bad Request`. A style\nprofile that does not exist or that your account cannot access is rejected with `404 Not Found`.\n\nAvailable for accounts with style profiles enabled; otherwise the request is rejected with\n`400 Bad Request`.", + "description": "Translate with a [style profile](/api-reference/style-profiles/get-style-profile): its glossaries,\nstyle rule lists and translation memories through one ID. The profile is applied per text once the\nsource language is known: the glossaries with a dictionary for the text's language pair, the style\nrule list for the target language, and the translation memories whose source language matches the\ntext. A component that does not fit a text's language pair is left out for that text; this is not an\nerror.\n\nA style profile is a complete set of customizations, so it cannot be combined with `glossary_id`,\n`glossary_ids`, `style_id`, `translation_memory_id`, `translation_memory_threshold` or\n`custom_instructions`. A request that combines them is rejected with `400 Bad Request`. A style\nprofile that does not exist or that your account cannot access is rejected with `404 Not Found`.\n\nAvailable for accounts with style profiles enabled; otherwise the request is rejected with\n`400 Bad Request`.", "type": "string", "format": "uuid", "example": "3f1c9d0e-7a24-4b58-9c31-8f0e5d2a1b47" @@ -945,7 +945,7 @@ "$ref": "#/components/schemas/TranslationMemoryThreshold" }, "style_profile_id": { - "description": "Translate with a [style profile](/api-reference/style-profiles/get-style-profile): its glossaries,\nstyle rule lists, translation memories and example documents through one ID. The profile is applied\nper text once the source language is known: the glossaries with a dictionary for the text's language\npair, the style rule list for the target language, the translation memories whose source language\nmatches the text, and the example documents written in the target language. A component that does\nnot fit a text's language pair is left out for that text; this is not an error.\n\nA style profile is a complete set of customizations, so it cannot be combined with `customizations`,\n`glossary_id`, `glossary_ids`, `style_id`, `translation_memory_id`, `translation_memory_threshold` or\n`custom_instructions`. A request that combines them is rejected with `400 Bad Request`. A style\nprofile that does not exist or that your account cannot access is rejected with `404 Not Found`.\n\nAvailable for accounts with style profiles enabled; otherwise the request is rejected with\n`400 Bad Request`.", + "description": "Translate with a [style profile](/api-reference/style-profiles/get-style-profile): its glossaries,\nstyle rule lists and translation memories through one ID. The profile is applied per text once the\nsource language is known: the glossaries with a dictionary for the text's language pair, the style\nrule list for the target language, and the translation memories whose source language matches the\ntext. A component that does not fit a text's language pair is left out for that text; this is not an\nerror.\n\nA style profile is a complete set of customizations, so it cannot be combined with `glossary_id`,\n`glossary_ids`, `style_id`, `translation_memory_id`, `translation_memory_threshold` or\n`custom_instructions`. A request that combines them is rejected with `400 Bad Request`. A style\nprofile that does not exist or that your account cannot access is rejected with `404 Not Found`.\n\nAvailable for accounts with style profiles enabled; otherwise the request is rejected with\n`400 Bad Request`.", "type": "string", "format": "uuid", "example": "3f1c9d0e-7a24-4b58-9c31-8f0e5d2a1b47" diff --git a/api-reference/openapi.yaml b/api-reference/openapi.yaml index 064e79fb..4c986c7d 100644 --- a/api-reference/openapi.yaml +++ b/api-reference/openapi.yaml @@ -671,14 +671,14 @@ paths: style_profile_id: description: |- Translate with a [style profile](/api-reference/style-profiles/get-style-profile): its glossaries, - style rule lists, translation memories and example documents through one ID. The profile is applied - per text once the source language is known: the glossaries with a dictionary for the text's language - pair, the style rule list for the target language, the translation memories whose source language - matches the text, and the example documents written in the target language. A component that does - not fit a text's language pair is left out for that text; this is not an error. + style rule lists and translation memories through one ID. The profile is applied per text once the + source language is known: the glossaries with a dictionary for the text's language pair, the style + rule list for the target language, and the translation memories whose source language matches the + text. A component that does not fit a text's language pair is left out for that text; this is not an + error. - A style profile is a complete set of customizations, so it cannot be combined with `customizations`, - `glossary_id`, `glossary_ids`, `style_id`, `translation_memory_id`, `translation_memory_threshold` or + A style profile is a complete set of customizations, so it 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 rejected with `404 Not Found`. @@ -777,14 +777,14 @@ paths: style_profile_id: description: |- Translate with a [style profile](/api-reference/style-profiles/get-style-profile): its glossaries, - style rule lists, translation memories and example documents through one ID. The profile is applied - per text once the source language is known: the glossaries with a dictionary for the text's language - pair, the style rule list for the target language, the translation memories whose source language - matches the text, and the example documents written in the target language. A component that does - not fit a text's language pair is left out for that text; this is not an error. + style rule lists and translation memories through one ID. The profile is applied per text once the + source language is known: the glossaries with a dictionary for the text's language pair, the style + rule list for the target language, and the translation memories whose source language matches the + text. A component that does not fit a text's language pair is left out for that text; this is not an + error. - A style profile is a complete set of customizations, so it cannot be combined with `customizations`, - `glossary_id`, `glossary_ids`, `style_id`, `translation_memory_id`, `translation_memory_threshold` or + A style profile is a complete set of customizations, so it 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 rejected with `404 Not Found`. diff --git a/docs/customize/overview.mdx b/docs/customize/overview.mdx index 4491cbbf..0bf37067 100644 --- a/docs/customize/overview.mdx +++ b/docs/customize/overview.mdx @@ -16,7 +16,7 @@ DeepL's customization features let you control terminology, style, and consisten | [Custom instructions](/docs/customize/custom-instructions) | Tone, phrasing, and domain-specific behavior via natural-language directives | Inline per request via `custom_instructions`, or stored in a style rule list | | [Translation memories](/docs/customize/using-translation-memories) | Reuse of your previously approved translations for matching segments | Stored on your account; passed per request via `translation_memory_id` | | [Spoken terms](/docs/customize/improving-transcription-with-spoken-terms) | Recognition of specific terms during Voice API speech transcription | Stored on your account; passed per voice session via `spoken_terms_id` | -| [Style profiles](/api-reference/style-profiles/list-all-style-profiles) | A named bundle of glossaries, style rules, translation memories and example documents for one purpose | Stored on your account; passed per request via `style_profile_id`, which stands in for the individual parameters | +| [Style profiles](/api-reference/style-profiles/list-all-style-profiles) | A named bundle of glossaries, style rules and translation memories for one purpose | Stored on your account; passed per request via `style_profile_id`, which stands in for the individual parameters | Glossaries, style rules, custom instructions, and translation memories work with both [text translation](/docs/translate/translate-text-quickstart) and [document translation](/docs/translate/translate-documents-quickstart), support all `model_type` values, and can be combined in a single request. Spoken terms apply to [Voice API](/docs/voice/overview) sessions, where they can be combined with glossaries.