> ## Documentation Index
> Fetch the complete documentation index at: https://developers.deepl.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Style rules

> Manage a shared list of rules for style, formatting, and more

<Info>
  The Style Rules API is currently available only to Pro API subscribers.
</Info>

## 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).

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.

<Tabs>
  <Tab title="cURL">
    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 a style rule list theme={null}
    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": "en",
      "configured_rules": {
        "dates_and_times": {
          "calendar_era": "use_bc_and_ad"
        },
        "punctuation": {
          "periods_in_academic_degrees": "do_not_use"
        }
      },
      "custom_instructions": [
        {
          "label": "Tone instruction",
          "prompt": "Use a friendly, diplomatic tone",
          "source_language": "en"
        }
      ]
    }'
    ```

    ```json Example response theme={null}
    {
      "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": "en",
      "version": 1,
      "configured_rules": {
        "dates_and_times": {
          "calendar_era": "use_bc_and_ad"
        },
        "punctuation": {
          "periods_in_academic_degrees": "do_not_use"
        }
      },
      "custom_instructions": [
        {
          "id": "68fdb803-c013-4e67-b62e-1aad0ab519cd",
          "label": "Tone instruction",
          "prompt": "Use a friendly, diplomatic tone",
          "source_language": "en"
        }
      ]
    }
    ```
  </Tab>

  <Tab title="HTTP Request">
    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 a style rule list theme={null}
    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

    {
      "name": "Technical Documentation Rules",
      "language": "en",
      "configured_rules": {
        "dates_and_times": {
          "calendar_era": "use_bc_and_ad"
        },
        "punctuation": {
          "periods_in_academic_degrees": "do_not_use"
        }
      },
      "custom_instructions": [
        {
          "label": "Tone instruction",
          "prompt": "Use a friendly, diplomatic tone",
          "source_language": "en"
        }
      ]
    }
    ```

    ```json Example response theme={null}
    {
      "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": "en",
      "version": 1,
      "configured_rules": {
        "dates_and_times": {
          "calendar_era": "use_bc_and_ad"
        },
        "punctuation": {
          "periods_in_academic_degrees": "do_not_use"
        }
      },
      "custom_instructions": [
        {
          "id": "68fdb803-c013-4e67-b62e-1aad0ab519cd",
          "label": "Tone instruction",
          "prompt": "Use a friendly, diplomatic tone",
          "source_language": "en"
        }
      ]
    }
    ```
  </Tab>
</Tabs>

#### Request body parameters

<ParamField body="name" type="string" required>
  The name of the style rule list. Maximum length: 1024 characters.
</ParamField>

<ParamField body="language" type="string" required>
  The target language for the style rules. Supported values: `de`, `en`, `es`, `fr`, `it`, `ja`, `ko`, `zh`.
</ParamField>

<ParamField body="configured_rules" type="object">
  An object containing predefined rules to enable for the style rule list. Rules are organized by category (e.g., `dates_and_times`, `punctuation`). Each category can contain multiple rule options.
</ParamField>

<ParamField body="custom_instructions" type="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.
</ParamField>

<Info>
  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.
</Info>

## Retrieving style rules

### List all style rule lists

`GET /v3/style_rules`

Get all style rule lists and their meta-information.

