diff --git a/api-reference/openapi.yaml b/api-reference/openapi.yaml index 00601ce..d2bcc54 100644 --- a/api-reference/openapi.yaml +++ b/api-reference/openapi.yaml @@ -1994,6 +1994,378 @@ paths: $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' + language: + $ref: '#/components/schemas/StyleRuleLanguage' + configured_rules: + $ref: '#/components/schemas/ConfiguredRules' + custom_instructions: + type: array + description: Array of custom instruction objects + 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 + responses: + 200: + 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/Forbidden' + 429: + $ref: '#/components/responses/TooManyRequests' + 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' + 401: + $ref: '#/components/responses/Unauthorized' + 403: + $ref: '#/components/responses/Forbidden' + 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 configured rules + 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' + configured_rules: + $ref: '#/components/schemas/ConfiguredRules' + 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/Forbidden' + 404: + $ref: '#/components/responses/NotFound' + 429: + $ref: '#/components/responses/TooManyRequests' + 500: + $ref: '#/components/responses/InternalServerError' + 503: + $ref: '#/components/responses/ServiceUnavailable' + security: + - auth_header: [] + delete: + summary: Delete a style rule list + operationId: deleteStyleRuleList + parameters: + - name: style_id + in: path + required: true + schema: + type: string + description: The ID of the style rule list + responses: + 204: + description: Style rule list deleted successfully + headers: + X-Trace-ID: + $ref: '#/components/headers/X-Trace-ID' + 401: + $ref: '#/components/responses/Unauthorized' + 403: + $ref: '#/components/responses/Forbidden' + 404: + $ref: '#/components/responses/NotFound' + 429: + $ref: '#/components/responses/TooManyRequests' + 500: + $ref: '#/components/responses/InternalServerError' + 503: + $ref: '#/components/responses/ServiceUnavailable' + security: + - auth_header: [] + /v3/style_rules/{style_id}/custom_instructions: + post: + summary: Create a custom instruction + operationId: createCustomInstruction + 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 + required: + - label + - prompt + properties: + label: + type: string + description: Label for the custom instruction + maxLength: 100 + prompt: + type: string + description: Instruction text + maxLength: 300 + source_language: + type: string + description: Optional source language code + responses: + 200: + description: Custom instruction 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/Forbidden' + 404: + $ref: '#/components/responses/NotFound' + 429: + $ref: '#/components/responses/TooManyRequests' + 500: + $ref: '#/components/responses/InternalServerError' + 503: + $ref: '#/components/responses/ServiceUnavailable' + security: + - auth_header: [] + /v3/style_rules/{style_id}/custom_instructions/{instruction_id}: + get: + summary: Get a custom instruction + operationId: getCustomInstruction + parameters: + - name: style_id + in: path + required: true + schema: + type: string + description: The ID of the style rule list + - name: instruction_id + in: path + required: true + schema: + type: string + description: The ID of the custom instruction + responses: + 200: + description: Custom instruction details + headers: + X-Trace-ID: + $ref: '#/components/headers/X-Trace-ID' + content: + application/json: + schema: + $ref: '#/components/schemas/CustomInstruction' + 401: + $ref: '#/components/responses/Unauthorized' + 403: + $ref: '#/components/responses/Forbidden' + 404: + $ref: '#/components/responses/NotFound' + 429: + $ref: '#/components/responses/TooManyRequests' + 500: + $ref: '#/components/responses/InternalServerError' + 503: + $ref: '#/components/responses/ServiceUnavailable' + security: + - auth_header: [] + put: + summary: Update a custom instruction + operationId: updateCustomInstruction + parameters: + - name: style_id + in: path + required: true + schema: + type: string + description: The ID of the style rule list + - name: instruction_id + in: path + required: true + schema: + type: string + description: The ID of the custom instruction + requestBody: + required: true + content: + application/json: + schema: + type: object + required: + - label + - prompt + properties: + label: + type: string + description: Updated label for the custom instruction + maxLength: 100 + prompt: + type: string + description: Updated instruction text + maxLength: 300 + source_language: + type: string + description: Optional source language code + responses: + 200: + description: Custom instruction updated successfully + headers: + X-Trace-ID: + $ref: '#/components/headers/X-Trace-ID' + content: + application/json: + schema: + $ref: '#/components/schemas/CustomInstruction' + 400: + $ref: '#/components/responses/BadRequest' + 401: + $ref: '#/components/responses/Unauthorized' + 403: + $ref: '#/components/responses/Forbidden' + 404: + $ref: '#/components/responses/NotFound' + 429: + $ref: '#/components/responses/TooManyRequests' + 500: + $ref: '#/components/responses/InternalServerError' + 503: + $ref: '#/components/responses/ServiceUnavailable' + security: + - auth_header: [] + delete: + summary: Delete a custom instruction + operationId: deleteCustomInstruction + parameters: + - name: style_id + in: path + required: true + schema: + type: string + description: The ID of the style rule list + - name: instruction_id + in: path + required: true + schema: + type: string + description: The ID of the custom instruction + responses: + 204: + description: Custom instruction deleted successfully + headers: + X-Trace-ID: + $ref: '#/components/headers/X-Trace-ID' + 401: + $ref: '#/components/responses/Unauthorized' + 403: + $ref: '#/components/responses/Forbidden' + 404: + $ref: '#/components/responses/NotFound' + 429: + $ref: '#/components/responses/TooManyRequests' + 500: + $ref: '#/components/responses/InternalServerError' + 503: + $ref: '#/components/responses/ServiceUnavailable' + security: + - auth_header: [] /v3/voice/realtime: servers: - url: https://api.deepl.com diff --git a/api-reference/style-rules.mdx b/api-reference/style-rules.mdx index 1a32a4a..b2a06b8 100644 --- a/api-reference/style-rules.mdx +++ b/api-reference/style-rules.mdx @@ -8,140 +8,811 @@ description: "Manage a shared list of rules for style, formatting, and more" The Style Rules API is currently available only to Pro API subscribers. +## Overview + The style rules feature allows you to select a set of rules to apply when translating text. These rules make changes to your text according to the selected formatting and spelling conventions. -You can create style rules in the UI at [https://deepl.com/custom-rules](https://deepl.com/custom-rules). +You can create style rules in the UI at [https://deepl.com/custom-rules](https://deepl.com/custom-rules). + +Both glossaries and style rules are unique to each of DeepL's global data centers and are not shared between them. Clients using the `api-us.deepl.com` endpoint will not be able to access glossaries or style rules created in the UI at this time. + +A **style rule list** contains two types of rules: +- **Configured rules**: Predefined rules for formatting conventions (e.g., time format, number formatting, style and tone) +- **Custom instructions**: User-defined instructions for specific styling requirements + +Both configured rules and custom instructions are applied during translation to ensure your translations match your style requirements. They work together to provide comprehensive style control over your translated content. + +### Limits + +- There is no limit to how many predefined rules can be selected per style rule list +- A maximum of 200 custom instructions can be enabled per style rule list (although this may be adjusted based on plan tiers in the future) +- Each custom instruction is at most 300 characters + +If you need more than 200 custom instructions, consider organizing your rules into multiple style rule lists for different use cases or content types. + +## Creating style rules -Both style rules and glossaries are unique to each of DeepL's global data centers and are not shared between them. Clients using the `api-us.deepl.com` endpoint will not be able to access glossaries or style rules created in the UI at this time. +### Create a style rule list -### Get all style rule lists -Get all style rules lists and their meta-information. +`POST /v3/style_rules` + +Create a new style rule list with configured rules and optional custom instructions. - + + The example below uses our API Pro endpoint `https://api.deepl.com`. If you're an API Free user, remember to update your requests to use `https://api-free.deepl.com` instead. -```sh Example request: get all style rule lists -curl -X GET 'https://api.deepl.com/v3/style_rules' \ ---header 'Authorization: DeepL-Auth-Key [yourAuthKey]' -``` + ```sh Example request: create a style rule list + curl -X POST 'https://api.deepl.com/v3/style_rules' \ + --header 'Authorization: DeepL-Auth-Key [yourAuthKey]' \ + --header 'Content-Type: application/json' \ + --data '{ + "name": "Technical Documentation Rules", + "language": "de", + "configured_rules": { + "numbers": { + "time_format": "always-use-24-hour-clock" + } + }, + "custom_instructions": [ + { + "label": "Tone instruction", + "prompt": "Use a friendly, diplomatic tone", + "source_language": "en" + } + ] + }' + ``` -```json Example response -{ - "style_rules": [ + ```json Example response { "style_id": "a74d88fb-ed2a-4943-a664-a4512398b994", "name": "Technical Documentation Rules", "creation_time": "2024-10-01T12:34:56Z", - "updated_time": "2024-10-03T12:34:56Z", - "language": "EN", - "version": 8 + "updated_time": "2024-10-01T12:34:56Z", + "language": "de", + "version": 1, + "configured_rules": { + "numbers": { + "time_format": "always-use-24-hour-clock" + } + }, + "custom_instructions": [ + { + "id": "68fdb803-c013-4e67-b62e-1aad0ab519cd", + "label": "Tone instruction", + "prompt": "Use a friendly, diplomatic tone", + "source_language": "en" + } + ] } - ] -} -``` -You can also optionally pass in a `detailed` query parameter, to retrieve all configured rules and custom instructions per rule list. + ``` + + + The example below uses our API Pro endpoint `https://api.deepl.com`. If you're an API Free user, remember to update your requests to use `https://api-free.deepl.com` instead. -```sh Example request: get all style rule lists and their configured rules -curl -X GET 'https://api.deepl.com/v3/style_rules?detailed=true' \ ---header 'Authorization: DeepL-Auth-Key [yourAuthKey]' -``` + ```http Example request: create a style rule list + POST /v3/style_rules HTTP/2 + Host: api.deepl.com + Authorization: DeepL-Auth-Key [yourAuthKey] + User-Agent: YourApp/1.2.3 + Content-Length: 234 + Content-Type: application/json -```json Example response -{ - "style_rules": [ + { + "name": "Technical Documentation Rules", + "language": "de", + "configured_rules": { + "numbers": { + "time_format": "always-use-24-hour-clock" + } + }, + "custom_instructions": [ + { + "label": "Tone instruction", + "prompt": "Use a friendly, diplomatic tone", + "source_language": "en" + } + ] + } + ``` + + ```json Example response { "style_id": "a74d88fb-ed2a-4943-a664-a4512398b994", "name": "Technical Documentation Rules", "creation_time": "2024-10-01T12:34:56Z", - "updated_time": "2024-10-03T12:34:56Z", - "language": "EN", - "version": 8, + "updated_time": "2024-10-01T12:34:56Z", + "language": "de", + "version": 1, "configured_rules": { "numbers": { - "time_format": "always-use-24-hour-clock" - }, - "style_and_tone": { - "instructions_style": "use-imperative", - "redundant_introductory_words": "avoid-redundant-introductory-words-that-relate-to-current-text" + "time_format": "always-use-24-hour-clock" } }, - "custom_instructions": { - "label": "My Custom instruction", - "prompt": "Use a friendly, diplomatic tone" - } + "custom_instructions": [ + { + "id": "68fdb803-c013-4e67-b62e-1aad0ab519cd", + "label": "Tone instruction", + "prompt": "Use a friendly, diplomatic tone", + "source_language": "en" + } + ] } - ] -} -``` - - - -```http Example request: get all style rule lists -GET https://api.deepl.com/v3/style_rules HTTP/2 -Host: api.deepl.com -Authorization: DeepL-Auth-Key [yourAuthKey] -User-Agent: YourApp/1.2.3 -``` -```json Example response -{ - "style_rules": [ + ``` + + + +#### Request body parameters + + + The name of the style rule list. Maximum length: 1024 characters. + + + The target language for the style rules. Supported values: `de`, `en`, `es`, `fr`, `it`, `ja`, `ko`, `zh`. + + + An object containing predefined rules to enable for the style rule list. Rules are organized by category (e.g., `numbers`, `style_and_tone`). Each category can contain multiple rule options. + + + An array of custom instruction objects. Each custom instruction must include `label`, `prompt`, and optionally `source_language`. Maximum 200 custom instructions per style rule list. Each prompt is limited to 300 characters. + + + + The `version` field in the response increments each time the style rule list is modified (e.g., when rules are updated or custom instructions are added/removed). You can use this field to track changes to your style rules. + + +## Retrieving style rules + +### List all style rule lists + +`GET /v3/style_rules` + +Get all style rule lists and their meta-information. + + + + The example below uses our API Pro endpoint `https://api.deepl.com`. If you're an API Free user, remember to update your requests to use `https://api-free.deepl.com` instead. + + ```sh Example request: get all style rule lists + curl -X GET 'https://api.deepl.com/v3/style_rules' \ + --header 'Authorization: DeepL-Auth-Key [yourAuthKey]' + ``` + + ```json Example response + { + "style_rules": [ + { + "style_id": "a74d88fb-ed2a-4943-a664-a4512398b994", + "name": "Technical Documentation Rules", + "creation_time": "2024-10-01T12:34:56Z", + "updated_time": "2024-10-03T12:34:56Z", + "language": "en", + "version": 8 + } + ] + } + ``` + + You can also optionally pass in a `detailed` query parameter to retrieve all configured rules and custom instructions per rule list. + + ```sh Example request: get all style rule lists with details + curl -X GET 'https://api.deepl.com/v3/style_rules?detailed=true' \ + --header 'Authorization: DeepL-Auth-Key [yourAuthKey]' + ``` + + ```json Example response + { + "style_rules": [ + { + "style_id": "a74d88fb-ed2a-4943-a664-a4512398b994", + "name": "Technical Documentation Rules", + "creation_time": "2024-10-01T12:34:56Z", + "updated_time": "2024-10-03T12:34:56Z", + "language": "en", + "version": 8, + "configured_rules": { + "numbers": { + "time_format": "always-use-24-hour-clock" + }, + "style_and_tone": { + "instructions_style": "use-imperative", + "redundant_introductory_words": "avoid-redundant-introductory-words-that-relate-to-current-text" + } + }, + "custom_instructions": [ + { + "id": "68fdb803-c013-4e67-b62e-1aad0ab519cd", + "label": "Tone instruction", + "prompt": "Use a friendly, diplomatic tone", + "source_language": "de" + } + ] + } + ] + } + ``` + + + The example below uses our API Pro endpoint `https://api.deepl.com`. If you're an API Free user, remember to update your requests to use `https://api-free.deepl.com` instead. + + ```http Example request: get all style rule lists + GET /v3/style_rules HTTP/2 + Host: api.deepl.com + Authorization: DeepL-Auth-Key [yourAuthKey] + User-Agent: YourApp/1.2.3 + ``` + + ```json Example response + { + "style_rules": [ + { + "style_id": "a74d88fb-ed2a-4943-a664-a4512398b994", + "name": "Technical Documentation Rules", + "creation_time": "2024-10-01T12:34:56Z", + "updated_time": "2024-10-03T12:34:56Z", + "language": "en", + "version": 8 + } + ] + } + ``` + + You can also optionally pass in a `detailed` query parameter to retrieve all configured rules and custom instructions per rule list. + + ```http Example request: get all style rule lists with details + GET /v3/style_rules?detailed=true HTTP/2 + Host: api.deepl.com + Authorization: DeepL-Auth-Key [yourAuthKey] + User-Agent: YourApp/1.2.3 + ``` + + ```json Example response + { + "style_rules": [ + { + "style_id": "a74d88fb-ed2a-4943-a664-a4512398b994", + "name": "Technical Documentation Rules", + "creation_time": "2024-10-01T12:34:56Z", + "updated_time": "2024-10-03T12:34:56Z", + "language": "en", + "version": 8, + "configured_rules": { + "numbers": { + "time_format": "always-use-24-hour-clock" + }, + "style_and_tone": { + "instructions_style": "use-imperative", + "redundant_introductory_words": "avoid-redundant-introductory-words-that-relate-to-current-text" + } + }, + "custom_instructions": [ + { + "id": "68fdb803-c013-4e67-b62e-1aad0ab519cd", + "label": "Tone instruction", + "prompt": "Use a friendly, diplomatic tone", + "source_language": "de" + } + ] + } + ] + } + ``` + + + +#### Query parameters + + + Determines if the rule list's `configured_rules` and `custom_instructions` should be included in the response body. If `detailed` parameter is not included, defaults to `false`. + + + The index of the first page to return. Default: 0 (the first page). Use with `page_size` to get the next page of rule lists. + + + The maximum number of style rule lists to return. Default: 10. Minimum: 1. Maximum: 25. + + +### Get a style rule list + +`GET /v3/style_rules/{style_id}` + +Get detailed information for a single style rule list, including all configured rules and custom instructions. + + + + The example below uses our API Pro endpoint `https://api.deepl.com`. If you're an API Free user, remember to update your requests to use `https://api-free.deepl.com` instead. + + ```sh Example request: retrieve style rule list + curl -X GET 'https://api.deepl.com/v3/style_rules/{style_id}' \ + --header 'Authorization: DeepL-Auth-Key [yourAuthKey]' + ``` + + ```json Example response { "style_id": "a74d88fb-ed2a-4943-a664-a4512398b994", "name": "Technical Documentation Rules", "creation_time": "2024-10-01T12:34:56Z", "updated_time": "2024-10-03T12:34:56Z", - "language": "EN", - "version": 8 + "language": "en", + "version": 8, + "configured_rules": { + "numbers": { + "time_format": "always-use-24-hour-clock" + }, + "style_and_tone": { + "instructions_style": "use-imperative", + "redundant_introductory_words": "avoid-redundant-introductory-words-that-relate-to-current-text" + } + }, + "custom_instructions": [ + { + "id": "68fdb803-c013-4e67-b62e-1aad0ab519cd", + "label": "Tone instruction", + "prompt": "Use a friendly, diplomatic tone", + "source_language": "de" + } + ] } - ] -} -``` + ``` + + + The example below uses our API Pro endpoint `https://api.deepl.com`. If you're an API Free user, remember to update your requests to use `https://api-free.deepl.com` instead. -You can also optionally pass in a `detailed` query parameter, to retrieve all configured rules and custom instructions per rule list. + ```http Example request: retrieve style rule list + GET /v3/style_rules/{style_id} HTTP/2 + Host: api.deepl.com + Authorization: DeepL-Auth-Key [yourAuthKey] + User-Agent: YourApp/1.2.3 + ``` -```http Example request: get all style rule lists and their configured rules -GET https://api.deepl.com/v3/style_rules?detailed=true HTTP/2 -Host: api.deepl.com -Authorization: DeepL-Auth-Key [yourAuthKey] -User-Agent: YourApp/1.2.3 -``` -```json Example response -{ - "style_rules": [ + ```json Example response { "style_id": "a74d88fb-ed2a-4943-a664-a4512398b994", "name": "Technical Documentation Rules", "creation_time": "2024-10-01T12:34:56Z", "updated_time": "2024-10-03T12:34:56Z", - "language": "EN", + "language": "en", "version": 8, "configured_rules": { "numbers": { - "time_format": "always-use-24-hour-clock" + "time_format": "always-use-24-hour-clock" }, "style_and_tone": { - "instructions_style": "use-imperative", - "redundant_introductory_words": "avoid-redundant-introductory-words-that-relate-to-current-text" + "instructions_style": "use-imperative", + "redundant_introductory_words": "avoid-redundant-introductory-words-that-relate-to-current-text" + } + }, + "custom_instructions": [ + { + "id": "68fdb803-c013-4e67-b62e-1aad0ab519cd", + "label": "Tone instruction", + "prompt": "Use a friendly, diplomatic tone", + "source_language": "de" + } + ] + } + ``` + + + +## Updating style rules + +### Update configured rules + +`PATCH /v3/style_rules/{style_id}` + +Update the name and/or configured rules for a style rule list. This allows for partial updates without affecting custom instructions or other unchanged fields. + + + + The example below uses our API Pro endpoint `https://api.deepl.com`. If you're an API Free user, remember to update your requests to use `https://api-free.deepl.com` instead. + + ```sh Example request: update configured rules + curl -X PATCH 'https://api.deepl.com/v3/style_rules/{style_id}' \ + --header 'Authorization: DeepL-Auth-Key [yourAuthKey]' \ + --header 'Content-Type: application/json' \ + --data '{ + "name": "New Technical Documentation Rules", + "configured_rules": { + "numbers": { + "time_format": "always-use-12-hour-clock" + } + } + }' + ``` + + ```json Example response + { + "style_id": "a74d88fb-ed2a-4943-a664-a4512398b994", + "name": "New Technical Documentation Rules", + "creation_time": "2024-10-01T12:34:56Z", + "updated_time": "2024-10-01T12:34:56Z", + "language": "de", + "version": 2, + "configured_rules": { + "numbers": { + "time_format": "always-use-12-hour-clock" } }, - "custom_instructions": { - "label": "My Custom instruction", - "prompt": "Use a friendly, diplomatic tone" + "custom_instructions": [ + { + "id": "68fdb803-c013-4e67-b62e-1aad0ab519cd", + "label": "Tone instruction", + "prompt": "Use a friendly, diplomatic tone", + "source_language": "en" + } + ] + } + ``` + + + The example below uses our API Pro endpoint `https://api.deepl.com`. If you're an API Free user, remember to update your requests to use `https://api-free.deepl.com` instead. + + ```http Example request: update configured rules + PATCH /v3/style_rules/{style_id} HTTP/2 + Host: api.deepl.com + Authorization: DeepL-Auth-Key [yourAuthKey] + User-Agent: YourApp/1.2.3 + Content-Length: 123 + Content-Type: application/json + + { + "name": "New Technical Documentation Rules", + "configured_rules": { + "numbers": { + "time_format": "always-use-12-hour-clock" + } } } - ] -} -``` - + ``` + + ```json Example response + { + "style_id": "a74d88fb-ed2a-4943-a664-a4512398b994", + "name": "New Technical Documentation Rules", + "creation_time": "2024-10-01T12:34:56Z", + "updated_time": "2024-10-01T12:34:56Z", + "language": "de", + "version": 2, + "configured_rules": { + "numbers": { + "time_format": "always-use-12-hour-clock" + } + }, + "custom_instructions": [ + { + "id": "68fdb803-c013-4e67-b62e-1aad0ab519cd", + "label": "Tone instruction", + "prompt": "Use a friendly, diplomatic tone", + "source_language": "en" + } + ] + } + ``` + -### Query parameters - -Determines if the rule list's `configured_rules` and `custom_instructions` should be included in the response body. If `detailed` parameter is not included, defaults to `false`. +#### Request body parameters + + + The new name for the style rule list. Maximum length: 1024 characters. - -The index of the first page to return. Default: 0 (the first page). Use with `page_size` to get the next page of rule lists. + + An object containing the updated predefined rules. Only the provided rules will be updated; other rules remain unchanged. - -The maximum number of style rule lists to return. Default: 10. Minimum: 1. Maximum: 25. + +### Delete a style rule list + +`DELETE /v3/style_rules/{style_id}` + +Delete a style rule list. This operation cannot be undone. + + + + The example below uses our API Pro endpoint `https://api.deepl.com`. If you're an API Free user, remember to update your requests to use `https://api-free.deepl.com` instead. + + ```sh Example request: delete style rule list + curl -X DELETE 'https://api.deepl.com/v3/style_rules/{style_id}' \ + --header 'Authorization: DeepL-Auth-Key [yourAuthKey]' + ``` + + Returns a `204 No Content` status code on successful deletion. The response body will be empty. If the style rule list is not found, a `404` error will be returned. + + + The example below uses our API Pro endpoint `https://api.deepl.com`. If you're an API Free user, remember to update your requests to use `https://api-free.deepl.com` instead. + + ```http Example request: delete style rule list + DELETE /v3/style_rules/{style_id} HTTP/2 + Host: api.deepl.com + Authorization: DeepL-Auth-Key [yourAuthKey] + User-Agent: YourApp/1.2.3 + ``` + + Returns a `204 No Content` status code on successful deletion. The response body will be empty. If the style rule list is not found, a `404` error will be returned. + + + +## Managing custom instructions + +### Create a custom instruction + +`POST /v3/style_rules/{style_id}/custom_instructions` + +Add a new custom instruction to an existing style rule list. The response returns the complete updated style rule list, including the new custom instruction with its generated ID. + + + + The example below uses our API Pro endpoint `https://api.deepl.com`. If you're an API Free user, remember to update your requests to use `https://api-free.deepl.com` instead. + + ```sh Example request: create custom instruction + curl -X POST 'https://api.deepl.com/v3/style_rules/{style_id}/custom_instructions' \ + --header 'Authorization: DeepL-Auth-Key [yourAuthKey]' \ + --header 'Content-Type: application/json' \ + --data '{ + "label": "Currency format instruction", + "prompt": "Put currency symbols after the numeric amount", + "source_language": "en" + }' + ``` + + ```json Example response + { + "style_id": "a74d88fb-ed2a-4943-a664-a4512398b994", + "name": "Technical Documentation Rules", + "creation_time": "2024-10-01T12:34:56Z", + "updated_time": "2024-10-01T12:34:56Z", + "language": "de", + "version": 2, + "configured_rules": { + "numbers": { + "time_format": "always-use-24-hour-clock" + } + }, + "custom_instructions": [ + { + "id": "68fdb803-c013-4e67-b62e-1aad0ab519cd", + "label": "Tone instruction", + "prompt": "Use a friendly, diplomatic tone", + "source_language": "en" + }, + { + "id": "f4515921-8fdf-4e3a-a981-ad7a6717a8aa", + "label": "Currency format instruction", + "prompt": "Put currency symbols after the numeric amount", + "source_language": "en" + } + ] + } + ``` + + + The example below uses our API Pro endpoint `https://api.deepl.com`. If you're an API Free user, remember to update your requests to use `https://api-free.deepl.com` instead. + + ```http Example request: create custom instruction + POST /v3/style_rules/{style_id}/custom_instructions HTTP/2 + Host: api.deepl.com + Authorization: DeepL-Auth-Key [yourAuthKey] + User-Agent: YourApp/1.2.3 + Content-Length: 145 + Content-Type: application/json + + { + "label": "Currency format instruction", + "prompt": "Put currency symbols after the numeric amount", + "source_language": "en" + } + ``` + + ```json Example response + { + "style_id": "a74d88fb-ed2a-4943-a664-a4512398b994", + "name": "Technical Documentation Rules", + "creation_time": "2024-10-01T12:34:56Z", + "updated_time": "2024-10-01T12:34:56Z", + "language": "de", + "version": 2, + "configured_rules": { + "numbers": { + "time_format": "always-use-24-hour-clock" + } + }, + "custom_instructions": [ + { + "id": "68fdb803-c013-4e67-b62e-1aad0ab519cd", + "label": "Tone instruction", + "prompt": "Use a friendly, diplomatic tone", + "source_language": "en" + }, + { + "id": "f4515921-8fdf-4e3a-a981-ad7a6717a8aa", + "label": "Currency format instruction", + "prompt": "Put currency symbols after the numeric amount", + "source_language": "en" + } + ] + } + ``` + + + +#### Request body parameters + + + A short descriptive label for the custom instruction. Maximum length: 100 characters. + + + The instruction text that defines the style requirement. Maximum length: 300 characters. + + + Optional source language code for the custom instruction (e.g., `en`, `de`, `fr`). + + +### Get a custom instruction + +`GET /v3/style_rules/{style_id}/custom_instructions/{instruction_id}` + +Get details for a specific custom instruction within a style rule list. + + + + The example below uses our API Pro endpoint `https://api.deepl.com`. If you're an API Free user, remember to update your requests to use `https://api-free.deepl.com` instead. + + ```sh Example request: retrieve custom instruction + curl -X GET 'https://api.deepl.com/v3/style_rules/{style_id}/custom_instructions/{instruction_id}' \ + --header 'Authorization: DeepL-Auth-Key [yourAuthKey]' + ``` + + ```json Example response + { + "id": "f4515921-8fdf-4e3a-a981-ad7a6717a8aa", + "label": "Tone instruction", + "prompt": "Use a friendly, diplomatic tone", + "source_language": "de" + } + ``` + + + The example below uses our API Pro endpoint `https://api.deepl.com`. If you're an API Free user, remember to update your requests to use `https://api-free.deepl.com` instead. + + ```http Example request: retrieve custom instruction + GET /v3/style_rules/{style_id}/custom_instructions/{instruction_id} HTTP/2 + Host: api.deepl.com + Authorization: DeepL-Auth-Key [yourAuthKey] + User-Agent: YourApp/1.2.3 + ``` + + ```json Example response + { + "id": "f4515921-8fdf-4e3a-a981-ad7a6717a8aa", + "label": "Tone instruction", + "prompt": "Use a friendly, diplomatic tone", + "source_language": "de" + } + ``` + + + +### Update a custom instruction + +`PUT /v3/style_rules/{style_id}/custom_instructions/{instruction_id}` + +Update an existing custom instruction within a style rule list. All fields must be provided. + + + + The example below uses our API Pro endpoint `https://api.deepl.com`. If you're an API Free user, remember to update your requests to use `https://api-free.deepl.com` instead. + + ```sh Example request: update custom instruction + curl -X PUT 'https://api.deepl.com/v3/style_rules/{style_id}/custom_instructions/{instruction_id}' \ + --header 'Authorization: DeepL-Auth-Key [yourAuthKey]' \ + --header 'Content-Type: application/json' \ + --data '{ + "label": "Updated currency instruction", + "prompt": "Put currency symbols after the numeric amount", + "source_language": "en" + }' + ``` + + ```json Example response + { + "id": "f4515921-8fdf-4e3a-a981-ad7a6717a8aa", + "label": "Updated currency instruction", + "prompt": "Put currency symbols after the numeric amount", + "source_language": "en" + } + ``` + + + The example below uses our API Pro endpoint `https://api.deepl.com`. If you're an API Free user, remember to update your requests to use `https://api-free.deepl.com` instead. + + ```http Example request: update custom instruction + PUT /v3/style_rules/{style_id}/custom_instructions/{instruction_id} HTTP/2 + Host: api.deepl.com + Authorization: DeepL-Auth-Key [yourAuthKey] + User-Agent: YourApp/1.2.3 + Content-Length: 145 + Content-Type: application/json + + { + "label": "Updated currency instruction", + "prompt": "Put currency symbols after the numeric amount", + "source_language": "en" + } + ``` + + ```json Example response + { + "id": "f4515921-8fdf-4e3a-a981-ad7a6717a8aa", + "label": "Updated currency instruction", + "prompt": "Put currency symbols after the numeric amount", + "source_language": "en" + } + ``` + + + +#### Request body parameters + + + The updated label for the custom instruction. Maximum length: 100 characters. + + + The updated instruction text. Maximum length: 300 characters. + + Optional source language code for the custom instruction (e.g., `en`, `de`, `fr`). + + +### Delete a custom instruction + +`DELETE /v3/style_rules/{style_id}/custom_instructions/{instruction_id}` + +Delete a specific custom instruction from a style rule list. This operation cannot be undone. + + + + The example below uses our API Pro endpoint `https://api.deepl.com`. If you're an API Free user, remember to update your requests to use `https://api-free.deepl.com` instead. + + ```sh Example request: delete custom instruction + curl -X DELETE 'https://api.deepl.com/v3/style_rules/{style_id}/custom_instructions/{instruction_id}' \ + --header 'Authorization: DeepL-Auth-Key [yourAuthKey]' + ``` + + Returns a `204 No Content` status code on successful deletion. The response body will be empty. If the custom instruction is not found, a `404` error will be returned. + + + The example below uses our API Pro endpoint `https://api.deepl.com`. If you're an API Free user, remember to update your requests to use `https://api-free.deepl.com` instead. + + ```http Example request: delete custom instruction + DELETE /v3/style_rules/{style_id}/custom_instructions/{instruction_id} HTTP/2 + Host: api.deepl.com + Authorization: DeepL-Auth-Key [yourAuthKey] + User-Agent: YourApp/1.2.3 + ``` + + Returns a `204 No Content` status code on successful deletion. The response body will be empty. If the custom instruction is not found, a `404` error will be returned. + + + +## Using style rules + +### In translation requests + +To use a style rule list in a translation request, include its `style_id` parameter in your translation call. For more information on using style rules in translations, see the [translation documentation](/api-reference/translate). + +```sh Example: translate with style rules +curl -X POST 'https://api.deepl.com/v2/translate' \ +--header 'Authorization: DeepL-Auth-Key [yourAuthKey]' \ +--header 'Content-Type: application/json' \ +--data '{ + "text": ["The meeting is at 3:00 PM"], + "source_lang": "EN", + "target_lang": "DE", + "style_id": "a74d88fb-ed2a-4943-a664-a4512398b994" +}' +``` + + + Any request with the `style_id` parameter enabled will use `quality_optimized` models. Requests combining `style_id` and `model_type: latency_optimized` will be rejected. + diff --git a/api-reference/style-rules/create-custom-instruction.mdx b/api-reference/style-rules/create-custom-instruction.mdx new file mode 100644 index 0000000..1dfe017 --- /dev/null +++ b/api-reference/style-rules/create-custom-instruction.mdx @@ -0,0 +1,4 @@ +--- +openapi: post /v3/style_rules/{style_id}/custom_instructions +title: "Create a custom instruction" +--- diff --git a/api-reference/style-rules/create-style-rule.mdx b/api-reference/style-rules/create-style-rule.mdx new file mode 100644 index 0000000..f9690c2 --- /dev/null +++ b/api-reference/style-rules/create-style-rule.mdx @@ -0,0 +1,4 @@ +--- +openapi: post /v3/style_rules +title: "Create a style rule list" +--- diff --git a/api-reference/style-rules/delete-custom-instruction.mdx b/api-reference/style-rules/delete-custom-instruction.mdx new file mode 100644 index 0000000..9f248d1 --- /dev/null +++ b/api-reference/style-rules/delete-custom-instruction.mdx @@ -0,0 +1,4 @@ +--- +openapi: delete /v3/style_rules/{style_id}/custom_instructions/{instruction_id} +title: "Delete a custom instruction" +--- diff --git a/api-reference/style-rules/delete-style-rule.mdx b/api-reference/style-rules/delete-style-rule.mdx new file mode 100644 index 0000000..082af86 --- /dev/null +++ b/api-reference/style-rules/delete-style-rule.mdx @@ -0,0 +1,4 @@ +--- +openapi: delete /v3/style_rules/{style_id} +title: "Delete a style rule list" +--- diff --git a/api-reference/style-rules/get-custom-instruction.mdx b/api-reference/style-rules/get-custom-instruction.mdx new file mode 100644 index 0000000..e16be4a --- /dev/null +++ b/api-reference/style-rules/get-custom-instruction.mdx @@ -0,0 +1,4 @@ +--- +openapi: get /v3/style_rules/{style_id}/custom_instructions/{instruction_id} +title: "Get a custom instruction" +--- diff --git a/api-reference/style-rules/get-style-rule.mdx b/api-reference/style-rules/get-style-rule.mdx new file mode 100644 index 0000000..4c84edf --- /dev/null +++ b/api-reference/style-rules/get-style-rule.mdx @@ -0,0 +1,4 @@ +--- +openapi: get /v3/style_rules/{style_id} +title: "Get a style rule list" +--- diff --git a/api-reference/style-rules/update-custom-instruction.mdx b/api-reference/style-rules/update-custom-instruction.mdx new file mode 100644 index 0000000..5449e6d --- /dev/null +++ b/api-reference/style-rules/update-custom-instruction.mdx @@ -0,0 +1,4 @@ +--- +openapi: put /v3/style_rules/{style_id}/custom_instructions/{instruction_id} +title: "Update a custom instruction" +--- diff --git a/api-reference/style-rules/update-style-rule.mdx b/api-reference/style-rules/update-style-rule.mdx new file mode 100644 index 0000000..173e826 --- /dev/null +++ b/api-reference/style-rules/update-style-rule.mdx @@ -0,0 +1,4 @@ +--- +openapi: patch /v3/style_rules/{style_id} +title: "Update configured rules" +--- diff --git a/docs.json b/docs.json index aeac6e3..55f2dfc 100644 --- a/docs.json +++ b/docs.json @@ -180,7 +180,15 @@ "group": "Style rules", "pages": [ "api-reference/style-rules", - "api-reference/style-rules/list-all-style-rules" + "api-reference/style-rules/list-all-style-rules", + "api-reference/style-rules/create-style-rule", + "api-reference/style-rules/get-style-rule", + "api-reference/style-rules/update-style-rule", + "api-reference/style-rules/delete-style-rule", + "api-reference/style-rules/create-custom-instruction", + "api-reference/style-rules/get-custom-instruction", + "api-reference/style-rules/update-custom-instruction", + "api-reference/style-rules/delete-custom-instruction" ] }, { diff --git a/docs/resources/roadmap-and-release-notes.mdx b/docs/resources/roadmap-and-release-notes.mdx index 3c23945..02fe3b8 100644 --- a/docs/resources/roadmap-and-release-notes.mdx +++ b/docs/resources/roadmap-and-release-notes.mdx @@ -8,6 +8,16 @@ rss: true - Add more events to audit logs for Pro API customers (API key management, cost control and usage limit changes) + +## February 15 - Expanded Style Rules API + +Expanded the Style Rules API with comprehensive endpoints for programmatic style rules management: +- Added 4 new endpoints for style rule list operations: create, retrieve, update, and delete +- Added 4 new endpoints for managing custom instructions within style rule lists + +See the [Style Rules API reference](/api-reference/style-rules) for complete documentation. + + ## January 20 - Legacy Auth Deprecation