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.
Recommended automatic routes
trustedrouter/auto starts with GLM 5.3 Flash, then GLM 5.3, followed by DeepSeek, Kimi, and the rest of the fallback pool. Your provider, privacy, and capability requirements still determine which routes qualify.
trustedrouter/cheap includes both GLM models alongside lower-cost alternatives. It orders the pool by published input plus output token prices, so GLM 5.3 remains a higher-cost fallback. Set provider.max_price to enforce your per-token price ceiling.
Provider settings
Add these optional settings inside the provider object in your API request. They control which providers can handle it. 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 | Effect | Values |
|---|---|---|
only | Allowlist. Candidates outside it are removed; an empty result is a 400. | Provider slugs (array or comma string) |
ignore | Blocklist, applied after only. | Provider slugs |
order | Soft preferred order while fallbacks are enabled; unlisted providers remain eligible afterward. Combine with allow_fallbacks: false or use only for a hard restriction. | Provider slugs |
allow_fallbacks | false serves only the single first candidate; a top-level allow_fallbacks is also accepted, and disagreeing values are a 400. | true (default) / false |
sort | Orders endpoints by tracked metrics. The default model partition preserves the primary and fallback model order; none sorts every endpoint together. | price, latency, throughput, or {
"by": "price",
"partition": "model|none"
} |
require_parameters | true removes endpoints that do not publish support for every model parameter present in the request. Without it, only tools, tool_choice and response_format filter routes, by what the catalog declares for the route and its model. | true / false (default) |
max_price | Hard maximum USD price per million prompt or completion tokens. Compared as integer microdollars. | {
"prompt": "0.15",
"completion": "0.40"
} |
preferred_max_latency | Prefers routes meeting the requested time to first token. A soft preference, not a timeout. | Seconds, or a percentile object |
preferred_min_throughput | Prefers routes meeting the requested output speed. Other eligible routes remain available for fallback. | Tokens per second, or a percentile object |
zdr | true restricts routing to endpoints with a tracked zero-data-retention guarantee. | true / false |
min_privacy | A hard privacy floor: no endpoint with the required tracked guarantee means a 400, never a downgrade. The confidential-only hostname requires the explicit value confidential. | any, no_store, zdr, confidential (aliases e2e, e2ee) |
data_collection | OpenRouter-compatible preference against providers that retain data; use min_privacy when the floor must be unrelaxable. | allow, deny |
usage | Restricts billing path — platform credits or your own upstream key. | credits, byok (aliases prepaid, bring-your-own-key; also accepted as usage_type or billing) |
jurisdiction | Restricts to providers headquartered in that jurisdiction. | us (also accepted as country, headquarters_country, provider_country) |
Unsupported options return 501
quantizationsandenforce_distillable_text- Non-token
max_priceunits sort: "exacto"
Error: 501 not_supported_in_alpha. Quantization metadata is available for reviewed endpoints; filtering by it is not implemented.
Published weight formats
Precision metadata API guide Model precision overview
Model pages and endpoint JSON include reviewed weight formats for Tinfoil, Privatemode, NEAR AI, and Chutes deployments. The same model can have different formats at different providers. Unreviewed endpoints return null and display Unknown.
Look up a model's endpoints
GET /v1/models/{author}/{slug}/endpoints The response includes quantization and trustedrouter.precision. In the catalog fetched with GET /v1/models?include=endpoints, find these at:
trustedrouter.endpoints[].quantization
trustedrouter.endpoints[].precision Read the precision metadata
The precision object links the published serving code and pinned model configuration, with a review date and model revision.
quantization- Names the primary format.
weight_formats,label,notes- Describe mixed formats and higher-precision exclusions.
kv_cache_dtype- Describes the cache separately. An FP8 cache does not imply FP8 weights.
Reviewed configuration, not per-request proof
This is a reviewed configuration snapshot, not per-request proof of the loaded weights.
evidence_type: published_serving_config
runtime_verified: falseProvider changes require a new review; workload attestation alone does not establish serving precision.
Performance preferences
Performance routing API guide Performance routing overview
Set your preferred speed
Following OpenRouter's provider-selection interface, use a number for p50 or an object with p50, p75, p90, and p99.
All supplied thresholds must be met to receive priority. Throughput p90 means a rate achieved by at least 90% of measured requests.
{
"provider": {
"preferred_max_latency": {"p90": 3},
"preferred_min_throughput": 40
}
}How measurements work
Measurements use successful streaming requests with reported token counts from the last five minutes, scoped to the gateway region and control-plane instance. Storage is bounded and routing adds no analytics query.
Cold instances and routes without recent measurements retain normal fallback ordering.
Preferences, not guarantees
These are best-effort preferences, not performance guarantees. Explicit provider order, model fallback order, privacy requirements, and allowlists still apply.
Performance preferences apply to synchronous Chat Completions, Responses, and Messages. Other endpoint types return 501 rather than accepting preferences they cannot measure.
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.
Unknown option
400 invalid_request_errorThe error names the exact field in error.param, such as provider.future_option.
Known but unavailable
501 not_supported_in_alphaThe 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" |
Suffixes take precedence
A suffix takes precedence over an explicit provider.sort in the same request.
Discover providers and verify requests
Find which providers serve a model, with privacy badges, prices, and live performance, on that model's page under models.
For programmatic discovery, use the models API:
GET /v1/modelsPinned requests still produce signed receipts naming the provider that actually served.