Routing Rules

What a routing rule is

A routing rule is a saved set of routing preferences. Instead of sending the same provider object with every request, you save it once and point requests at the rule.

A rule can hold:

The provider fields are the ones described in Routing: order, only, ignore, allow_fallbacks, sort, quantizations and the data residency fields data_residency, eu_owned, max_retention_days, zdr and data_collection.

Create a rule in the dashboard

1. Open Routing in the dashboard and create a rule.
2. Pick a starting point (EU Compliance, Cost Saver or Low Latency) or configure it yourself.
3. Go through the four steps:
   • General: the rule's name, description and status.
   • Compliance: EU-owned providers only, data collection, data residency and maximum retention.
   • Models: a primary model and fallback models.
   • Providers: the optimization goal (sort), whitelisted providers (only), blacklisted providers (ignore) and whether to allow fallbacks.
4. Check the preview. It shows the request payload and, for each model, which providers are still available with your settings.
5. Save the rule, then copy its ID or name from the success screen.

A rule you create in the dashboard belongs to the workspace you are in. In an organization, you need the admin or owner role to manage rules.

You can also manage rules through the Routing Rules API.

Scopes

Every rule has a scope that decides who can use it:

A rule that isn't tied to a workspace applies in every workspace of its account. A rule tied to a workspace can't be used from another workspace: the request fails as if the rule didn't exist.

Apply a rule to a request

Add rule_id or rule_name to the request body:

curl https://api.eurouter.ai/api/v1/chat/completions \
  -H "Authorization: Bearer $EUROUTER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "rule_name": "EU Compliance",
    "messages": [{ "role": "user", "content": "Hello!" }]
  }'

rule_id and rule_name work on every inference endpoint: chat completions, completions, responses, messages, embeddings, rerank and audio.

• rule_id is the rule's UUID. It always points at one rule, so prefer it in production code.
• rule_name matches enabled rules by exact name. When more than one rule you can use has that name, EUrouter picks the API key's rule first, then your personal rule, then the organization's.
• When you send both, rule_id wins.

When you create a rule with a name that is already used in the same scope, EUrouter adds a number, such as EU Compliance 2.

With the OpenAI SDK

The OpenAI SDKs pass extra body fields through extra_body:

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["EUROUTER_API_KEY"],
    base_url="https://api.eurouter.ai/api/v1",
)

response = client.chat.completions.create(
    model="mistral-large-3",
    messages=[{"role": "user", "content": "Hello!"}],
    extra_body={"rule_name": "EU Compliance"},
)

Default rule for an API key

An API key can have a default routing rule. Set it under Default routing rule when you create or edit a key in the dashboard, or with default_routing_rule_id in the API Keys API.

Requests made with that key use the default rule unless they send their own rule_id or rule_name. This is the way to apply a rule to clients that can't add fields to the request body.

A default rule is stricter than a rule named in the request: its provider settings win over the request's provider settings (see below). You can't delete or disable a rule while it is an API key's default; clear the default on those keys first.

How a rule combines with the request

Models

• When the request sets model or models, the request's models are used and the rule's models are ignored.
• When the request sets neither, the rule's model or models are used.
• When neither sets a model, the workspace's default model is used for text requests, if the workspace has one.

Provider preferences

The request's provider object and the rule's provider are merged field by field:

Fields set on only one side are kept. For example, a rule with { "only": ["scaleway", "mistral"] } and a request with { "sort": "price" } route to the cheapest of Scaleway and Mistral.

Two exceptions always apply:

• Retention is never loosened. When both set zdr or max_retention_days, the strictest value applies.
• An unsupported sort doesn't replace the rule's sort. A request with sort: "exacto" keeps the rule's sort.

The workspace's default sort applies last, only when neither the rule nor the request sets sort.

Test a rule with a dry run

A dry run shows which providers a rule leaves for each model, without sending a request to a provider. The dashboard's preview uses it. Through the API:

curl https://api.eurouter.ai/api/v1/routing-rules/dry-run \
  -H "Authorization: Bearer $EUROUTER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "rule_name": "EU Compliance",
    "model": "mistral-large-3",
    "preference_overrides": { "sort": "price" }
  }'

The response has rule_applied, the merged effective_preferences, and per model the number of providers left and their slugs:

{
  "data": {
    "rule_applied": { "id": "3f1c…", "name": "EU Compliance" },
    "effective_preferences": { "eu_owned": true, "sort": "price" },
    "results": [{ "model": "mistral-large-3", "provider_count": 2, "providers": ["scaleway", "mistral"] }],
    "summary": { "total_models": 1, "models_with_providers": 1 }
  }
}

When the rule isn't found or is disabled, the dry run still answers, without the rule: rule_applied is null. Check it before you trust the result.

A model with provider_count: 0 can't be served with these settings.

Errors

A request that names a rule fails with a 400 when:

• the rule_id doesn't exist or isn't available to the account or workspace,
• no enabled rule you can use has that rule_name,
• the rule is disabled,
• the API key's default rule is disabled or no longer available.

See Error handling for the error format.