DEVELOPER DOCUMENTATION

Routing

Price competition across approved providers, with exact model identity.

Exact versions stay separate

Model aliases only merge where the gateway advertises an unambiguous mapping. A similarly named model, quantization, dated revision, or variant is not assumed equivalent.

Fresh capacity

Marketplace floors include healthy, available venue-attested sellers and direct venue quotes. Unknown trust is excluded. Market snapshots older than three minutes are excluded from current savings and eligibility.

When a paid request uses a venue-attested marketplace quote, its approved-provider allow-list stays attached through dispatch for both streaming and non-streaming calls. A quote without a selectable approved provider is rejected before reserving credits. Catalog refreshes cannot widen the admitted provider list.

How a route is selected

The gateway estimates input and requested maximum output tokens, prices the eligible primary routes, and selects the least expensive. OpenRouter provides coverage when a primary does not advertise the model. This is not a guarantee of retrying every failed request.

Observation versus execution

A market floor shows the best observed offer. The router quote is the ceiling used for route selection and reservation. A venue’s estimated-discount path alone does not guarantee final rates or exclude its internal fallback providers.

Require a minimum discount

Send min_discount in a Chat Completions request. For example, 90 requires both input and output rates to be at least 90% below their respective direct-list rates. This is a rate constraint, not a percentage calculated from the final token mix or rounded chart labels.

{
  "model": "your-model-id",
  "messages": [
    {
      "role": "user",
      "content": "Hello!"
    }
  ],
  "max_tokens": 256,
  "min_discount": 90
}

Values are numbers from 0 to 100 with up to two decimal places, including 99.5. Zero requires prices no higher than direct list; omit the field for normal routing. Both streaming and non-streaming requests enforce the same policy, including sponsored :free requests.

The gateway uses quotes no older than three minutes and requires a nonzero direct reference for each rate. The executable quote must meet both limits, and the provider adapter must enforce those limits before execution across every internal fallback. An observed market floor alone does not qualify. Missing or unsupported guarantees return HTTP 503 with minimum_discount_not_met before reserving credits or calling a provider. Invalid values return HTTP 400.