Routing hints
Per-request fields that shape routing without changing your policy — a session id that keeps an agent loop on one model, and provider filters for a pinned model. Hints only narrow; none widens.
Your workspace policy and Routers decide what a request may use. Routing hints let one request add detail on top. They never widen what your policy allows.
No hint is forwarded to a provider. Stav reads them and strips them before the request goes upstream, so they cannot change the prompt or its cache prefix.
session_id — name the conversation
resp = client.chat.completions.create(
model="auto",
messages=[...],
extra_body={"session_id": "conv-8f21"},
)
Tells the Smart Router which conversation this request belongs to, so it can remember what it chose last turn. That is what lets an agent loop stay on the same model while tool calls are outstanding (see the continuity lock in Smart Router).
Accepted on /v1/chat/completions, /v1/messages and /v1/responses.
Stav resolves the conversation identity in this order and uses the first one present:
session_idin the body- the
X-Session-Idrequest header prompt_cache_keyin the body- a fingerprint of the conversation's opening
The value is hashed together with your workspace and API key, so two customers sending "default" never share state.
Responses may carry an X-Session-Id header. Send it back on the next request if you want session tracking to be exact rather than inferred.
provider — filter a pinned model
On /v1/chat/completions and /v1/messages, when you name a model, provider checks that model against your preferences:
client.chat.completions.create(
model="mistralai/mistral-small-4-119b-2603",
messages=[...],
extra_body={"provider": {
"only": ["mistral"],
"max_price": {"prompt": 2.0, "completion": 6.0},
}},
)
| Field | Effect |
|---|---|
only | Inference Provider slugs the model must be served by |
ignore | Inference Provider slugs to exclude |
max_price | Ceiling in EUR per million tokens: prompt, completion. Models with no price pass |
quantizations | Allowed quantisation levels. Models with no recorded level pass |
If the model does not pass, the request is refused rather than served elsewhere.
sort, require_parameters and allow_fallbacks are not supported. Sending any of them is a 400 unsupported_parameter naming the field.
Seeing what happened
| Header | Says |
|---|---|
X-Stav-Model | the model that served |
X-Stav-Route-Reason | why it was chosen |
X-Stav-Route-Lock | the continuity lock that held the route (tool_loop, signed_thinking), or none |
X-Session-Id | the conversation session id, when one was resolved |