Routing rules

A routing rule maps a caller request to a concrete (provider, model) pair. Rules are sorted by priority and evaluated in order; the first matching rule wins. If no rule matches, routeur.ai falls back to its built-in default for the requested alias.

Evaluation order

Filter to enabled rules.
Sort by priority descending.
Evaluate match against the request. First hit wins.
Apply the rule's action; record route_reason: "rule:<name>".

Example rule

Pin every request that asked for the alias demo-premium to openai/gpt-4o.

rule definition

{
  "name":        "premium_demo",
  "priority":    100,
  "enabled":     true,
  "action_kind": "pin",
  "match": { "requested_model": "demo-premium" },
  "action": {
    "provider": "openai",
    "model":    "gpt-4o"
  }
}

Rule fields

namestringrequired

Human identifier surfaced in trace metadata as rule:<name>.

priorityinteger

Higher numbers evaluate first. Ties broken by insertion order.

action_kindpin | auto

pin sends to a fixed pair. auto defers to routeur.ai's automatic picker.

match.requested_modelstring

Exact match against the caller's model field.

action.providerstring

Upstream provider identifier (openai, gemini, deepseek).

action.modelstring

Concrete upstream model id.

Per-request overrides

Two headers let a single request bypass rule evaluation:

Routeur-Provider — forces the provider.
Routeur-Model — forces the model id.

Overrides still run through DLP and output moderation.

← Request lifecycle

DLP →