diff --git a/api-reference/openapi.json b/api-reference/openapi.json index 735d58cf..949031e1 100644 --- a/api-reference/openapi.json +++ b/api-reference/openapi.json @@ -57,6 +57,10 @@ "name": "ManageGlossaries", "description": "Please note that this is the spec for the (old) v2 glossary endpoint.\nWe recommend users switch to the newer v3 glossary endpoints, which support editability and multilinguality.\n\nThe *glossary* functions allow you to create, inspect, and delete glossaries.\nGlossaries created with the glossary function can be used in translate requests by specifying the\n`glossary_id` parameter.\nIf you encounter issues, please let us know at support@DeepL.com.\n\nCurrently you can create glossaries with any of the languages DeepL supports (with the exception of Thai)." }, + { + "name": "ManageStyleProfiles", + "description": "The style profile endpoints allow you to create, inspect, edit and delete style profiles. A style\nprofile bundles glossaries, style rule lists and translation memories under one ID. Pass its\n`style_profile_id` in a translation request instead of the individual customization parameters.\n\nEvery component list is optional, and you can link components later with an update. A style\nprofile can reference at most one style rule list per target language and at most one translation\nmemory per source language. With `glossary_priority_order_enabled`, the order of the glossary IDs\ndecides which glossary wins when two of them define the same source term.\n\nDeleting a style profile does not delete the glossaries, style rule lists and translation memories it\nlinks. Deleting one of those components removes it from every style profile that links it." + }, { "name": "MetaInformation", "description": "Information about API usage and value ranges" @@ -832,6 +836,12 @@ "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 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\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`. A style profile that does not exist or that your account cannot access is\nrejected with `404 Not Found`.", + "type": "string", + "format": "uuid", + "example": "3f1c9d0e-7a24-4b58-9c31-8f0e5d2a1b47" + }, "tag_handling": { "$ref": "#/components/schemas/TagHandlingOption" }, @@ -934,6 +944,12 @@ "translation_memory_threshold": { "$ref": "#/components/schemas/TranslationMemoryThreshold" }, + "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 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\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`. A style profile that does not exist or that your account cannot access is\nrejected with `404 Not Found`.", + "type": "string", + "format": "uuid", + "example": "3f1c9d0e-7a24-4b58-9c31-8f0e5d2a1b47" + }, "tag_handling": { "$ref": "#/components/schemas/TagHandlingOption" }, @@ -1194,6 +1210,12 @@ "translation_memory_threshold": { "$ref": "#/components/schemas/TranslationMemoryThreshold" }, + "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.`.", + "type": "string", + "format": "uuid", + "example": "3f1c9d0e-7a24-4b58-9c31-8f0e5d2a1b47" + }, "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", @@ -5163,10 +5185,14 @@ ] } }, - "/v3/style_rules": { + "/v3/style_profiles": { "get": { - "summary": "Retrieve style rule lists", - "operationId": "getStyleRuleLists", + "tags": [ + "ManageStyleProfiles" + ], + "summary": "List style profiles", + "operationId": "listStyleProfiles", + "description": "Retrieve a list of style profiles available to the authenticated account, newest first.\n\nThe list includes style profiles that have been shared with the account.\n\nRequires an API key with the `style_profiles:read` scope.", "parameters": [ { "name": "page", @@ -5175,32 +5201,21 @@ "type": "integer", "default": 0 }, - "description": "The index of the first page to return. Use with `page_size` to get the next page of rule lists" + "description": "The index of the first page to return. Use with `page_size` to get the next page of style profiles." }, { "name": "page_size", "in": "query", "schema": { "type": "integer", - "default": 10, - "minimum": 1, - "maximum": 25 - }, - "description": "The maximum number of style rule lists to return." - }, - { - "name": "detailed", - "in": "query", - "schema": { - "type": "boolean", - "default": false + "default": 10 }, - "description": "Determines if the rule list's `configured_rules` and `custom_instructions` should be included in the response body." + "description": "The maximum number of style profiles to return. Values above 100 are reduced to 100." } ], "responses": { "200": { - "description": "JSON object containing the style rule lists.", + "description": "Returns a list of style profiles.", "headers": { "X-Trace-ID": { "$ref": "#/components/headers/X-Trace-ID" @@ -5211,11 +5226,53 @@ "schema": { "type": "object", "properties": { - "style_rules": { + "style_profiles": { "type": "array", "items": { - "$ref": "#/components/schemas/StyleRuleList" + "$ref": "#/components/schemas/StyleProfile" } + }, + "total_count": { + "type": "integer", + "description": "The total number of style profiles available to the account.", + "example": 2 + } + } + }, + "examples": { + "Basic": { + "value": { + "style_profiles": [ + { + "style_profile_id": "3f1c9d0e-7a24-4b58-9c31-8f0e5d2a1b47", + "name": "Legal, German", + "description": "Contract wording for the German market.", + "industry": "Legal", + "glossary_ids": [ + "4d0a2e1c-6b93-4f7a-8d15-2c6e9a3b7f81" + ], + "style_rule_ids": [ + "bd0a38f3-1831-440b-a8dd-2c702e2325ab" + ], + "translation_memory_ids": [ + "a74d88fb-ed2a-4943-a664-a4512398b994" + ], + "glossary_priority_order_enabled": true, + "creation_time": "2026-04-01T16:34:25.223Z", + "updated_time": "2026-08-06T09:12:44.108Z" + }, + { + "style_profile_id": "c58e2a71-90b4-4d6f-a2e3-71d5c8b4f902", + "name": "Marketing, Japanese", + "glossary_ids": [], + "style_rule_ids": [], + "translation_memory_ids": [], + "glossary_priority_order_enabled": false, + "creation_time": "2026-07-14T11:02:09.640Z", + "updated_time": "2026-07-14T11:02:09.640Z" + } + ], + "total_count": 2 } } } @@ -5248,8 +5305,12 @@ ] }, "post": { - "summary": "Create a style rule list", - "operationId": "createStyleRuleList", + "tags": [ + "ManageStyleProfiles" + ], + "summary": "Create a style profile", + "operationId": "createStyleProfile", + "description": "Create a style profile. Only `name` is required.\n\nIf any of the component IDs cannot be used, the request fails and no style profile is created.\n\nRequires an API key with the `style_profiles:write` scope.", "requestBody": { "required": true, "content": { @@ -5257,76 +5318,97 @@ "schema": { "type": "object", "required": [ - "name", - "language" + "name" ], "properties": { "name": { - "$ref": "#/components/schemas/StyleRuleName", - "x-default": "My style rules" + "description": "Name for the style profile. At most 255 characters. An empty name is rejected with\n`400 Bad Request`.", + "type": "string", + "example": "Legal, German" }, - "language": { - "$ref": "#/components/schemas/StyleRuleLanguage", - "x-default": "de" + "description": { + "description": "Free-text description of the style profile. At most 1000 characters. Omit it to create\nthe style profile without a description.", + "type": "string", + "example": "Contract wording for the German market." }, - "configured_rules": { - "$ref": "#/components/schemas/ConfiguredRules" + "industry": { + "description": "The industry the style profile is written for. At most 255 characters. Omit it to create\nthe style profile without an industry.", + "type": "string", + "example": "Legal" }, - "custom_instructions": { + "glossary_ids": { + "description": "The IDs of the glossaries to link, highest priority first. The order only takes effect\nwith `glossary_priority_order_enabled`. Defaults to an empty list.", "type": "array", - "description": "Array of custom instruction objects", - "maxItems": 200, "items": { - "type": "object", - "required": [ - "label", - "prompt" - ], - "properties": { - "label": { - "type": "string", - "description": "Label for the custom instruction" - }, - "prompt": { - "type": "string", - "description": "Instruction text", - "maxLength": 300 - }, - "source_language": { - "type": "string", - "description": "Optional source language code" - } - } - } + "type": "string", + "format": "uuid" + }, + "example": [ + "4d0a2e1c-6b93-4f7a-8d15-2c6e9a3b7f81" + ] + }, + "style_rule_ids": { + "description": "The IDs of the style rule lists to link. At most one style rule list per target\nlanguage. Defaults to an empty list.", + "type": "array", + "items": { + "type": "string", + "format": "uuid" + }, + "example": [ + "bd0a38f3-1831-440b-a8dd-2c702e2325ab" + ] + }, + "translation_memory_ids": { + "description": "The IDs of the translation memories to link. At most one translation memory per source\nlanguage. Defaults to an empty list.", + "type": "array", + "items": { + "type": "string", + "format": "uuid" + }, + "example": [ + "a74d88fb-ed2a-4943-a664-a4512398b994" + ] + }, + "glossary_priority_order_enabled": { + "description": "Whether the order of `glossary_ids` sets priority: when two linked glossaries define the\nsame source term, the one listed first wins. When `false`, the order has no effect.\nDefaults to `false`.", + "type": "boolean", + "default": false, + "example": true } } }, - "example": { - "name": "My style rules", - "language": "de", - "configured_rules": { - "style_and_tone": { - "abbreviations": "use_abbreviations_and_symbols", - "short_vs_long_words": "use_short_words" - }, - "punctuation": { - "apostrophe": "use_curly_apostrophes" + "examples": { + "MetadataOnly": { + "summary": "Metadata only", + "value": { + "name": "Marketing, Japanese" } }, - "custom_instructions": [ - { - "label": "Currency custom instruction", - "prompt": "Have currency symbols before the numerical value (e.g. $100, €100)", - "source_language": "en" + "FullyConfigured": { + "summary": "Fully configured", + "value": { + "name": "Legal, German", + "description": "Contract wording for the German market.", + "industry": "Legal", + "glossary_ids": [ + "4d0a2e1c-6b93-4f7a-8d15-2c6e9a3b7f81" + ], + "style_rule_ids": [ + "bd0a38f3-1831-440b-a8dd-2c702e2325ab" + ], + "translation_memory_ids": [ + "a74d88fb-ed2a-4943-a664-a4512398b994" + ], + "glossary_priority_order_enabled": true } - ] + } } } } }, "responses": { "201": { - "description": "Style rule list created successfully", + "description": "Returns the created style profile.", "headers": { "X-Trace-ID": { "$ref": "#/components/headers/X-Trace-ID" @@ -5335,25 +5417,85 @@ "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/StyleRuleList" + "$ref": "#/components/schemas/StyleProfile" + }, + "examples": { + "Basic": { + "value": { + "style_profile_id": "3f1c9d0e-7a24-4b58-9c31-8f0e5d2a1b47", + "name": "Legal, German", + "description": "Contract wording for the German market.", + "industry": "Legal", + "glossary_ids": [ + "4d0a2e1c-6b93-4f7a-8d15-2c6e9a3b7f81" + ], + "style_rule_ids": [ + "bd0a38f3-1831-440b-a8dd-2c702e2325ab" + ], + "translation_memory_ids": [ + "a74d88fb-ed2a-4943-a664-a4512398b994" + ], + "glossary_priority_order_enabled": true, + "creation_time": "2026-04-01T16:34:25.223Z", + "updated_time": "2026-04-01T16:34:25.223Z" + } + } } } } }, "400": { - "$ref": "#/components/responses/BadRequest" + "description": "The request was rejected and no style profile was created. This is returned for a malformed\nrequest body, for a missing or empty `name`, for a value that is longer than the field allows,\nand for a component ID that is not a valid UUID or that names a component your account cannot\naccess. The message names the list that contains the bad ID.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + }, + "examples": { + "UnusableComponentId": { + "summary": "Unusable component ID", + "value": { + "message": "Bad request. Reason: One or more glossary ids do not exist or are not accessible. Check 'glossary_ids'." + } + }, + "EmptyName": { + "summary": "Empty name", + "value": { + "message": "Bad request. Reason: The Name field is required." + } + } + } + } + } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { - "$ref": "#/components/responses/ForbiddenScoped" + "description": "Authorization failed. Please supply a valid `DeepL-Auth-Key` via the `Authorization` header.\nThis error is also returned when the API key is scoped but does not include the\n`style_profiles:write` scope, and when your plan does not include creating style profiles.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "456": { - "$ref": "#/components/responses/QuotaExceeded" + "description": "You have reached the maximum number of style profiles for your account. Delete a style profile\nbefore creating another one.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + }, + "example": { + "message": "Quota exceeded" + } + } + } }, "500": { "$ref": "#/components/responses/InternalServerError" @@ -5369,24 +5511,28 @@ ] } }, - "/v3/style_rules/{style_id}": { + "/v3/style_profiles/{style_profile_id}": { "get": { - "summary": "Get a style rule list", - "operationId": "getStyleRuleList", + "tags": [ + "ManageStyleProfiles" + ], + "summary": "Retrieve a style profile", + "operationId": "getStyleProfile", + "description": "Retrieve a single style profile by its ID, including the components it links and its timestamps.\n\nRequires an API key with the `style_profiles:read` scope.", "parameters": [ { - "name": "style_id", + "name": "style_profile_id", "in": "path", "required": true, "schema": { - "type": "string" + "$ref": "#/components/schemas/StyleProfileId" }, - "description": "The ID of the style rule list" + "description": "The ID of the style profile to retrieve." } ], "responses": { "200": { - "description": "Style rule list details", + "description": "Returns the style profile.", "headers": { "X-Trace-ID": { "$ref": "#/components/headers/X-Trace-ID" @@ -5395,7 +5541,29 @@ "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/StyleRuleList" + "$ref": "#/components/schemas/StyleProfile" + }, + "examples": { + "Basic": { + "value": { + "style_profile_id": "3f1c9d0e-7a24-4b58-9c31-8f0e5d2a1b47", + "name": "Legal, German", + "description": "Contract wording for the German market.", + "industry": "Legal", + "glossary_ids": [ + "4d0a2e1c-6b93-4f7a-8d15-2c6e9a3b7f81" + ], + "style_rule_ids": [ + "bd0a38f3-1831-440b-a8dd-2c702e2325ab" + ], + "translation_memory_ids": [ + "a74d88fb-ed2a-4943-a664-a4512398b994" + ], + "glossary_priority_order_enabled": true, + "creation_time": "2026-04-01T16:34:25.223Z", + "updated_time": "2026-08-06T09:12:44.108Z" + } + } } } } @@ -5410,7 +5578,14 @@ "$ref": "#/components/responses/ForbiddenScoped" }, "404": { - "$ref": "#/components/responses/NotFound" + "description": "The style profile could not be found. This is also returned for a style profile your account\ncannot access.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } }, "429": { "$ref": "#/components/responses/TooManyRequests" @@ -5429,17 +5604,21 @@ ] }, "patch": { - "summary": "Update a style rule list's name", - "operationId": "updateStyleRuleList", + "tags": [ + "ManageStyleProfiles" + ], + "summary": "Update a style profile", + "operationId": "updateStyleProfile", + "description": "Update a style profile you own or that was shared with you for editing. Fields you leave out of the\nrequest body are not changed.\n\nA component list you send replaces the linked list in full. To add a glossary to a style profile\nthat already links two, send all three IDs. To unlink all components in a list, send an empty\nlist.\n\nRequires an API key with the `style_profiles:write` scope.", "parameters": [ { - "name": "style_id", + "name": "style_profile_id", "in": "path", "required": true, "schema": { - "type": "string" + "$ref": "#/components/schemas/StyleProfileId" }, - "description": "The ID of the style rule list" + "description": "The ID of the style profile to update." } ], "requestBody": { @@ -5450,7 +5629,80 @@ "type": "object", "properties": { "name": { - "$ref": "#/components/schemas/StyleRuleName" + "description": "A new name for the style profile. At most 255 characters. An empty string is rejected\nwith `400 Bad Request`.", + "type": "string", + "example": "Legal, German (2026)" + }, + "description": { + "description": "A new description for the style profile. At most 1000 characters. Send an empty string\nto clear it.", + "type": "string", + "example": "Contract wording for the German market, 2026 revision." + }, + "industry": { + "description": "A new industry for the style profile. At most 255 characters. Send an empty string to\nclear it.", + "type": "string", + "example": "Legal" + }, + "glossary_ids": { + "description": "The IDs of the glossaries to link, highest priority first. The order only takes effect\nwith `glossary_priority_order_enabled`. Replaces the linked glossaries in full. Send an\nempty list to unlink all of them.", + "type": "array", + "items": { + "type": "string", + "format": "uuid" + }, + "example": [ + "4d0a2e1c-6b93-4f7a-8d15-2c6e9a3b7f81" + ] + }, + "style_rule_ids": { + "description": "The IDs of the style rule lists to link. At most one style rule list per target\nlanguage. Replaces the linked style rule lists in full. Send an empty list to unlink\nall of them.", + "type": "array", + "items": { + "type": "string", + "format": "uuid" + }, + "example": [ + "bd0a38f3-1831-440b-a8dd-2c702e2325ab" + ] + }, + "translation_memory_ids": { + "description": "The IDs of the translation memories to link. At most one translation memory per source\nlanguage. Replaces the linked translation memories in full. Send an empty list to\nunlink all of them.", + "type": "array", + "items": { + "type": "string", + "format": "uuid" + }, + "example": [ + "a74d88fb-ed2a-4943-a664-a4512398b994" + ] + }, + "glossary_priority_order_enabled": { + "description": "Whether the order of `glossary_ids` sets priority: when two linked glossaries define the\nsame source term, the one listed first wins. When `false`, the order has no effect.", + "type": "boolean", + "example": true + } + } + }, + "examples": { + "RenameOnly": { + "summary": "Rename only", + "value": { + "name": "Legal, German (2026)" + } + }, + "ClearTheDescription": { + "summary": "Clear the description", + "value": { + "description": "" + } + }, + "ReplaceTheLinkedGlossaries": { + "summary": "Replace the linked glossaries", + "value": { + "glossary_ids": [ + "4d0a2e1c-6b93-4f7a-8d15-2c6e9a3b7f81", + "7b2f6d84-3c15-4e90-8a72-d5e1490bc637" + ] } } } @@ -5459,7 +5711,459 @@ }, "responses": { "200": { - "description": "Style rule list updated successfully", + "description": "Returns the updated style profile.", + "headers": { + "X-Trace-ID": { + "$ref": "#/components/headers/X-Trace-ID" + } + }, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/StyleProfile" + }, + "examples": { + "Basic": { + "value": { + "style_profile_id": "3f1c9d0e-7a24-4b58-9c31-8f0e5d2a1b47", + "name": "Legal, German (2026)", + "description": "Contract wording for the German market.", + "industry": "Legal", + "glossary_ids": [ + "4d0a2e1c-6b93-4f7a-8d15-2c6e9a3b7f81", + "7b2f6d84-3c15-4e90-8a72-d5e1490bc637" + ], + "style_rule_ids": [ + "bd0a38f3-1831-440b-a8dd-2c702e2325ab" + ], + "translation_memory_ids": [ + "a74d88fb-ed2a-4943-a664-a4512398b994" + ], + "glossary_priority_order_enabled": true, + "creation_time": "2026-04-01T16:34:25.223Z", + "updated_time": "2026-08-20T13:47:51.902Z" + } + } + } + } + } + }, + "400": { + "description": "The request was rejected and the style profile was not changed. This is returned for a\nmalformed request body, for an empty `name`, for a value that is longer than the field allows,\nand for a component ID that is not a valid UUID or that names a component your account cannot\naccess. The message names the list that contains the bad ID.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + }, + "examples": { + "UnusableComponentId": { + "summary": "Unusable component ID", + "value": { + "message": "Bad request. Reason: One or more translation memory ids do not exist or are not accessible. Check 'translation_memory_ids'." + } + }, + "EmptyName": { + "summary": "Empty name", + "value": { + "message": "Bad request. Reason: The field Name must be a string or array type with a minimum length of '1'." + } + } + } + } + } + }, + "401": { + "$ref": "#/components/responses/Unauthorized" + }, + "403": { + "$ref": "#/components/responses/ForbiddenScoped" + }, + "404": { + "description": "The style profile could not be found. This is also returned for a style profile your account\ncan view but not edit.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "429": { + "$ref": "#/components/responses/TooManyRequests" + }, + "500": { + "$ref": "#/components/responses/InternalServerError" + }, + "503": { + "$ref": "#/components/responses/ServiceUnavailable" + } + }, + "security": [ + { + "auth_header": [] + } + ] + }, + "delete": { + "tags": [ + "ManageStyleProfiles" + ], + "summary": "Delete a style profile", + "operationId": "deleteStyleProfile", + "description": "Delete a style profile. Only the account that owns a style profile can delete it. A style profile\nthat was shared with your account returns `404 Not Found`.\n\nThe glossaries, style rule lists and translation memories the style profile links are not deleted.\nTranslation requests that pass the deleted `style_profile_id` fail after this call, so update your\nintegration before deleting.\n\nRequires an API key with the `style_profiles:write` scope.", + "parameters": [ + { + "name": "style_profile_id", + "in": "path", + "required": true, + "schema": { + "$ref": "#/components/schemas/StyleProfileId" + }, + "description": "The ID of the style profile to delete." + } + ], + "responses": { + "204": { + "description": "The style profile was deleted. The response has no body.", + "headers": { + "X-Trace-ID": { + "$ref": "#/components/headers/X-Trace-ID" + } + } + }, + "400": { + "$ref": "#/components/responses/BadRequest" + }, + "401": { + "$ref": "#/components/responses/Unauthorized" + }, + "403": { + "$ref": "#/components/responses/ForbiddenScoped" + }, + "404": { + "description": "The style profile could not be found. This is also returned for a style profile that was\nshared with your account, because only the owner can delete it.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "429": { + "$ref": "#/components/responses/TooManyRequests" + }, + "500": { + "$ref": "#/components/responses/InternalServerError" + }, + "503": { + "$ref": "#/components/responses/ServiceUnavailable" + } + }, + "security": [ + { + "auth_header": [] + } + ] + } + }, + "/v3/style_rules": { + "get": { + "summary": "Retrieve style rule lists", + "operationId": "getStyleRuleLists", + "parameters": [ + { + "name": "page", + "in": "query", + "schema": { + "type": "integer", + "default": 0 + }, + "description": "The index of the first page to return. Use with `page_size` to get the next page of rule lists" + }, + { + "name": "page_size", + "in": "query", + "schema": { + "type": "integer", + "default": 10, + "minimum": 1, + "maximum": 25 + }, + "description": "The maximum number of style rule lists to return." + }, + { + "name": "detailed", + "in": "query", + "schema": { + "type": "boolean", + "default": false + }, + "description": "Determines if the rule list's `configured_rules` and `custom_instructions` should be included in the response body." + } + ], + "responses": { + "200": { + "description": "JSON object containing the style rule lists.", + "headers": { + "X-Trace-ID": { + "$ref": "#/components/headers/X-Trace-ID" + } + }, + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "style_rules": { + "type": "array", + "items": { + "$ref": "#/components/schemas/StyleRuleList" + } + } + } + } + } + } + }, + "400": { + "$ref": "#/components/responses/BadRequest" + }, + "401": { + "$ref": "#/components/responses/Unauthorized" + }, + "403": { + "$ref": "#/components/responses/ForbiddenScoped" + }, + "429": { + "$ref": "#/components/responses/TooManyRequests" + }, + "500": { + "$ref": "#/components/responses/InternalServerError" + }, + "503": { + "$ref": "#/components/responses/ServiceUnavailable" + } + }, + "security": [ + { + "auth_header": [] + } + ] + }, + "post": { + "summary": "Create a style rule list", + "operationId": "createStyleRuleList", + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "name", + "language" + ], + "properties": { + "name": { + "$ref": "#/components/schemas/StyleRuleName", + "x-default": "My style rules" + }, + "language": { + "$ref": "#/components/schemas/StyleRuleLanguage", + "x-default": "de" + }, + "configured_rules": { + "$ref": "#/components/schemas/ConfiguredRules" + }, + "custom_instructions": { + "type": "array", + "description": "Array of custom instruction objects", + "maxItems": 200, + "items": { + "type": "object", + "required": [ + "label", + "prompt" + ], + "properties": { + "label": { + "type": "string", + "description": "Label for the custom instruction" + }, + "prompt": { + "type": "string", + "description": "Instruction text", + "maxLength": 300 + }, + "source_language": { + "type": "string", + "description": "Optional source language code" + } + } + } + } + } + }, + "example": { + "name": "My style rules", + "language": "de", + "configured_rules": { + "style_and_tone": { + "abbreviations": "use_abbreviations_and_symbols", + "short_vs_long_words": "use_short_words" + }, + "punctuation": { + "apostrophe": "use_curly_apostrophes" + } + }, + "custom_instructions": [ + { + "label": "Currency custom instruction", + "prompt": "Have currency symbols before the numerical value (e.g. $100, €100)", + "source_language": "en" + } + ] + } + } + } + }, + "responses": { + "201": { + "description": "Style rule list created successfully", + "headers": { + "X-Trace-ID": { + "$ref": "#/components/headers/X-Trace-ID" + } + }, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/StyleRuleList" + } + } + } + }, + "400": { + "$ref": "#/components/responses/BadRequest" + }, + "401": { + "$ref": "#/components/responses/Unauthorized" + }, + "403": { + "$ref": "#/components/responses/ForbiddenScoped" + }, + "429": { + "$ref": "#/components/responses/TooManyRequests" + }, + "456": { + "$ref": "#/components/responses/QuotaExceeded" + }, + "500": { + "$ref": "#/components/responses/InternalServerError" + }, + "503": { + "$ref": "#/components/responses/ServiceUnavailable" + } + }, + "security": [ + { + "auth_header": [] + } + ] + } + }, + "/v3/style_rules/{style_id}": { + "get": { + "summary": "Get a style rule list", + "operationId": "getStyleRuleList", + "parameters": [ + { + "name": "style_id", + "in": "path", + "required": true, + "schema": { + "type": "string" + }, + "description": "The ID of the style rule list" + } + ], + "responses": { + "200": { + "description": "Style rule list details", + "headers": { + "X-Trace-ID": { + "$ref": "#/components/headers/X-Trace-ID" + } + }, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/StyleRuleList" + } + } + } + }, + "400": { + "$ref": "#/components/responses/BadRequest" + }, + "401": { + "$ref": "#/components/responses/Unauthorized" + }, + "403": { + "$ref": "#/components/responses/ForbiddenScoped" + }, + "404": { + "$ref": "#/components/responses/NotFound" + }, + "429": { + "$ref": "#/components/responses/TooManyRequests" + }, + "500": { + "$ref": "#/components/responses/InternalServerError" + }, + "503": { + "$ref": "#/components/responses/ServiceUnavailable" + } + }, + "security": [ + { + "auth_header": [] + } + ] + }, + "patch": { + "summary": "Update a style rule list's name", + "operationId": "updateStyleRuleList", + "parameters": [ + { + "name": "style_id", + "in": "path", + "required": true, + "schema": { + "type": "string" + }, + "description": "The ID of the style rule list" + } + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "name": { + "$ref": "#/components/schemas/StyleRuleName" + } + } + } + } + } + }, + "responses": { + "200": { + "description": "Style rule list updated successfully", "headers": { "X-Trace-ID": { "$ref": "#/components/headers/X-Trace-ID" @@ -8758,6 +9462,95 @@ } } }, + "StyleProfile": { + "type": "object", + "required": [ + "style_profile_id", + "name", + "glossary_ids", + "style_rule_ids", + "translation_memory_ids", + "glossary_priority_order_enabled", + "creation_time", + "updated_time" + ], + "properties": { + "style_profile_id": { + "$ref": "#/components/schemas/StyleProfileId" + }, + "name": { + "description": "Name associated with the style profile. At most 255 characters.", + "type": "string", + "example": "Legal, German" + }, + "description": { + "description": "Free-text description of the style profile. At most 1000 characters. Omitted from the response\nwhen the style profile has no description.", + "type": "string", + "example": "Contract wording for the German market." + }, + "industry": { + "description": "The industry the style profile is written for. At most 255 characters. Omitted from the response\nwhen the style profile has no industry.", + "type": "string", + "example": "Legal" + }, + "glossary_ids": { + "description": "The IDs of the glossaries linked to the style profile, highest priority first. The order only\ntakes effect with `glossary_priority_order_enabled`.", + "type": "array", + "items": { + "type": "string", + "format": "uuid" + }, + "example": [ + "4d0a2e1c-6b93-4f7a-8d15-2c6e9a3b7f81" + ] + }, + "style_rule_ids": { + "description": "The IDs of the style rule lists linked to the style profile. A style profile links at most one\nstyle rule list per target language.", + "type": "array", + "items": { + "type": "string", + "format": "uuid" + }, + "example": [ + "bd0a38f3-1831-440b-a8dd-2c702e2325ab" + ] + }, + "translation_memory_ids": { + "description": "The IDs of the translation memories linked to the style profile. A style profile links at most\none translation memory per source language.", + "type": "array", + "items": { + "type": "string", + "format": "uuid" + }, + "example": [ + "a74d88fb-ed2a-4943-a664-a4512398b994" + ] + }, + "glossary_priority_order_enabled": { + "description": "Whether the order of `glossary_ids` sets priority: when two linked glossaries define the same\nsource term, the one listed first wins. When `false`, the order has no effect.", + "type": "boolean", + "example": true + }, + "creation_time": { + "description": "The creation time of the style profile in the ISO 8601-1:2019 format (e.g.: `2021-08-03T14:16:18.329Z`).", + "type": "string", + "format": "date-time", + "example": "2026-04-01T16:34:25.223Z" + }, + "updated_time": { + "description": "The time of the last update to the style profile in the ISO 8601-1:2019 format (e.g.: `2021-08-03T14:16:18.329Z`).", + "type": "string", + "format": "date-time", + "example": "2026-08-06T09:12:44.108Z" + } + } + }, + "StyleProfileId": { + "type": "string", + "format": "uuid", + "description": "A unique ID assigned to a style profile.", + "example": "3f1c9d0e-7a24-4b58-9c31-8f0e5d2a1b47" + }, "StyleRuleList": { "type": "object", "required": [ diff --git a/api-reference/openapi.yaml b/api-reference/openapi.yaml index 248ca0e0..fc0587ff 100644 --- a/api-reference/openapi.yaml +++ b/api-reference/openapi.yaml @@ -88,6 +88,19 @@ tags: If you encounter issues, please let us know at support@DeepL.com. Currently you can create glossaries with any of the languages DeepL supports (with the exception of Thai). +- name: ManageStyleProfiles + description: |- + The style profile endpoints allow you to create, inspect, edit and delete style profiles. A style + profile bundles glossaries, style rule lists and translation memories under one ID. Pass its + `style_profile_id` in a translation request instead of the individual customization parameters. + + Every component list is optional, and you can link components later with an update. A style + profile can reference at most one style rule list per target language and at most one translation + memory per source language. With `glossary_priority_order_enabled`, the order of the glossary IDs + decides which glossary wins when two of them define the same source term. + + Deleting a style profile does not delete the glossaries, style rule lists and translation memories it + links. Deleting one of those components removes it from every style profile that links it. - name: MetaInformation description: Information about API usage and value ranges - name: TranslationMemories @@ -646,6 +659,22 @@ paths: items: 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, + 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. + + 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`. + type: string + format: uuid + example: 3f1c9d0e-7a24-4b58-9c31-8f0e5d2a1b47 tag_handling: $ref: '#/components/schemas/TagHandlingOption' tag_handling_version: @@ -733,6 +762,22 @@ 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/list-all-style-profiles): its glossaries, + 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. + + 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`. + type: string + format: uuid + example: 3f1c9d0e-7a24-4b58-9c31-8f0e5d2a1b47 tag_handling: $ref: '#/components/schemas/TagHandlingOption' outline_detection: @@ -956,6 +1001,21 @@ 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/list-all-style-profiles): its glossaries, + style rule lists and translation memories through one ID. The profile is applied once the + document's source language is known: the glossaries with a dictionary for the language pair, the + 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`. + 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 + format: uuid + example: 3f1c9d0e-7a24-4b58-9c31-8f0e5d2a1b47 enable_watermark: description: |- When `true`, adds a "Translated by DeepL" watermark to the translated document. @@ -3660,6 +3720,538 @@ paths: $ref: '#/components/responses/ServiceUnavailable' security: - auth_header: [] + /v3/style_profiles: + get: + tags: + - ManageStyleProfiles + summary: List style profiles + operationId: listStyleProfiles + description: |- + Retrieve a list of style profiles available to the authenticated account, newest first. + + The list includes style profiles that have been shared with the account. + + Requires an API key with the `style_profiles:read` scope. + parameters: + - name: page + in: query + schema: + type: integer + default: 0 + description: The index of the first page to return. Use with `page_size` to get the next page of style profiles. + - name: page_size + in: query + schema: + type: integer + default: 10 + description: The maximum number of style profiles to return. Values above 100 are reduced to 100. + responses: + 200: + description: Returns a list of style profiles. + headers: + X-Trace-ID: + $ref: '#/components/headers/X-Trace-ID' + content: + application/json: + schema: + type: object + properties: + style_profiles: + type: array + items: + $ref: '#/components/schemas/StyleProfile' + total_count: + type: integer + description: The total number of style profiles available to the account. + example: 2 + examples: + Basic: + value: + style_profiles: + - style_profile_id: 3f1c9d0e-7a24-4b58-9c31-8f0e5d2a1b47 + name: Legal, German + description: Contract wording for the German market. + industry: Legal + glossary_ids: + - 4d0a2e1c-6b93-4f7a-8d15-2c6e9a3b7f81 + style_rule_ids: + - bd0a38f3-1831-440b-a8dd-2c702e2325ab + translation_memory_ids: + - a74d88fb-ed2a-4943-a664-a4512398b994 + glossary_priority_order_enabled: true + creation_time: '2026-04-01T16:34:25.223Z' + updated_time: '2026-08-06T09:12:44.108Z' + - style_profile_id: c58e2a71-90b4-4d6f-a2e3-71d5c8b4f902 + name: Marketing, Japanese + glossary_ids: [] + style_rule_ids: [] + translation_memory_ids: [] + glossary_priority_order_enabled: false + creation_time: '2026-07-14T11:02:09.640Z' + updated_time: '2026-07-14T11:02:09.640Z' + total_count: 2 + 400: + $ref: '#/components/responses/BadRequest' + 401: + $ref: '#/components/responses/Unauthorized' + 403: + $ref: '#/components/responses/ForbiddenScoped' + 429: + $ref: '#/components/responses/TooManyRequests' + 500: + $ref: '#/components/responses/InternalServerError' + 503: + $ref: '#/components/responses/ServiceUnavailable' + security: + - auth_header: [] + post: + tags: + - ManageStyleProfiles + summary: Create a style profile + operationId: createStyleProfile + description: |- + Create a style profile. Only `name` is required. + + If any of the component IDs cannot be used, the request fails and no style profile is created. + + Requires an API key with the `style_profiles:write` scope. + requestBody: + required: true + content: + application/json: + schema: + type: object + required: + - name + properties: + name: + description: |- + Name for the style profile. At most 255 characters. An empty name is rejected with + `400 Bad Request`. + type: string + example: Legal, German + description: + description: |- + Free-text description of the style profile. At most 1000 characters. Omit it to create + the style profile without a description. + type: string + example: Contract wording for the German market. + industry: + description: |- + The industry the style profile is written for. At most 255 characters. Omit it to create + the style profile without an industry. + type: string + example: Legal + glossary_ids: + description: |- + The IDs of the glossaries to link, highest priority first. The order only takes effect + with `glossary_priority_order_enabled`. Defaults to an empty list. + type: array + items: + type: string + format: uuid + example: + - 4d0a2e1c-6b93-4f7a-8d15-2c6e9a3b7f81 + style_rule_ids: + description: |- + The IDs of the style rule lists to link. At most one style rule list per target + language. Defaults to an empty list. + type: array + items: + type: string + format: uuid + example: + - bd0a38f3-1831-440b-a8dd-2c702e2325ab + translation_memory_ids: + description: |- + The IDs of the translation memories to link. At most one translation memory per source + language. Defaults to an empty list. + type: array + items: + type: string + format: uuid + example: + - a74d88fb-ed2a-4943-a664-a4512398b994 + glossary_priority_order_enabled: + description: |- + Whether the order of `glossary_ids` sets priority: when two linked glossaries define the + same source term, the one listed first wins. When `false`, the order has no effect. + Defaults to `false`. + type: boolean + default: false + example: true + examples: + MetadataOnly: + summary: Metadata only + value: + name: Marketing, Japanese + FullyConfigured: + summary: Fully configured + value: + name: Legal, German + description: Contract wording for the German market. + industry: Legal + glossary_ids: + - 4d0a2e1c-6b93-4f7a-8d15-2c6e9a3b7f81 + style_rule_ids: + - bd0a38f3-1831-440b-a8dd-2c702e2325ab + translation_memory_ids: + - a74d88fb-ed2a-4943-a664-a4512398b994 + glossary_priority_order_enabled: true + responses: + 201: + description: Returns the created style profile. + headers: + X-Trace-ID: + $ref: '#/components/headers/X-Trace-ID' + content: + application/json: + schema: + $ref: '#/components/schemas/StyleProfile' + examples: + Basic: + value: + style_profile_id: 3f1c9d0e-7a24-4b58-9c31-8f0e5d2a1b47 + name: Legal, German + description: Contract wording for the German market. + industry: Legal + glossary_ids: + - 4d0a2e1c-6b93-4f7a-8d15-2c6e9a3b7f81 + style_rule_ids: + - bd0a38f3-1831-440b-a8dd-2c702e2325ab + translation_memory_ids: + - a74d88fb-ed2a-4943-a664-a4512398b994 + glossary_priority_order_enabled: true + creation_time: '2026-04-01T16:34:25.223Z' + updated_time: '2026-04-01T16:34:25.223Z' + 400: + description: |- + The request was rejected and no style profile was created. This is returned for a malformed + request body, for a missing or empty `name`, for a value that is longer than the field allows, + and for a component ID that is not a valid UUID or that names a component your account cannot + access. The message names the list that contains the bad ID. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + examples: + UnusableComponentId: + summary: Unusable component ID + value: + message: "Bad request. Reason: One or more glossary ids do not exist or are not accessible. Check 'glossary_ids'." + EmptyName: + summary: Empty name + value: + message: 'Bad request. Reason: The Name field is required.' + 401: + $ref: '#/components/responses/Unauthorized' + 403: + description: |- + Authorization failed. Please supply a valid `DeepL-Auth-Key` via the `Authorization` header. + This error is also returned when the API key is scoped but does not include the + `style_profiles:write` scope, and when your plan does not include creating style profiles. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + 429: + $ref: '#/components/responses/TooManyRequests' + 456: + description: |- + You have reached the maximum number of style profiles for your account. Delete a style profile + before creating another one. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + example: + message: Quota exceeded + 500: + $ref: '#/components/responses/InternalServerError' + 503: + $ref: '#/components/responses/ServiceUnavailable' + security: + - auth_header: [] + /v3/style_profiles/{style_profile_id}: + get: + tags: + - ManageStyleProfiles + summary: Retrieve a style profile + operationId: getStyleProfile + description: |- + Retrieve a single style profile by its ID, including the components it links and its timestamps. + + Requires an API key with the `style_profiles:read` scope. + parameters: + - name: style_profile_id + in: path + required: true + schema: + $ref: '#/components/schemas/StyleProfileId' + description: The ID of the style profile to retrieve. + responses: + 200: + description: Returns the style profile. + headers: + X-Trace-ID: + $ref: '#/components/headers/X-Trace-ID' + content: + application/json: + schema: + $ref: '#/components/schemas/StyleProfile' + examples: + Basic: + value: + style_profile_id: 3f1c9d0e-7a24-4b58-9c31-8f0e5d2a1b47 + name: Legal, German + description: Contract wording for the German market. + industry: Legal + glossary_ids: + - 4d0a2e1c-6b93-4f7a-8d15-2c6e9a3b7f81 + style_rule_ids: + - bd0a38f3-1831-440b-a8dd-2c702e2325ab + translation_memory_ids: + - a74d88fb-ed2a-4943-a664-a4512398b994 + glossary_priority_order_enabled: true + creation_time: '2026-04-01T16:34:25.223Z' + updated_time: '2026-08-06T09:12:44.108Z' + 400: + $ref: '#/components/responses/BadRequest' + 401: + $ref: '#/components/responses/Unauthorized' + 403: + $ref: '#/components/responses/ForbiddenScoped' + 404: + description: |- + The style profile could not be found. This is also returned for a style profile your account + cannot access. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + 429: + $ref: '#/components/responses/TooManyRequests' + 500: + $ref: '#/components/responses/InternalServerError' + 503: + $ref: '#/components/responses/ServiceUnavailable' + security: + - auth_header: [] + patch: + tags: + - ManageStyleProfiles + summary: Update a style profile + operationId: updateStyleProfile + description: |- + Update a style profile you own or that was shared with you for editing. Fields you leave out of the + request body are not changed. + + A component list you send replaces the linked list in full. To add a glossary to a style profile + that already links two, send all three IDs. To unlink all components in a list, send an empty + list. + + Requires an API key with the `style_profiles:write` scope. + parameters: + - name: style_profile_id + in: path + required: true + schema: + $ref: '#/components/schemas/StyleProfileId' + description: The ID of the style profile to update. + requestBody: + required: true + content: + application/json: + schema: + type: object + properties: + name: + description: |- + A new name for the style profile. At most 255 characters. An empty string is rejected + with `400 Bad Request`. + type: string + example: Legal, German (2026) + description: + description: |- + A new description for the style profile. At most 1000 characters. Send an empty string + to clear it. + type: string + example: Contract wording for the German market, 2026 revision. + industry: + description: |- + A new industry for the style profile. At most 255 characters. Send an empty string to + clear it. + type: string + example: Legal + glossary_ids: + description: |- + The IDs of the glossaries to link, highest priority first. The order only takes effect + with `glossary_priority_order_enabled`. Replaces the linked glossaries in full. Send an + empty list to unlink all of them. + type: array + items: + type: string + format: uuid + example: + - 4d0a2e1c-6b93-4f7a-8d15-2c6e9a3b7f81 + style_rule_ids: + description: |- + The IDs of the style rule lists to link. At most one style rule list per target + language. Replaces the linked style rule lists in full. Send an empty list to unlink + all of them. + type: array + items: + type: string + format: uuid + example: + - bd0a38f3-1831-440b-a8dd-2c702e2325ab + translation_memory_ids: + description: |- + The IDs of the translation memories to link. At most one translation memory per source + language. Replaces the linked translation memories in full. Send an empty list to + unlink all of them. + type: array + items: + type: string + format: uuid + example: + - a74d88fb-ed2a-4943-a664-a4512398b994 + glossary_priority_order_enabled: + description: |- + Whether the order of `glossary_ids` sets priority: when two linked glossaries define the + same source term, the one listed first wins. When `false`, the order has no effect. + type: boolean + example: true + examples: + RenameOnly: + summary: Rename only + value: + name: Legal, German (2026) + ClearTheDescription: + summary: Clear the description + value: + description: '' + ReplaceTheLinkedGlossaries: + summary: Replace the linked glossaries + value: + glossary_ids: + - 4d0a2e1c-6b93-4f7a-8d15-2c6e9a3b7f81 + - 7b2f6d84-3c15-4e90-8a72-d5e1490bc637 + responses: + 200: + description: Returns the updated style profile. + headers: + X-Trace-ID: + $ref: '#/components/headers/X-Trace-ID' + content: + application/json: + schema: + $ref: '#/components/schemas/StyleProfile' + examples: + Basic: + value: + style_profile_id: 3f1c9d0e-7a24-4b58-9c31-8f0e5d2a1b47 + name: Legal, German (2026) + description: Contract wording for the German market. + industry: Legal + glossary_ids: + - 4d0a2e1c-6b93-4f7a-8d15-2c6e9a3b7f81 + - 7b2f6d84-3c15-4e90-8a72-d5e1490bc637 + style_rule_ids: + - bd0a38f3-1831-440b-a8dd-2c702e2325ab + translation_memory_ids: + - a74d88fb-ed2a-4943-a664-a4512398b994 + glossary_priority_order_enabled: true + creation_time: '2026-04-01T16:34:25.223Z' + updated_time: '2026-08-20T13:47:51.902Z' + 400: + description: |- + The request was rejected and the style profile was not changed. This is returned for a + malformed request body, for an empty `name`, for a value that is longer than the field allows, + and for a component ID that is not a valid UUID or that names a component your account cannot + access. The message names the list that contains the bad ID. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + examples: + UnusableComponentId: + summary: Unusable component ID + value: + message: "Bad request. Reason: One or more translation memory ids do not exist or are not accessible. Check 'translation_memory_ids'." + EmptyName: + summary: Empty name + value: + message: "Bad request. Reason: The field Name must be a string or array type with a minimum length of '1'." + 401: + $ref: '#/components/responses/Unauthorized' + 403: + $ref: '#/components/responses/ForbiddenScoped' + 404: + description: |- + The style profile could not be found. This is also returned for a style profile your account + can view but not edit. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + 429: + $ref: '#/components/responses/TooManyRequests' + 500: + $ref: '#/components/responses/InternalServerError' + 503: + $ref: '#/components/responses/ServiceUnavailable' + security: + - auth_header: [] + delete: + tags: + - ManageStyleProfiles + summary: Delete a style profile + operationId: deleteStyleProfile + description: |- + Delete a style profile. Only the account that owns a style profile can delete it. A style profile + that was shared with your account returns `404 Not Found`. + + The glossaries, style rule lists and translation memories the style profile links are not deleted. + Translation requests that pass the deleted `style_profile_id` fail after this call, so update your + integration before deleting. + + Requires an API key with the `style_profiles:write` scope. + parameters: + - name: style_profile_id + in: path + required: true + schema: + $ref: '#/components/schemas/StyleProfileId' + description: The ID of the style profile to delete. + responses: + 204: + description: The style profile was deleted. The response has no body. + headers: + X-Trace-ID: + $ref: '#/components/headers/X-Trace-ID' + 400: + $ref: '#/components/responses/BadRequest' + 401: + $ref: '#/components/responses/Unauthorized' + 403: + $ref: '#/components/responses/ForbiddenScoped' + 404: + description: |- + The style profile could not be found. This is also returned for a style profile that was + shared with your account, because only the owner can delete it. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + 429: + $ref: '#/components/responses/TooManyRequests' + 500: + $ref: '#/components/responses/InternalServerError' + 503: + $ref: '#/components/responses/ServiceUnavailable' + security: + - auth_header: [] /v3/style_rules: get: summary: Retrieve style rule lists @@ -6255,6 +6847,89 @@ components: type: string description: Optional source language of the custom instruction example: "en" + StyleProfile: + type: object + required: + - style_profile_id + - name + - glossary_ids + - style_rule_ids + - translation_memory_ids + - glossary_priority_order_enabled + - creation_time + - updated_time + properties: + style_profile_id: + $ref: '#/components/schemas/StyleProfileId' + name: + description: |- + Name associated with the style profile. At most 255 characters. + type: string + example: Legal, German + description: + description: |- + Free-text description of the style profile. At most 1000 characters. Omitted from the response + when the style profile has no description. + type: string + example: Contract wording for the German market. + industry: + description: |- + The industry the style profile is written for. At most 255 characters. Omitted from the response + when the style profile has no industry. + type: string + example: Legal + glossary_ids: + description: |- + The IDs of the glossaries linked to the style profile, highest priority first. The order only + takes effect with `glossary_priority_order_enabled`. + type: array + items: + type: string + format: uuid + example: + - 4d0a2e1c-6b93-4f7a-8d15-2c6e9a3b7f81 + style_rule_ids: + description: |- + The IDs of the style rule lists linked to the style profile. A style profile links at most one + style rule list per target language. + type: array + items: + type: string + format: uuid + example: + - bd0a38f3-1831-440b-a8dd-2c702e2325ab + translation_memory_ids: + description: |- + The IDs of the translation memories linked to the style profile. A style profile links at most + one translation memory per source language. + type: array + items: + type: string + format: uuid + example: + - a74d88fb-ed2a-4943-a664-a4512398b994 + glossary_priority_order_enabled: + description: |- + Whether the order of `glossary_ids` sets priority: when two linked glossaries define the same + source term, the one listed first wins. When `false`, the order has no effect. + type: boolean + example: true + creation_time: + description: 'The creation time of the style profile in the ISO 8601-1:2019 format (e.g.: `2021-08-03T14:16:18.329Z`).' + type: string + format: date-time + example: '2026-04-01T16:34:25.223Z' + updated_time: + description: 'The time of the last update to the style profile in the ISO 8601-1:2019 format (e.g.: `2021-08-03T14:16:18.329Z`).' + type: string + format: date-time + example: '2026-08-06T09:12:44.108Z' + StyleProfileId: + type: string + format: uuid + description: |- + A unique ID assigned to a style profile. + example: 3f1c9d0e-7a24-4b58-9c31-8f0e5d2a1b47 StyleRuleList: type: object required: diff --git a/api-reference/style-profiles/create-style-profile.mdx b/api-reference/style-profiles/create-style-profile.mdx new file mode 100644 index 00000000..fd484947 --- /dev/null +++ b/api-reference/style-profiles/create-style-profile.mdx @@ -0,0 +1,5 @@ +--- +openapi: post /v3/style_profiles +title: "Create a style profile" +description: "Create a style profile that bundles glossaries, style rule lists and translation memories under one ID." +--- diff --git a/api-reference/style-profiles/delete-style-profile.mdx b/api-reference/style-profiles/delete-style-profile.mdx new file mode 100644 index 00000000..8b9ea345 --- /dev/null +++ b/api-reference/style-profiles/delete-style-profile.mdx @@ -0,0 +1,5 @@ +--- +openapi: delete /v3/style_profiles/{style_profile_id} +title: "Delete a style profile" +description: "Delete a style profile without deleting the components it links." +--- diff --git a/api-reference/style-profiles/get-style-profile.mdx b/api-reference/style-profiles/get-style-profile.mdx new file mode 100644 index 00000000..e9edfe25 --- /dev/null +++ b/api-reference/style-profiles/get-style-profile.mdx @@ -0,0 +1,5 @@ +--- +openapi: get /v3/style_profiles/{style_profile_id} +title: "Retrieve a style profile" +description: "Retrieve a style profile's linked components and metadata by its ID." +--- diff --git a/api-reference/style-profiles/list-all-style-profiles.mdx b/api-reference/style-profiles/list-all-style-profiles.mdx new file mode 100644 index 00000000..231d80f8 --- /dev/null +++ b/api-reference/style-profiles/list-all-style-profiles.mdx @@ -0,0 +1,5 @@ +--- +openapi: get /v3/style_profiles +title: "List style profiles" +description: "Retrieve all style profiles available to your account, including the ones shared with it." +--- diff --git a/api-reference/style-profiles/update-style-profile.mdx b/api-reference/style-profiles/update-style-profile.mdx new file mode 100644 index 00000000..29b2d7f9 --- /dev/null +++ b/api-reference/style-profiles/update-style-profile.mdx @@ -0,0 +1,5 @@ +--- +openapi: patch /v3/style_profiles/{style_profile_id} +title: "Update a style profile" +description: "Update a style profile's name, description, industry or linked components." +--- diff --git a/docs.json b/docs.json index 38559381..d40109f7 100644 --- a/docs.json +++ b/docs.json @@ -185,6 +185,12 @@ "pages": [ "docs/customize/using-translation-memories" ] + }, + { + "group": "Style Profiles", + "pages": [ + "docs/customize/using-style-profiles" + ] } ] }, @@ -278,6 +284,17 @@ ], "drilldown": false }, + { + "group": "Style Profiles", + "pages": [ + "api-reference/style-profiles/list-all-style-profiles", + "api-reference/style-profiles/create-style-profile", + "api-reference/style-profiles/get-style-profile", + "api-reference/style-profiles/update-style-profile", + "api-reference/style-profiles/delete-style-profile" + ], + "drilldown": false + }, { "group": "Style Rules", "pages": [ diff --git a/docs/customize/overview.mdx b/docs/customize/overview.mdx index b1184a2c..6a1c8a95 100644 --- a/docs/customize/overview.mdx +++ b/docs/customize/overview.mdx @@ -16,8 +16,9 @@ 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](/docs/customize/using-style-profiles) | A named bundle of glossaries, style rules, and translation memories | Stored on your account; passed per request via `style_profile_id` instead of 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. +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. A style profile works with both endpoints too, but replaces the individual parameters rather than combining with them. Spoken terms apply to [Voice API](/docs/voice/overview) sessions, where they can be combined with glossaries. Glossaries and style rules are unique to each of DeepL's global data centers and are not shared between them. Clients using [regional endpoints](/docs/getting-started/regional-endpoints) can't access glossaries or style rules created in the UI at this time. diff --git a/docs/customize/using-style-profiles.mdx b/docs/customize/using-style-profiles.mdx new file mode 100644 index 00000000..3aea0e02 --- /dev/null +++ b/docs/customize/using-style-profiles.mdx @@ -0,0 +1,116 @@ +--- +title: "Using Style Profiles" +description: "Bundle glossaries, style rule lists, and translation memories into a style profile and apply them to translations with the style_profile_id parameter." +covers: [Customize] +public: true +--- + +A style profile bundles the customizations you use together, such as the glossary, style rule list, and translation memory for one product or client, under a single ID. Instead of passing `glossary_ids`, `style_id`, and `translation_memory_id` with every request, you pass one `style_profile_id`. When the bundle changes, you update the profile, not your integration. + +A style profile can link: + +- **Glossaries**: any number, optionally with a priority order +- **Style rule lists**: at most one per target language +- **Translation memories**: at most one per source language + +Manage style profiles with the [style profiles endpoints](/api-reference/style-profiles/list-all-style-profiles), as shown below. + +## Create a style profile + +Send `POST /v3/style_profiles` a name and the IDs of the components to link. Only `name` is required, so you can also create an empty profile and link components later. + +```sh Example request +curl -X POST https://api.deepl.com/v3/style_profiles \ + --header "Authorization: DeepL-Auth-Key $API_KEY" \ + --header "Content-Type: application/json" \ + --data '{ + "name": "Legal, German", + "description": "Contract wording for the German market.", + "industry": "Legal", + "glossary_ids": ["4d0a2e1c-6b93-4f7a-8d15-2c6e9a3b7f81"], + "style_rule_ids": ["bd0a38f3-1831-440b-a8dd-2c702e2325ab"], + "translation_memory_ids": ["a74d88fb-ed2a-4943-a664-a4512398b994"] +}' +``` + +```json Example response +{ + "style_profile_id": "3f1c9d0e-7a24-4b58-9c31-8f0e5d2a1b47", + "name": "Legal, German", + "description": "Contract wording for the German market.", + "industry": "Legal", + "glossary_ids": ["4d0a2e1c-6b93-4f7a-8d15-2c6e9a3b7f81"], + "style_rule_ids": ["bd0a38f3-1831-440b-a8dd-2c702e2325ab"], + "translation_memory_ids": ["a74d88fb-ed2a-4943-a664-a4512398b994"], + "glossary_priority_order_enabled": false, + "creation_time": "2026-04-01T16:34:25.223Z", + "updated_time": "2026-04-01T16:34:25.223Z" +} +``` + +If one of the IDs doesn't exist or isn't accessible to your account, the request fails with `400 Bad Request` and no profile is created. The error message names the list that contains the bad ID, for example `Check 'glossary_ids'`. + +The glossaries, style rule lists, and translation memories you link don't have to share a language pair. A profile can hold an English and a Japanese style rule list at the same time, and each one is used only for its own target language. + +## Translate with a style profile + +Pass the `style_profile_id` in a [`/v2/translate`](/api-reference/translate/request-translation) or [`/v2/document`](/api-reference/document/upload-and-translate-a-document) request: + +```sh Example request +curl -X POST https://api.deepl.com/v2/translate \ + --header "Authorization: DeepL-Auth-Key $API_KEY" \ + --header "Content-Type: application/json" \ + --data '{ + "text": ["Der Kunde hat den Vertrag unterschrieben."], + "target_lang": "EN", + "style_profile_id": "3f1c9d0e-7a24-4b58-9c31-8f0e5d2a1b47" +}' +``` + +DeepL picks the components that fit the request once the source language is known: the glossaries with a dictionary for the language pair, the style rule list for the target language, and the translation memory whose source language matches the text. A component that doesn't fit is left out without an error, so the same profile works for every language pair it covers. You don't need to set `source_lang`; language detection works as usual. + + +A style profile replaces the individual customization parameters. A request that combines `style_profile_id` with `glossary_id`, `glossary_ids`, `style_id`, `translation_memory_id`, `translation_memory_threshold`, or `custom_instructions` is rejected with `400 Bad Request`. + + +All `model_type` values are supported. Translation memories linked through a profile use the default matching threshold of 75. + +## Set the glossary priority + +When two linked glossaries define the same source term, enable `glossary_priority_order_enabled` to make the order of `glossary_ids` decide: the first glossary that defines the term wins. Without it, the order has no effect. + +```sh Example request +curl -X PATCH https://api.deepl.com/v3/style_profiles/3f1c9d0e-7a24-4b58-9c31-8f0e5d2a1b47 \ + --header "Authorization: DeepL-Auth-Key $API_KEY" \ + --header "Content-Type: application/json" \ + --data '{ + "glossary_ids": [ + "4d0a2e1c-6b93-4f7a-8d15-2c6e9a3b7f81", + "7b2f6d84-3c15-4e90-8a72-d5e1490bc637" + ], + "glossary_priority_order_enabled": true +}' +``` + +## Update a style profile + +[`PATCH /v3/style_profiles/{style_profile_id}`](/api-reference/style-profiles/update-style-profile) changes only the fields you send. Each component list you send replaces the linked list in full, so to add a glossary to a profile that already links two, send all three IDs. An empty list unlinks every component of that kind: + +```sh Example request +curl -X PATCH https://api.deepl.com/v3/style_profiles/3f1c9d0e-7a24-4b58-9c31-8f0e5d2a1b47 \ + --header "Authorization: DeepL-Auth-Key $API_KEY" \ + --header "Content-Type: application/json" \ + --data '{ + "translation_memory_ids": [] +}' +``` + +You don't need to update a profile when you delete one of its components. A deleted glossary, style rule list, or translation memory is removed from every profile that links it. + +To list or inspect profiles, use [`GET /v3/style_profiles`](/api-reference/style-profiles/list-all-style-profiles) or [`GET /v3/style_profiles/{style_profile_id}`](/api-reference/style-profiles/get-style-profile). [`DELETE /v3/style_profiles/{style_profile_id}`](/api-reference/style-profiles/delete-style-profile) removes the profile but leaves its components in place. Translation requests that still pass the deleted ID fail, so update your integration before deleting. + +## Limits + +- A style profile links at most one style rule list per target language and one translation memory per source language. Sending two for the same language is rejected with `400 Bad Request` +- The number of style profiles per account depends on your plan. Creating one above the limit is rejected with `456` +- `name` and `industry` are limited to 255 characters, `description` to 1000