diff --git a/api-reference/openapi.json b/api-reference/openapi.json index 735d58cf..7a8086df 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 functions allow you to create, inspect, edit and delete style profiles.\nA style profile bundles your other customizations, glossaries, style rule lists, translation memories\nand example documents, behind a single ID, so one `style_profile_id` stands for a whole translation\nconfiguration instead of a list of individual parameters.\n\nEvery component list is optional. A style profile can hold nothing but a name, and you can link\ncomponents to it later with a partial update. Within each list, the order of the IDs is the order in\nwhich the components are applied, and a style profile can reference at most one translation memory per\nsource language.\n\nA style profile can also link one Spoken Terms collection, which is applied when the profile is used\nfor speech rather than text instead of the text-only components. A profile links at most one\ncollection: collections are deliberately small so that transcription stays fast (see\n[Spoken Terms requirements](/docs/customize/spoken-terms-requirements)), and stacking several against\none profile would work against that. Manage collections with the\n[Spoken Terms endpoints](/api-reference/spoken-terms/list-all-spoken-terms).\n\nDeleting a style profile only unlinks its components. The glossaries, style rule lists, translation\nmemories, example documents and Spoken Terms collection themselves are left in place and can be reused\nin another style profile." + }, { "name": "MetaInformation", "description": "Information about API usage and value ranges" @@ -5163,10 +5167,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 covers style profiles the account owns and style profiles that have been shared with it,\nso it can contain profiles the account is not allowed to delete.\n\nRequires an API key with the `style_profiles:read` scope.", "parameters": [ { "name": "page", @@ -5175,32 +5183,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 +5208,58 @@ "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" + ], + "example_document_ids": [ + "9e7b41c2-58da-4a03-b6f1-3c85e0d97a26" + ], + "spoken_terms_id": "def3a26b-3e84-45b3-84ae-0c0aaf3525f7", + "glossary_priority_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": [], + "example_document_ids": [], + "glossary_priority_enabled": false, + "creation_time": "2026-07-14T11:02:09.640Z", + "updated_time": "2026-07-14T11:02:09.640Z" + } + ], + "total_count": 2 } } } @@ -5248,8 +5292,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, so a metadata-only style profile and a fully\nconfigured one are both a single request.\n\nCreation is atomic. If any of the component IDs you pass cannot be used, no style profile is\ncreated and nothing is linked, so you can retry the whole request after fixing the ID rather than\ncleaning up a partly built profile.\n\nRequires an API key with the `style_profiles:write` scope.", "requestBody": { "required": true, "content": { @@ -5257,76 +5305,118 @@ "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, in the order they should be applied. Defaults to an\nempty 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, in the order they should be applied. At\nmost 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, in the order they should be applied. At\nmost one translation memory per source language. Defaults to an empty list.", + "type": "array", + "items": { + "type": "string", + "format": "uuid" + }, + "example": [ + "a74d88fb-ed2a-4943-a664-a4512398b994" + ] + }, + "example_document_ids": { + "description": "The IDs of the example documents to link, in the order they should be applied. A\ndocument must be fully imported before it can be linked. Defaults to an empty list.", + "type": "array", + "items": { + "type": "string", + "format": "uuid" + }, + "example": [ + "9e7b41c2-58da-4a03-b6f1-3c85e0d97a26" + ] + }, + "spoken_terms_id": { + "description": "The ID of the Spoken Terms collection to link, applied when the style profile is used\nfor speech rather than text. A style profile links at most one collection. Omit it to\ncreate the style profile without one. See\n[Improving transcription with Spoken Terms](/docs/customize/improving-transcription-with-spoken-terms).\n\nRequires a plan that includes DeepL Voice. Sending a `spoken_terms_id` on a plan\nwithout it is rejected with `403 Forbidden` and no style profile is created. A value\nthat is not a valid UUID, or that names a collection your account cannot access, is\nrejected with `400 Bad Request` naming the field.", + "type": "string", + "format": "uuid", + "example": "def3a26b-3e84-45b3-84ae-0c0aaf3525f7" + }, + "glossary_priority_enabled": { + "description": "Whether the glossaries linked to this style profile take priority over its other\ncomponents. Defaults 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" + ], + "example_document_ids": [ + "9e7b41c2-58da-4a03-b6f1-3c85e0d97a26" + ], + "spoken_terms_id": "def3a26b-3e84-45b3-84ae-0c0aaf3525f7", + "glossary_priority_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 +5425,86 @@ "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" + ], + "example_document_ids": [ + "9e7b41c2-58da-4a03-b6f1-3c85e0d97a26" + ], + "spoken_terms_id": "def3a26b-3e84-45b3-84ae-0c0aaf3525f7", + "glossary_priority_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 cannot be used. A component ID that is not a valid UUID, or that\nnames a component your account cannot access, is reported per field, so the message names the\nlist, or `spoken_terms_id`, that the bad ID was passed in.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + }, + "examples": { + "UnusableComponentId": { + "summary": "Unusable component ID", + "value": { + "message": "One or more IDs in glossary_ids could not be used" + } + }, + "EmptyName": { + "summary": "Empty name", + "value": { + "message": "name must not be empty" + } + } + } + } + } }, "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, when your plan does not include creating style profiles, and\nwhen the request sends a `spoken_terms_id` but your plan does not include DeepL Voice.", + "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" + } + } + } }, "500": { "$ref": "#/components/responses/InternalServerError" @@ -5369,24 +5520,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 +5550,33 @@ "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" + ], + "example_document_ids": [ + "9e7b41c2-58da-4a03-b6f1-3c85e0d97a26" + ], + "spoken_terms_id": "def3a26b-3e84-45b3-84ae-0c0aaf3525f7", + "glossary_priority_enabled": true, + "creation_time": "2026-04-01T16:34:25.223Z", + "updated_time": "2026-08-06T09:12:44.108Z" + } + } } } } @@ -5410,7 +5591,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 the account\ncannot see, so a `404` does not confirm that the ID is unused.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } }, "429": { "$ref": "#/components/responses/TooManyRequests" @@ -5429,17 +5617,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. Fields you leave out of the request body are left unchanged, so you can\nsend only what you want to change.\n\nEach component list you send replaces that linked set in full rather than adding to it. To add one\nglossary to a profile that already has two, send all three IDs. To unlink every component in a\nlist, send an empty list.\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,39 +5642,602 @@ "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" - } - }, - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/StyleRuleList" - } - } - } - }, - "400": { - "$ref": "#/components/responses/BadRequest" - }, - "401": { - "$ref": "#/components/responses/Unauthorized" - }, - "403": { - "$ref": "#/components/responses/ForbiddenScoped" - }, - "404": { + "description": "A new name for the style profile. At most 255 characters. A style profile always has a\nname, so an empty string is rejected with `400 Bad Request` rather than clearing it.", + "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, in the order they should be applied. Replaces the\nlinked 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, in the order they should be applied. At\nmost one style rule list per target language. Replaces the linked style rule\nlists 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, in the order they should be applied. At\nmost one translation memory per source language. Replaces the linked translation\nmemories in full. Send an empty list to unlink all of them.", + "type": "array", + "items": { + "type": "string", + "format": "uuid" + }, + "example": [ + "a74d88fb-ed2a-4943-a664-a4512398b994" + ] + }, + "example_document_ids": { + "description": "The IDs of the example documents to link, in the order they should be applied. A\ndocument must be fully imported before it can be linked. Replaces the linked example\ndocuments in full. Send an empty list to unlink all of them.", + "type": "array", + "items": { + "type": "string", + "format": "uuid" + }, + "example": [ + "9e7b41c2-58da-4a03-b6f1-3c85e0d97a26" + ] + }, + "spoken_terms_id": { + "description": "The ID of the Spoken Terms collection to link, applied when the style profile is used\nfor speech rather than text. A style profile links at most one collection, so a new ID\nreplaces the current link. Send an empty string to unlink the collection, the same way\nan empty string clears `description` and `industry`.\n\nRequires a plan that includes DeepL Voice. Sending a `spoken_terms_id` on a plan\nwithout it is rejected with `403 Forbidden` and the style profile is not changed. A\nvalue that is not a valid UUID, or that names a collection your account cannot access,\nis rejected with `400 Bad Request` naming the field.", + "type": "string", + "format": "uuid", + "example": "def3a26b-3e84-45b3-84ae-0c0aaf3525f7" + }, + "glossary_priority_enabled": { + "description": "Whether the glossaries linked to this style profile take priority over its other\ncomponents.", + "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" + ] + } + }, + "UnlinkAllExampleDocuments": { + "summary": "Unlink all example documents", + "value": { + "example_document_ids": [] + } + }, + "UnlinkTheSpokenTermsCollection": { + "summary": "Unlink the Spoken Terms collection", + "value": { + "spoken_terms_id": "" + } + } + } + } + } + }, + "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" + ], + "example_document_ids": [], + "spoken_terms_id": "def3a26b-3e84-45b3-84ae-0c0aaf3525f7", + "glossary_priority_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 cannot be used. A component ID that is not a valid UUID, or that\nnames a component your account cannot access, is reported per field, so the message names the\nlist, or `spoken_terms_id`, that the bad ID was passed in.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + }, + "examples": { + "UnusableComponentId": { + "summary": "Unusable component ID", + "value": { + "message": "One or more IDs in example_document_ids could not be used" + } + }, + "EmptyName": { + "summary": "Empty name", + "value": { + "message": "name must not be empty" + } + } + } + } + } + }, + "401": { + "$ref": "#/components/responses/Unauthorized" + }, + "403": { + "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 the request sends a `spoken_terms_id` but your plan\ndoes not include DeepL Voice.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "404": { + "description": "The style profile could not be found. This is also returned for a style profile the account\ncannot see, so a `404` does not confirm that the ID is unused.", + "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, and that you can therefore list and retrieve, returns\n`404 Not Found` on delete, the same status as an ID that does not exist.\n\nDeleting a style profile unlinks its components rather than deleting them. The glossaries, style\nrule lists, translation memories, example documents and Spoken Terms collection it referenced are\nleft in place. Translation requests that pass the deleted `style_profile_id` fail after this call,\nso update your integration 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 the account\ncannot see, and for a style profile the account can see but does not own, so a `404` does not\nconfirm that the ID is unused.", + "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" + } + }, + "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": { @@ -8758,6 +9513,113 @@ } } }, + "StyleProfile": { + "type": "object", + "required": [ + "style_profile_id", + "name", + "glossary_ids", + "style_rule_ids", + "translation_memory_ids", + "example_document_ids", + "glossary_priority_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. A style profile always has a\nname, so it cannot be cleared once it is set.", + "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, in the order they are applied.", + "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, in the order they are applied.", + "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, in the order they are applied.\nA style profile links at most one translation memory per source language.", + "type": "array", + "items": { + "type": "string", + "format": "uuid" + }, + "example": [ + "a74d88fb-ed2a-4943-a664-a4512398b994" + ] + }, + "example_document_ids": { + "description": "The IDs of the example documents linked to the style profile, in the order they are applied.", + "type": "array", + "items": { + "type": "string", + "format": "uuid" + }, + "example": [ + "9e7b41c2-58da-4a03-b6f1-3c85e0d97a26" + ] + }, + "spoken_terms_id": { + "description": "The ID of the Spoken Terms collection linked to the style profile, applied when the profile is\nused for speech rather than text. A style profile links at most one collection. Omitted from\nthe response when no collection is linked. Collections are managed with the\n[Spoken Terms endpoints](/api-reference/spoken-terms/list-all-spoken-terms).", + "type": "string", + "format": "uuid", + "example": "def3a26b-3e84-45b3-84ae-0c0aaf3525f7" + }, + "glossary_priority_enabled": { + "description": "Whether the glossaries linked to the style profile take priority over its other components.", + "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..0d982eca 100644 --- a/api-reference/openapi.yaml +++ b/api-reference/openapi.yaml @@ -88,6 +88,28 @@ 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 functions allow you to create, inspect, edit and delete style profiles. + A style profile bundles your other customizations, glossaries, style rule lists, translation memories + and example documents, behind a single ID, so one `style_profile_id` stands for a whole translation + configuration instead of a list of individual parameters. + + Every component list is optional. A style profile can hold nothing but a name, and you can link + components to it later with a partial update. Within each list, the order of the IDs is the order in + which the components are applied, and a style profile can reference at most one translation memory per + source language. + + A style profile can also link one Spoken Terms collection, which is applied when the profile is used + for speech rather than text instead of the text-only components. A profile links at most one + collection: collections are deliberately small so that transcription stays fast (see + [Spoken Terms requirements](/docs/customize/spoken-terms-requirements)), and stacking several against + one profile would work against that. Manage collections with the + [Spoken Terms endpoints](/api-reference/spoken-terms/list-all-spoken-terms). + + Deleting a style profile only unlinks its components. The glossaries, style rule lists, translation + memories, example documents and Spoken Terms collection themselves are left in place and can be reused + in another style profile. - name: MetaInformation description: Information about API usage and value ranges - name: TranslationMemories @@ -3660,6 +3682,624 @@ 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 covers style profiles the account owns and style profiles that have been shared with it, + so it can contain profiles the account is not allowed to delete. + + 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 + example_document_ids: + - 9e7b41c2-58da-4a03-b6f1-3c85e0d97a26 + spoken_terms_id: def3a26b-3e84-45b3-84ae-0c0aaf3525f7 + glossary_priority_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: [] + example_document_ids: [] + glossary_priority_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, so a metadata-only style profile and a fully + configured one are both a single request. + + Creation is atomic. If any of the component IDs you pass cannot be used, no style profile is + created and nothing is linked, so you can retry the whole request after fixing the ID rather than + cleaning up a partly built profile. + + 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, in the order they should be applied. 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, in the order they should be applied. 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, in the order they should be applied. 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 + example_document_ids: + description: |- + The IDs of the example documents to link, in the order they should be applied. A + document must be fully imported before it can be linked. Defaults to an empty list. + type: array + items: + type: string + format: uuid + example: + - 9e7b41c2-58da-4a03-b6f1-3c85e0d97a26 + spoken_terms_id: + description: |- + The ID of the Spoken Terms collection to link, applied when the style profile is used + for speech rather than text. A style profile links at most one collection. Omit it to + create the style profile without one. See + [Improving transcription with Spoken Terms](/docs/customize/improving-transcription-with-spoken-terms). + + Requires a plan that includes DeepL Voice. Sending a `spoken_terms_id` on a plan + without it is rejected with `403 Forbidden` and no style profile is created. A value + that is not a valid UUID, or that names a collection your account cannot access, is + rejected with `400 Bad Request` naming the field. + type: string + format: uuid + example: def3a26b-3e84-45b3-84ae-0c0aaf3525f7 + glossary_priority_enabled: + description: |- + Whether the glossaries linked to this style profile take priority over its other + components. 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 + example_document_ids: + - 9e7b41c2-58da-4a03-b6f1-3c85e0d97a26 + spoken_terms_id: def3a26b-3e84-45b3-84ae-0c0aaf3525f7 + glossary_priority_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 + example_document_ids: + - 9e7b41c2-58da-4a03-b6f1-3c85e0d97a26 + spoken_terms_id: def3a26b-3e84-45b3-84ae-0c0aaf3525f7 + glossary_priority_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 cannot be used. A component ID that is not a valid UUID, or that + names a component your account cannot access, is reported per field, so the message names the + list, or `spoken_terms_id`, that the bad ID was passed in. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + examples: + UnusableComponentId: + summary: Unusable component ID + value: + message: One or more IDs in glossary_ids could not be used + EmptyName: + summary: Empty name + value: + message: name must not be empty + 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, when your plan does not include creating style profiles, and + when the request sends a `spoken_terms_id` but your plan does not include DeepL Voice. + 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' + 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 + example_document_ids: + - 9e7b41c2-58da-4a03-b6f1-3c85e0d97a26 + spoken_terms_id: def3a26b-3e84-45b3-84ae-0c0aaf3525f7 + glossary_priority_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 the account + cannot see, so a `404` does not confirm that the ID is unused. + 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. Fields you leave out of the request body are left unchanged, so you can + send only what you want to change. + + Each component list you send replaces that linked set in full rather than adding to it. To add one + glossary to a profile that already has two, send all three IDs. To unlink every component 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. A style profile always has a + name, so an empty string is rejected with `400 Bad Request` rather than clearing it. + 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, in the order they should be applied. 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, in the order they should be applied. 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, in the order they should be applied. 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 + example_document_ids: + description: |- + The IDs of the example documents to link, in the order they should be applied. A + document must be fully imported before it can be linked. Replaces the linked example + documents in full. Send an empty list to unlink all of them. + type: array + items: + type: string + format: uuid + example: + - 9e7b41c2-58da-4a03-b6f1-3c85e0d97a26 + spoken_terms_id: + description: |- + The ID of the Spoken Terms collection to link, applied when the style profile is used + for speech rather than text. A style profile links at most one collection, so a new ID + replaces the current link. Send an empty string to unlink the collection, the same way + an empty string clears `description` and `industry`. + + Requires a plan that includes DeepL Voice. Sending a `spoken_terms_id` on a plan + without it is rejected with `403 Forbidden` and the style profile is not changed. A + value that is not a valid UUID, or that names a collection your account cannot access, + is rejected with `400 Bad Request` naming the field. + type: string + format: uuid + example: def3a26b-3e84-45b3-84ae-0c0aaf3525f7 + glossary_priority_enabled: + description: |- + Whether the glossaries linked to this style profile take priority over its other + components. + 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 + UnlinkAllExampleDocuments: + summary: Unlink all example documents + value: + example_document_ids: [] + UnlinkTheSpokenTermsCollection: + summary: Unlink the Spoken Terms collection + value: + spoken_terms_id: '' + 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 + example_document_ids: [] + spoken_terms_id: def3a26b-3e84-45b3-84ae-0c0aaf3525f7 + glossary_priority_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 cannot be used. A component ID that is not a valid UUID, or that + names a component your account cannot access, is reported per field, so the message names the + list, or `spoken_terms_id`, that the bad ID was passed in. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + examples: + UnusableComponentId: + summary: Unusable component ID + value: + message: One or more IDs in example_document_ids could not be used + EmptyName: + summary: Empty name + value: + message: name must not be empty + 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 the request sends a `spoken_terms_id` but your plan + does not include DeepL Voice. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + 404: + description: |- + The style profile could not be found. This is also returned for a style profile the account + cannot see, so a `404` does not confirm that the ID is unused. + 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, and that you can therefore list and retrieve, returns + `404 Not Found` on delete, the same status as an ID that does not exist. + + Deleting a style profile unlinks its components rather than deleting them. The glossaries, style + rule lists, translation memories, example documents and Spoken Terms collection it referenced are + left in place. 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 the account + cannot see, and for a style profile the account can see but does not own, so a `404` does not + confirm that the ID is unused. + 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 +6895,106 @@ 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 + - example_document_ids + - glossary_priority_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. A style profile always has a + name, so it cannot be cleared once it is set. + 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, in the order they are applied. + 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, in the order they are applied. + 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, in the order they are applied. + 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 + example_document_ids: + description: |- + The IDs of the example documents linked to the style profile, in the order they are applied. + type: array + items: + type: string + format: uuid + example: + - 9e7b41c2-58da-4a03-b6f1-3c85e0d97a26 + spoken_terms_id: + description: |- + The ID of the Spoken Terms collection linked to the style profile, applied when the profile is + used for speech rather than text. A style profile links at most one collection. Omitted from + the response when no collection is linked. Collections are managed with the + [Spoken Terms endpoints](/api-reference/spoken-terms/list-all-spoken-terms). + type: string + format: uuid + example: def3a26b-3e84-45b3-84ae-0c0aaf3525f7 + glossary_priority_enabled: + description: |- + Whether the glossaries linked to the style profile take priority over its other components. + 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..aa1ffc67 --- /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: "Learn how to create a style profile, from a name on its own to a fully configured bundle, and what happens when a component ID is rejected." +--- 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..369eb93d --- /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: "Learn how to delete a style profile you own, and why the components it bundled are only unlinked." +--- 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..e068c7c3 --- /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: "Learn how to fetch a single style profile's linked components, metadata, and timestamps 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..5dd7b266 --- /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: "Learn how to page through the style profiles your account owns and the ones shared with it, newest first." +--- 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..86db28ee --- /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: "Learn how to rename a style profile, clear its description or industry, and replace the set of components it links." +--- diff --git a/docs.json b/docs.json index 38559381..7e55d38c 100644 --- a/docs.json +++ b/docs.json @@ -278,6 +278,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": [