Per-Request Override
The dz_router override -- steering one request inside the routing modes your team already enabled.
Per-Request Override
dz_router is a caller's steer for one request. It is the fourth and most
specific rung of the routing profile ladder, and it merges by the same
field-by-field rule: a field you omit is inherited from your team's
configuration, never cleared.
Carriers
The override rides exactly one of two carriers per request:
| Carrier | Status |
|---|---|
The X-Dz-Router request header, raw compact JSON, maximum 8192 bytes | Canonical. Send it through your SDK's default-headers mechanism. |
The dz_router body field | Compatibility alias. |
Presenting the override on both carriers is 400 dz_router_conflict -- even
if the two are byte-identical. There is deliberately no precedence rule: two
answers to one question is a bug in the caller, not an ambiguity to resolve.
Both carriers share one strict decoder. An unknown field is refused with
invalid_dz_router rather than ignored, because a typo must never silently do
nothing. The header is stripped with the other X-Dz-* headers before
forwarding, and the body field is stripped before the body is forwarded.
Fields
| Field | Type | Meaning |
|---|---|---|
fallback_models | array of author/slug ids, at most 4 | Replaces the configured fallback chain whole when non-empty; it is never appended to. Requires the profile to configure a chain or to enable auto. More than four entries is 400 invalid_dz_router, the same cap a profile save enforces. |
provider_sort | cost, latency or throughput | Provider ranking for the decided model. |
provider_order | array of provider names | Explicit provider preference order. |
provider_allow | array of provider names | Providers that may serve this request. |
provider_deny | array of provider names | Providers that may not serve this request. |
auto | object | Per-request auto-mode dials, forwarded to the auto resolver. Requires the profile to enable auto. |
upstream | string | Which registered upstream connector serves this request. An id the installation has not enabled is refused with 502 unknown_upstream. |
eligibility | object | Narrows which serving paths may serve this request, in the routing profile rule's own spelling (custody, regions, zero_data_retention, terms_classes, quantizations, max_prompt_usd_per_1m, max_completion_usd_per_1m). The one field that can only tighten the profile: a member that would re-admit what the profile excluded is ignored and recorded (routing_degraded carries eligibility_widening_ignored), never an error. Enforced only where the router chooses the serving path. |
There is deliberately no model field. The primary model stays the
surface's own model field -- the override steers around it rather than
replacing it.
Consent bounds the override
The rule is that a caller may steer inside a substitution mode the team enabled, but may not enable one:
| Override carries | Profile state | Result |
|---|---|---|
auto dials | Auto enabled | Applied. |
auto dials | Auto not enabled | 400 routing_override_not_permitted. |
fallback_models | A chain or auto is configured | Applied, replacing the chain for this request. |
fallback_models | Neither is configured | 400 routing_override_not_permitted. |
| Provider preferences | Any | Applied. Preferences are steering rather than substitution, so they are not gated. |
Provider enforcement is not the override's job either way: the boundary for
which providers may serve remains the allowed_providers rule on your
guardrail.
The OpenRouter spelling is a carrier too
A caller migrating from OpenRouter already writes its routing intent as a
top-level provider object, a top-level models list and the :nitro /
:floor model suffixes. The gateway's own router reads those fields, translates
them into the same override the two dz_router carriers decode to, applies them
across every upstream and strips them -- nothing OpenRouter-shaped is forwarded
as sent. The translation is strict for the reason dz_router is: a field the
router cannot honour is a 400, never dropped. It is also narrow-only: a
spelling the team did not design may restrict the profile but never widen it,
so its provider allow list intersects the profile's and its deny list adds to
it, where dz_router's own lists replace them.
Raw upstream routing fields are refused
The upstream's remaining routing knobs -- route, transforms, preset and
plugins -- are refused at the top level of every keyed inference body with
400 unsupported_routing_field. They never enter the API contract.
Examples
curl https://<your-gateway-host>/v1/chat/completions \
-H "Authorization: Bearer sk-dz-..." \
-H "Content-Type: application/json" \
-H 'X-Dz-Router: {"provider_sort":"latency","provider_deny":["some-provider"]}' \
-d '{
"model": "anthropic/claude-sonnet-4-5",
"messages": [{"role": "user", "content": "Hello"}]
}'In an SDK, send it through default_headers so it applies to every call
from that client, or per call where your SDK supports per-request headers.
When to use a profile instead
An override is the right tool for a decision that genuinely belongs to one request. It is the wrong tool for standing configuration:
- It is capped at 8192 bytes on the header, and an oversize value is refused with a message pointing at routing profiles.
- It cannot enable a mode, so a large override is usually an attempt to configure something that should be configured once, server-side.
- Which fields an override applied is recorded per request, so a fleet steering itself by header makes "why did this route here" a per-request question instead of a per-team answer.
See Routing profiles.
Auto Mode
Letting the platform choose the model for a request, and the two-part guarantee that keeps a delegated choice inside your allowlist.
Model Catalog and Providers
Browsing every model the gateway can route to, what each provider charges for it, and how to read a price that is absent rather than zero.