<Tabs>
  <Tab title="cURL">
    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 theme={null}
    curl -X GET 'https://api.deepl.com/v3/style_rules' \
    --header 'Authorization: DeepL-Auth-Key [yourAuthKey]'
    ```

    ```json Example response theme={null}
    {
      "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 theme={null}
    curl -X GET 'https://api.deepl.com/v3/style_rules?detailed=true' \
    --header 'Authorization: DeepL-Auth-Key [yourAuthKey]'
    ```

    ```json Example response theme={null}
    {
      "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": {
            "dates_and_times": {
              "calendar_era": "use_bc_and_ad"
            },
            "punctuation": {
              "periods_in_academic_degrees": "do_not_use"
            }
          },
          "custom_instructions": [
            {
              "id": "68fdb803-c013-4e67-b62e-1aad0ab519cd",
              "label": "Tone instruction",
              "prompt": "Use a friendly, diplomatic tone",
              "source_language": "de"
            }
          ]
        }
      ]
    }
    ```
  </Tab>

  <Tab title="HTTP Request">
    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 theme={null}
    GET /v3/style_rules HTTP/2
    Host: api.deepl.com
    Authorization: DeepL-Auth-Key [yourAuthKey]
    User-Agent: YourApp/1.2.3
    ```

    ```json Example response theme={null}
    {
      "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 theme={null}
    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 theme={null}
    {
      "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": {
            "dates_and_times": {
              "calendar_era": "use_bc_and_ad"
            },
            "punctuation": {
              "periods_in_academic_degrees": "do_not_use"
            }
          },
          "custom_instructions": [
            {
              "id": "68fdb803-c013-4e67-b62e-1aad0ab519cd",
              "label": "Tone instruction",
              "prompt": "Use a friendly, diplomatic tone",
              "source_language": "de"
            }
          ]
        }
      ]
    }
    ```
  </Tab>
</Tabs>

#### Query parameters

<ParamField query="detailed" type="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`.
</ParamField>

<ParamField query="page" type="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.
</ParamField>

<ParamField query="page_size" type="integer">
  The maximum number of style rule lists to return. Default: 10. Minimum: 1. Maximum: 25.
</ParamField>

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

<Tabs>
  <Tab title="cURL">
    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 theme={null}
    curl -X GET 'https://api.deepl.com/v3/style_rules/{style_id}' \
    --header 'Authorization: DeepL-Auth-Key [yourAuthKey]'
    ```

    ```json Example response theme={null}
    {
      "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": {
        "dates_and_times": {
          "calendar_era": "use_bc_and_ad"
        },
        "punctuation": {
          "periods_in_academic_degrees": "do_not_use"
        }
      },
      "custom_instructions": [
        {
          "id": "68fdb803-c013-4e67-b62e-1aad0ab519cd",
          "label": "Tone instruction",
          "prompt": "Use a friendly, diplomatic tone",
          "source_language": "de"
        }
      ]
    }
    ```
  </Tab>

  <Tab title="HTTP Request">
    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 style rule list theme={null}
    GET /v3/style_rules/{style_id} HTTP/2
    Host: api.deepl.com
    Authorization: DeepL-Auth-Key [yourAuthKey]
    User-Agent: YourApp/1.2.3
    ```

    ```json Example response theme={null}
    {
      "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": {
        "dates_and_times": {
          "calendar_era": "use_bc_and_ad"
        },
        "punctuation": {
          "periods_in_academic_degrees": "do_not_use"
        }
      },
      "custom_instructions": [
        {
          "id": "68fdb803-c013-4e67-b62e-1aad0ab519cd",
          "label": "Tone instruction",
          "prompt": "Use a friendly, diplomatic tone",
          "source_language": "de"
        }
      ]
    }
    ```
  </Tab>
</Tabs>

## Updating style rules

Use `PATCH /v3/style_rules/{style_id}` to update the name of a style rule list, or use `PUT /v3/style_rules/{style_id}/configured_rules` to replace all configured rules.

### Update a style rule list's name

`PATCH /v3/style_rules/{style_id}`

Update the name of a style rule list.

<Tabs>
  <Tab title="cURL">
    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 a style rule list's name theme={null}
    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"
    }'
    ```

    ```json Example response theme={null}
    {
      "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": "en",
      "version": 2,
      "configured_rules": {
        "dates_and_times": {
          "calendar_era": "use_bc_and_ad"
        },
        "punctuation": {
          "periods_in_academic_degrees": "do_not_use"
        }
      },
      "custom_instructions": [
        {
          "id": "68fdb803-c013-4e67-b62e-1aad0ab519cd",
          "label": "Tone instruction",
          "prompt": "Use a friendly, diplomatic tone",
          "source_language": "en"
        }
      ]
    }
    ```
  </Tab>

  <Tab title="HTTP Request">
    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 a style rule list's name theme={null}
    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: 52
    Content-Type: application/json

    {
      "name": "New Technical Documentation Rules"
    }
    ```

    ```json Example response theme={null}
    {
      "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": "en",
      "version": 2,
      "configured_rules": {
        "dates_and_times": {
          "calendar_era": "use_bc_and_ad"
        },
        "punctuation": {
          "periods_in_academic_degrees": "do_not_use"
        }
      },
      "custom_instructions": [
        {
          "id": "68fdb803-c013-4e67-b62e-1aad0ab519cd",
          "label": "Tone instruction",
          "prompt": "Use a friendly, diplomatic tone",
          "source_language": "en"
        }
      ]
    }
    ```
  </Tab>
