Skip to main content
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. 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

​
Create a style rule list

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.
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"
    }
  ]
}'
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": 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"
    }
  ]
}

​
Request body parameters

​
name
string
required
The name of the style rule list. Maximum length: 1024 characters.
​
language
string
required
The target language for the style rules. Supported values: de, en, es, fr, it, ja, ko, zh.
​
configured_rules
object
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.
​
custom_instructions
array
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.
Example request: get all style rule lists
curl -X GET 'https://api.deepl.com/v3/style_rules' \
--header 'Authorization: DeepL-Auth-Key [yourAuthKey]'
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.
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]'
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

​
detailed
boolean
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.
​
page
integer
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.
​
page_size
integer
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.
Example request: retrieve style rule list
curl -X GET 'https://api.deepl.com/v3/style_rules/{style_id}' \
--header 'Authorization: DeepL-Auth-Key [yourAuthKey]'
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,
  "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"
    }
  ]
}

​
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.
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"
    }
  }
}'
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"
    }
  ]
}

​
Request body parameters

​
name
string
The new name for the style rule list. Maximum length: 1024 characters.
​
configured_rules
object
An object containing the updated predefined rules. Only the provided rules will be updated; other rules remain unchanged.

​
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.
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.

​
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.
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"
}'
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

​
label
string
required
A short descriptive label for the custom instruction. Maximum length: 100 characters.
​
prompt
string
required
The instruction text that defines the style requirement. Maximum length: 300 characters.
​
source_language
string
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.
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]'
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.
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"
}'
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

​
label
string
required
The updated label for the custom instruction. Maximum length: 100 characters.
​
prompt
string
required
The updated instruction text. Maximum length: 300 characters.
​
source_language
string
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.
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.

​
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.
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.