Provider Routing And Pinning
Pin, prefer, or exclude providers per request with the OpenRouter-compatible provider object: only, ignore, order, allow_fallbacks, sort, max_price, require_parameters, ZDR, and hard filters that fail closed.
Pin, prefer, or exclude providers per request.
Every Chat Completions and Responses request accepts a provider object that narrows which providers may serve it and in what order. Hard filters fail with 400 before inference when nothing matches. Unknown options also return 400. OpenRouter options recognized but not implemented by this release return 501 not_supported_in_alpha. Accepted router options never disappear silently.
Lists accept either a JSON array or one comma-separated string. Provider slugs are the ones on the providers page and in GET /v1/models.
only + no fallbacks
{
"model": "deepseek/deepseek-v4-pro",
"provider": {
"only": ["deepseek"],
"allow_fallbacks": false
}
}order
{
"model": "trustedrouter/auto",
"provider": {
"order": ["tinfoil", "chutes"],
"ignore": ["examplecorp"]
}
}Rejected field names and status codes are emitted as bounded operational metadata so compatibility demand can be measured. Field values, request bodies, prompts, and outputs are excluded, and Sentry remains outside the enclave.
The provider object
Every field is optional. Filters compose: only and ignore narrow the candidate set, order and sort arrange it, and allow_fallbacks decides whether anything past the first candidate may serve.
| Field | Values | Effect |
|---|---|---|
only | Provider slugs (array or comma string) | Allowlist. Candidates outside it are removed; an empty result is a 400. |
ignore | Provider slugs | Blocklist, applied after only. |
order | Provider slugs | Soft preferred order while fallbacks are enabled; unlisted providers remain eligible afterward. Combine with allow_fallbacks: false or use only for a hard restriction. |
allow_fallbacks | true (default) / false | false serves only the single first candidate; a top-level allow_fallbacks is also accepted, and disagreeing values are a 400. |
sort | price, latency, throughput, or {"by":"price","partition":"model|none"} | Orders endpoints by tracked metrics. The default model partition preserves the primary and fallback model order; none sorts every endpoint together. |
require_parameters | true / false (default) | true removes endpoints that do not publish support for every model parameter present in the request. |
max_price | {"prompt":"0.15","completion":"0.40"} | Hard maximum USD price per million prompt or completion tokens. Compared as integer microdollars. |
zdr | true / false | true restricts routing to endpoints with a tracked zero-data-retention guarantee. |
min_privacy | any, no_store, zdr, confidential (aliases e2e, e2ee) | A hard privacy floor: no endpoint with the required tracked guarantee means a 400, never a downgrade. |
data_collection | allow, deny | OpenRouter-compatible preference against providers that retain data; use min_privacy when the floor must be unrelaxable. |
usage | credits, byok (aliases prepaid, bring-your-own-key; also accepted as usage_type or billing) | Restricts billing path — platform credits or your own upstream key. |
jurisdiction | us (also accepted as country, headquarters_country, provider_country) | Restricts to providers headquartered in that jurisdiction. |
quantizations, preferred_max_latency, preferred_min_throughput, enforce_distillable_text, non-token max_price units, and sort: "exacto" are recognized OpenRouter controls but are not implemented yet. They return 501 not_supported_in_alpha rather than routing as if unset.
Parameter contract
TrustedRouter validates the current OpenRouter request field, provider field, and plugin names at the attested boundary. This catches spelling mistakes and API drift before authorization or billing.
400 invalid_request_error
The error names the exact field in error.param, such as provider.future_option.
501 not_supported_in_alpha
The field is part of OpenRouter's API, but this TrustedRouter release cannot honor it. The request stops before inference.
Model-id suffixes
Two OpenRouter-style shortcuts set provider.sort from the model id itself.
| Suffix | Equivalent |
|---|---|
deepseek/deepseek-v4-pro:nitro | provider.sort = "throughput" |
deepseek/deepseek-v4-pro:floor | provider.sort = "price" |
A suffix takes precedence over an explicit provider.sort in the same request. Discover which providers serve a model — with privacy badges, prices, and live performance — on that model's page under models, or programmatically via GET /v1/models. Pinned requests still produce signed receipts naming the provider that actually served.