</Tabs>

#### Request body parameters

<ParamField body="name" type="string">
  The new name for the style rule list. Maximum length: 1024 characters.
</ParamField>

### Replace configured rules

`PUT /v3/style_rules/{style_id}/configured_rules`

Replace all configured rules for a style rule list. Custom instructions are not affected.

<Tabs>
  <Tab title="cURL">
    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: replace configured rules theme={null}
    curl -X PUT 'https://api.deepl.com/v3/style_rules/{style_id}/configured_rules' \
    --header 'Authorization: DeepL-Auth-Key [yourAuthKey]' \
    --header 'Content-Type: application/json' \
    --data '{
      "dates_and_times": {
        "calendar_era": "use_bc_and_ad"
      },
      "punctuation": {
        "periods_in_academic_degrees": "do_not_use"
      }
    }'
    ```

    ```json Example response theme={null}
    {
      "style_id": "a74d88fb-ed2a-4943-a664-a4512398b994",
      "name": "Technical Documentation Rules",
      "creation_time": "2024-10-01T12:34:56Z",
      "updated_time": "2024-10-04T12:34:56Z",
      "language": "en",
      "version": 3,
      "configured_rules": {
        "dates_and_times": {
          "calendar_era": "use_bc_and_ad"
        },
        "punctuation": {
          "periods_in_academic_degrees": "do_not_use"
        }
      },
      "custom_instructions": [
        {
          "id": "68fdb803-c013-4e67-b62e-1aad0ab519cd",
          "label": "Tone instruction",
          "prompt": "Use a friendly, diplomatic tone",
          "source_language": "en"
        }
      ]
    }
    ```
  </Tab>

  <Tab title="HTTP Request">
    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: replace configured rules theme={null}
    PUT /v3/style_rules/{style_id}/configured_rules HTTP/2
    Host: api.deepl.com
    Authorization: DeepL-Auth-Key [yourAuthKey]
    User-Agent: YourApp/1.2.3
    Content-Length: 145
    Content-Type: application/json

    {
      "dates_and_times": {
        "calendar_era": "use_bc_and_ad"
      },
      "punctuation": {
        "periods_in_academic_degrees": "do_not_use"
      }
    }
    ```

    ```json Example response theme={null}
    {
      "style_id": "a74d88fb-ed2a-4943-a664-a4512398b994",
      "name": "Technical Documentation Rules",
      "creation_time": "2024-10-01T12:34:56Z",
      "updated_time": "2024-10-04T12:34:56Z",
      "language": "en",
      "version": 3,
      "configured_rules": {
        "dates_and_times": {
          "calendar_era": "use_bc_and_ad"
        },
        "punctuation": {
          "periods_in_academic_degrees": "do_not_use"
        }
      },
      "custom_instructions": [
        {
          "id": "68fdb803-c013-4e67-b62e-1aad0ab519cd",
          "label": "Tone instruction",
          "prompt": "Use a friendly, diplomatic tone",
          "source_language": "en"
        }
      ]
    }
    ```
  </Tab>
</Tabs>

#### Request body parameters

<ParamField body="configured_rules" type="object" required>
  A `ConfiguredRules` object containing the complete set of predefined rules. This replaces all existing configured rules for the style rule list. Rules are organized by category (e.g., `dates_and_times`, `punctuation`).
</ParamField>

<Info>
  This endpoint replaces the entire configured rules object. Use `PATCH /v3/style_rules/{style_id}` instead if you only want to update the style rule list name.
</Info>

## Deleting style rules

### Delete a style rule list

`DELETE /v3/style_rules/{style_id}`

Delete a style rule list. This operation cannot be undone.

