Share your feedback on a new Style Rules endpoint!

Hey everyone! I'm a PM on the API team at DeepL, coming to you with the chance to help shape a new DeepL API 🙂

Background

Style rules let you define language-specific formatting and writing preferences (date formats, units of measure, active vs. passive voice, etc.) that get applied to your translations. With our recent release, you can now create and manage them via the API.

The available rules you can configure when creating a style rule depend on the target language. For example, a rule called writing_dates might exist for Italian, but be called date_format in French.

Right now there's no programmatic way to discover which rules are available for a given language before creating a style rule. We're designing a new endpoint to solve this (similar in spirit to the v3/languages beta that Mike shared recently), and I'd love your feedback on a couple of design decisions before we build it.

What we're planning

A new endpoint that lets you query available style rules per language. Something like:

GET /v3/style_rules/available_rules?language=fr

The response would include each rule's description (in English and the target language), available options, and examples where applicable. Here's an abridged sample for Spanish:

{
  "language": "es",
  "configured_rules": {
    "numbers": {
      "spelling_out_units": {
        "description": {
          "en": "When writing units of measure",
          "local": "Al escribir unidades de medida:"
        },
        "options": {
          "always_spell_out_units_of_measure": {
            "description": {
              "en": "Always spell out, with or without a numeral",
              "local": "Escribir siempre con letras"
            },
            "example": "Example: 4 kilos; algunos kilos"
          },
          "always_abbreviate_units_of_measure": {
            "description": {
              "en": "Always abbreviate, with or without a numeral",
              "local": "Usar siempre los símbolos"
            },
            "example": "Examples: 4 kg; algunos kg"
          }
        }
      }
    }
  }
}

Some rules only have a single option (like "use active voice"), in which case the rule and option descriptions are the same. Not all rules have examples.

Where I'd love your feedback

1. Dedicated endpoint vs. extending v3/languages.

   1. Does a separate endpoint make sense to you, or would you prefer a single place to get all language capability info?

   2. We considered adding this data to the existing v3/languages endpoint, which already tells you whether a language supports style rules.

   3. However, the rule catalog per language is significantly more verbose than any other product's data in that endpoint, and we think a dedicated endpoint gives us more flexibility to design the right response shape.

2. Response body shape:

   1. Looking at the sample above, does the structure make sense for how you'd use it? Is there anything missing, or anything you'd change?

   2. For context, our goal is to give you everything you need to build a UI or programmatic integration on top of style rules without hardcoding language-specific logic.

This endpoint doesn't exist yet, so now is the perfect time to shape it. Would love to hear from anyone who's working with style rules or planning to.

Thanks for reading!