<Tabs>
  <Tab title="cURL">
    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 theme={null}
    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.
  </Tab>

  <Tab title="HTTP Request">
    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 theme={null}
    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.
  </Tab>
</Tabs>

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

<Tabs>
  <Tab title="cURL">
    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 theme={null}
    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 theme={null}
    {
      "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": "en",
      "version": 2,
      "configured_rules": {
        "dates_and_times": {
          "calendar_era": "use_bc_and_ad"
        },
        "punctuation": {
          "periods_in_academic_degrees": "do_not_use"
        }
      },
      "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"
        }
      ]
    }
    ```
  </Tab>

  <Tab title="HTTP Request">
    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 theme={null}
    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 theme={null}
    {
      "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": "en",
      "version": 2,
      "configured_rules": {
        "dates_and_times": {
          "calendar_era": "use_bc_and_ad"
        },
        "punctuation": {
          "periods_in_academic_degrees": "do_not_use"
        }
      },
      "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"
        }
      ]
    }
    ```
  </Tab>
</Tabs>

#### Request body parameters

<ParamField body="label" type="string" required>
  A short descriptive label for the custom instruction. Maximum length: 100 characters.
</ParamField>

<ParamField body="prompt" type="string" required>
  The instruction text that defines the style requirement. Maximum length: 300 characters.
</ParamField>

<ParamField body="source_language" type="string">
  Optional source language code for the custom instruction (e.g., `en`, `de`, `fr`).
</ParamField>

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

<Tabs>
  <Tab title="cURL">
    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 theme={null}
    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 theme={null}
    {
      "id": "f4515921-8fdf-4e3a-a981-ad7a6717a8aa",
      "label": "Tone instruction",
      "prompt": "Use a friendly, diplomatic tone",
      "source_language": "de"
    }
    ```
  </Tab>

  <Tab title="HTTP Request">
    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 theme={null}
    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 theme={null}
    {
      "id": "f4515921-8fdf-4e3a-a981-ad7a6717a8aa",
      "label": "Tone instruction",
      "prompt": "Use a friendly, diplomatic tone",
      "source_language": "de"
    }
    ```
  </Tab>
</Tabs>

### Replace a custom instruction

`PUT /v3/style_rules/{style_id}/custom_instructions/{instruction_id}`

Replace an existing custom instruction within a style rule list. All fields must be provided.

<Tabs>
  <Tab title="cURL">
    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: replace custom instruction theme={null}
    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 theme={null}
    {
      "id": "f4515921-8fdf-4e3a-a981-ad7a6717a8aa",
      "label": "Updated currency instruction",
      "prompt": "Put currency symbols after the numeric amount",
      "source_language": "en"
    }
    ```
  </Tab>

  <Tab title="HTTP Request">
    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: replace custom instruction theme={null}
    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 theme={null}
    {
      "id": "f4515921-8fdf-4e3a-a981-ad7a6717a8aa",
      "label": "Updated currency instruction",
      "prompt": "Put currency symbols after the numeric amount",
      "source_language": "en"
    }
    ```
  </Tab>
</Tabs>

#### Request body parameters

<ParamField body="label" type="string" required>
  The updated label for the custom instruction. Maximum length: 100 characters.
</ParamField>

<ParamField body="prompt" type="string" required>
  The updated instruction text. Maximum length: 300 characters.
</ParamField>

<ParamField body="source_language" type="string">
  Optional source language code for the custom instruction (e.g., `en`, `de`, `fr`).
</ParamField>

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

<Tabs>
  <Tab title="cURL">
    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 theme={null}
    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.
  </Tab>

  <Tab title="HTTP Request">
    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 theme={null}
    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.
  </Tab>
</Tabs>

## 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 theme={null}
curl -X POST 'https://api.deepl.com/v2/translate' \
--header 'Authorization: DeepL-Auth-Key [yourAuthKey]' \
--header 'Content-Type: application/json' \
--data '{
  "text": ["Das Treffen ist um 15:00 Uhr"],
  "source_lang": "DE",
  "target_lang": "EN",
  "style_id": "a74d88fb-ed2a-4943-a664-a4512398b994"
}'
```

<Info>
  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.
</Info>