API reference · Chat

Create a message (Anthropic-compatible)

POSThttps://api.stav.ai/v1/messages

Anthropic Messages API. Drop-in for the official Anthropic SDK — set base_url="https://api.stav.ai" (the SDK appends /v1) and api_key=sk_stav_live_....

Routing:

anthropic/claude-* models are proxied verbatim to api.anthropic.com. Full Messages-API fidelity including cache_control markers, extended thinking, and beta features.
Every other catalogue model is translated to the OpenAI Chat Completions contract and dispatched through the same path as /v1/chat/completions. model="auto" invokes the Smart Router.

Per-key rate limits apply. App attribution via the X-Stav-App-Id header is supported and recorded on the inference log.

Header parameters

X-Stav-Runs-Instring
Where this request may run, as a header: eu, eea, one ISO 3166 alpha-2 country code, or a comma-separated list of codes (NO, SE). The same values and the same meaning as the provider.runs_in body field, for clients that can set fixed headers but not body fields (an SDK's default_headers). It filters the Provider Endpoints that may serve and every failover; when none passes, the request is refused (403 endpoint_not_admissible) and nothing is sent.

It only ever narrows. Sent together with provider.runs_in, both must hold: X-Stav-Runs-In: eea with "runs_in": "NO" runs in Norway; X-Stav-Runs-In: eu with "runs_in": "NO" or "US" has no country in common and is 400 invalid_value. It never widens your workspace policy. A value Stav cannot read, an empty one, or two header lines with different values is 400 invalid_value with param X-Stav-Runs-In; the same value sent twice counts once. The request log shows the region with its source.

GET /v1/models lists only models with an endpoint inside it, and a Router or auto only when at least one of its candidates has one (without a key, auto is not listed under the header); GET /v1/models/{model_id}/endpoints lists only those endpoints. /v1/messages/count_tokens reads it too: when the provider's own counter is outside it, the count is a local estimate and the prompt is never sent. The response header X-Stav-Token-Count says exact or estimate. Reading or cancelling a stored response (GET /v1/responses/{id}, /input_items, /cancel) held by an endpoint outside it is refused with 403 endpoint_not_admissible; DELETE is not refused, so data held outside the region can always be erased.
X-Stav-App-Idstring
Optional app slug for attribution on the inference log.

Request bodyapplication/json

modelstringrequired
max_tokensintegerrequired
messagesarray of objectsrequired
Show 2 child fields
- roleenumrequired
  userassistant
- contentstring | array of objectrequired
systemstring | array of object
temperaturenumber
top_pnumber
top_kinteger
streamboolean
Default: false
stop_sequencesarray of string
providerobject
The provider object on the chat surfaces (/v1/chat/completions, /v1/messages, /v1/responses): the fields of RequestProviderFilter, plus max_price and quantizations, which filter the endpoints that may serve — the pick and every failover stay inside them — and sort, which orders a named model's endpoints. When no endpoint passes, the request is refused (403 endpoint_not_admissible, naming the field) and nothing is sent upstream. require_parameters and allow_fallbacks are refused by name (400 unsupported_parameter), as is any other key. On /v1/messages it is never forwarded to Anthropic. The other surfaces take only RequestProviderFilter.
Show 7 child fields
- runs_instring | array of string
  Where the request may run: "eu", "eea", one ISO 3166 alpha-2 country code, or a list of country codes (["NO", "SE"]). One region or countries, not both in one list. global endpoints satisfy no region, so most Claude and Gemini endpoints are excluded by "eu". The X-Stav-Runs-In header takes the same values; sent with this field, both must hold.
- regionstring | array of string
  Alias of runs_in, same meaning. Not a provider region code — those are chosen in the model id (creator/model/provider:<code>). Sending both with different values is 400 invalid_value.
- onlyarray of string
  Only endpoints of these Inference Providers serve (slugs, as listed by GET /v1/models/{model_id}/endpoints). Applies to the endpoint, whoever the model's provider of record is. An unknown slug is 400 invalid_value.
- ignorearray of string
  No endpoint of these Inference Providers serves (slugs).
- max_priceobject
  The highest price an endpoint may charge, per 1M tokens, in your workspace's billing currency — the price shown by GET /v1/models/{model_id}/endpoints. Every rate the request can be billed at without asking for it counts: a conditional rate (a long prompt, an image in or out) and the reasoning output rate. A service tier or prompt-cache write you ask for does not. An endpoint whose price is not known does not pass. An empty object sets no ceiling; any key other than prompt and completion is 400 unsupported_parameter.
  Show 2 child fields
  - promptnumber
    Input tokens.
  - completionnumber
    Output tokens.
- quantizationsarray of string
  Only endpoints serving one of these quantizations (fp8, bf16, int4, …; any case). Read from the endpoint, else from the model. An endpoint whose quantization is not known does not pass. An empty list sets no filter.
- sortenum
  Order the endpoints of the model you named. price: the lowest expected cost of this request first, priced at your workspace's own rates (the rates you are billed at). latency: the lowest time to first token first. throughput: the most tokens per second first. An endpoint with no figure goes last. Failover follows the same order.
  
  It only orders the endpoints the other fields and your workspace policy admit; it never adds one. Without sort Stav picks the endpoint by live speed. With model: "auto" or a Router it is 400 unsupported_parameter — the Router's objective chooses there.
  pricelatencythroughput
toolsarray of objects
Tool definitions. On a non-Claude model, server tools (any type other than custom, e.g. web_search_20250305) are dropped and named in the X-Stav-Dropped-Params response header, together with tool_choice when it pointed at one. Tools with an input_schema are passed on.
Show 4 child fields
- namestringrequired
- input_schemarequired
  JSON Schema 2020-12 document for the tool's input.
- descriptionstring
- cache_controlobject
  Show 1 child field
  - typestring
tool_choiceobject
Show 3 forms
Form 1
- typestring
Form 2
- typestring
Form 3
- typestringrequired
- namestringrequired
thinkingobject
Extended thinking config (Anthropic models only).
Show 2 child fields
- typeenum
  enableddisabled
- budget_tokensinteger
metadataobject
Show 1 child field
- user_idstring

Response headers

Header	Meaning
`X-Stav-Request-Id`	Unique request identifier, identical to the completion `id`. Quote this when contacting support. Emitted on successful responses only.
`X-Stav-Model`	The model that actually served the request — not necessarily the one you asked for, when routing or failover intervened.
`X-Stav-Provider`	The provider that served the request.
`X-Stav-Sovereignty-Level`	The effective sovereignty level (L0–L4 ladder) of the endpoint that served this request. `UNCLASSIFIED` means the serving endpoint has not been assessed yet (a data-quality state, not a rung). The same value is recorded on the request log entry.
`X-Stav-Reasoning-Effort`	Present when the request carried a reasoning control (`reasoning_effort` / `reasoning` / `thinking` on Chat Completions, `reasoning.effort` on Responses, `output_config.effort` or `reasoning_effort` on Messages). The reasoning level the provider actually received: your level, or the nearest level the serving endpoint accepts on this API (equal distance goes to the lower level), after provider translation. `fixed` when the provider's reasoning has no level (Mistral). On a streaming response it describes the first endpoint tried; the request log records the endpoint that answered after a failover.
`X-Stav-Reasoning-Chosen-By`	Who chose the reasoning level the provider received: `caller` (the request carried one), `router` (the request carried none and the Smart Router picked one for the model it chose — never above the model's default unless the Router allows it) or `provider_default` (nothing was sent; the provider ran at its own default). Present on every chat-surface response.
`X-Stav-Upstream-Surface`	The provider API that served the request: `chat`, `responses` or `messages`. It differs from the path you called when Stav translated the request, or sent it to another API of the same Provider Endpoint because only that API delivers a capability you asked for (for example tools with your `reasoning_effort`). Stav never changes a parameter you sent and never moves the request to another endpoint; a Responses upstream always gets `store: false`. When no API of the endpoint can deliver the capability, the request is refused with 400 `capability_unreachable`. On a streaming response it describes the first endpoint tried.

Errors

Status	When
400	Invalid request — malformed JSON, missing required fields, or invalid parameter values.
401	Missing or invalid API key.
403	The API key lacks the required scope, or a Decision Router matched a case that blocks the request (`blocked_by_case`). A blocked request called no answer model; the answer is not billed, the decision step is. A streaming request gets the same 403 before any event. See Route requests by case.
404	Model id is not in the catalogue, or the caller's key doesn't have access to it.
429	Per-key or per-IP rate limit exceeded.
502	An upstream provider (Anthropic, OpenAI, etc.) returned an error.
503	Upstream Anthropic credential not configured on this deployment.

Every error code, what it means and what to do: Errors.

curl -X POST https://api.stav.ai/v1/messages \
  -H "Authorization: Bearer $STAV_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "anthropic/claude-sonnet-4-5",
    "max_tokens": 1024,
    "messages": [
      {
        "role": "user",
        "content": "Summarise CLOUD Act Section 102."
      }
    ]
  }'

Response · 200

{
  "id": "msg_01XYZ...",
  "type": "message",
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "string"
    }
  ],
  "model": "string",
  "stop_reason": "end_turn",
  "usage": {}
}

Create a message (Anthropic-compatible)

POSThttps://api.stav.ai/v1/messages

Anthropic Messages API. Drop-in for the official Anthropic SDK — set base_url="https://api.stav.ai" (the SDK appends /v1) and api_key=sk_stav_live_....

Routing:

anthropic/claude-* models are proxied verbatim to api.anthropic.com. Full Messages-API fidelity including cache_control markers, extended thinking, and beta features.
Every other catalogue model is translated to the OpenAI Chat Completions contract and dispatched through the same path as /v1/chat/completions. model="auto" invokes the Smart Router.

Per-key rate limits apply. App attribution via the X-Stav-App-Id header is supported and recorded on the inference log.

Header parameters

X-Stav-Runs-Instring
Where this request may run, as a header: eu, eea, one ISO 3166 alpha-2 country code, or a comma-separated list of codes (NO, SE). The same values and the same meaning as the provider.runs_in body field, for clients that can set fixed headers but not body fields (an SDK's default_headers). It filters the Provider Endpoints that may serve and every failover; when none passes, the request is refused (403 endpoint_not_admissible) and nothing is sent.

It only ever narrows. Sent together with provider.runs_in, both must hold: X-Stav-Runs-In: eea with "runs_in": "NO" runs in Norway; X-Stav-Runs-In: eu with "runs_in": "NO" or "US" has no country in common and is 400 invalid_value. It never widens your workspace policy. A value Stav cannot read, an empty one, or two header lines with different values is 400 invalid_value with param X-Stav-Runs-In; the same value sent twice counts once. The request log shows the region with its source.

GET /v1/models lists only models with an endpoint inside it, and a Router or auto only when at least one of its candidates has one (without a key, auto is not listed under the header); GET /v1/models/{model_id}/endpoints lists only those endpoints. /v1/messages/count_tokens reads it too: when the provider's own counter is outside it, the count is a local estimate and the prompt is never sent. The response header X-Stav-Token-Count says exact or estimate. Reading or cancelling a stored response (GET /v1/responses/{id}, /input_items, /cancel) held by an endpoint outside it is refused with 403 endpoint_not_admissible; DELETE is not refused, so data held outside the region can always be erased.
X-Stav-App-Idstring
Optional app slug for attribution on the inference log.

Request bodyapplication/json

modelstringrequired
max_tokensintegerrequired
messagesarray of objectsrequired
Show 2 child fields
- roleenumrequired
  userassistant
- contentstring | array of objectrequired
systemstring | array of object
temperaturenumber
top_pnumber
top_kinteger
streamboolean
Default: false
stop_sequencesarray of string
providerobject
The provider object on the chat surfaces (/v1/chat/completions, /v1/messages, /v1/responses): the fields of RequestProviderFilter, plus max_price and quantizations, which filter the endpoints that may serve — the pick and every failover stay inside them — and sort, which orders a named model's endpoints. When no endpoint passes, the request is refused (403 endpoint_not_admissible, naming the field) and nothing is sent upstream. require_parameters and allow_fallbacks are refused by name (400 unsupported_parameter), as is any other key. On /v1/messages it is never forwarded to Anthropic. The other surfaces take only RequestProviderFilter.
Show 7 child fields
- runs_instring | array of string
  Where the request may run: "eu", "eea", one ISO 3166 alpha-2 country code, or a list of country codes (["NO", "SE"]). One region or countries, not both in one list. global endpoints satisfy no region, so most Claude and Gemini endpoints are excluded by "eu". The X-Stav-Runs-In header takes the same values; sent with this field, both must hold.
- regionstring | array of string
  Alias of runs_in, same meaning. Not a provider region code — those are chosen in the model id (creator/model/provider:<code>). Sending both with different values is 400 invalid_value.
- onlyarray of string
  Only endpoints of these Inference Providers serve (slugs, as listed by GET /v1/models/{model_id}/endpoints). Applies to the endpoint, whoever the model's provider of record is. An unknown slug is 400 invalid_value.
- ignorearray of string
  No endpoint of these Inference Providers serves (slugs).
- max_priceobject
  The highest price an endpoint may charge, per 1M tokens, in your workspace's billing currency — the price shown by GET /v1/models/{model_id}/endpoints. Every rate the request can be billed at without asking for it counts: a conditional rate (a long prompt, an image in or out) and the reasoning output rate. A service tier or prompt-cache write you ask for does not. An endpoint whose price is not known does not pass. An empty object sets no ceiling; any key other than prompt and completion is 400 unsupported_parameter.
  Show 2 child fields
  - promptnumber
    Input tokens.
  - completionnumber
    Output tokens.
- quantizationsarray of string
  Only endpoints serving one of these quantizations (fp8, bf16, int4, …; any case). Read from the endpoint, else from the model. An endpoint whose quantization is not known does not pass. An empty list sets no filter.
- sortenum
  Order the endpoints of the model you named. price: the lowest expected cost of this request first, priced at your workspace's own rates (the rates you are billed at). latency: the lowest time to first token first. throughput: the most tokens per second first. An endpoint with no figure goes last. Failover follows the same order.
  
  It only orders the endpoints the other fields and your workspace policy admit; it never adds one. Without sort Stav picks the endpoint by live speed. With model: "auto" or a Router it is 400 unsupported_parameter — the Router's objective chooses there.
  pricelatencythroughput
toolsarray of objects
Tool definitions. On a non-Claude model, server tools (any type other than custom, e.g. web_search_20250305) are dropped and named in the X-Stav-Dropped-Params response header, together with tool_choice when it pointed at one. Tools with an input_schema are passed on.
Show 4 child fields
- namestringrequired
- input_schemarequired
  JSON Schema 2020-12 document for the tool's input.
- descriptionstring
- cache_controlobject
  Show 1 child field
  - typestring
tool_choiceobject
Show 3 forms
Form 1
- typestring
Form 2
- typestring
Form 3
- typestringrequired
- namestringrequired
thinkingobject
Extended thinking config (Anthropic models only).
Show 2 child fields
- typeenum
  enableddisabled
- budget_tokensinteger
metadataobject
Show 1 child field
- user_idstring

Response headers

Header	Meaning
`X-Stav-Request-Id`	Unique request identifier, identical to the completion `id`. Quote this when contacting support. Emitted on successful responses only.
`X-Stav-Model`	The model that actually served the request — not necessarily the one you asked for, when routing or failover intervened.
`X-Stav-Provider`	The provider that served the request.
`X-Stav-Sovereignty-Level`	The effective sovereignty level (L0–L4 ladder) of the endpoint that served this request. `UNCLASSIFIED` means the serving endpoint has not been assessed yet (a data-quality state, not a rung). The same value is recorded on the request log entry.
`X-Stav-Reasoning-Effort`	Present when the request carried a reasoning control (`reasoning_effort` / `reasoning` / `thinking` on Chat Completions, `reasoning.effort` on Responses, `output_config.effort` or `reasoning_effort` on Messages). The reasoning level the provider actually received: your level, or the nearest level the serving endpoint accepts on this API (equal distance goes to the lower level), after provider translation. `fixed` when the provider's reasoning has no level (Mistral). On a streaming response it describes the first endpoint tried; the request log records the endpoint that answered after a failover.
`X-Stav-Reasoning-Chosen-By`	Who chose the reasoning level the provider received: `caller` (the request carried one), `router` (the request carried none and the Smart Router picked one for the model it chose — never above the model's default unless the Router allows it) or `provider_default` (nothing was sent; the provider ran at its own default). Present on every chat-surface response.
`X-Stav-Upstream-Surface`	The provider API that served the request: `chat`, `responses` or `messages`. It differs from the path you called when Stav translated the request, or sent it to another API of the same Provider Endpoint because only that API delivers a capability you asked for (for example tools with your `reasoning_effort`). Stav never changes a parameter you sent and never moves the request to another endpoint; a Responses upstream always gets `store: false`. When no API of the endpoint can deliver the capability, the request is refused with 400 `capability_unreachable`. On a streaming response it describes the first endpoint tried.

Errors

Status	When
400	Invalid request — malformed JSON, missing required fields, or invalid parameter values.
401	Missing or invalid API key.
403	The API key lacks the required scope, or a Decision Router matched a case that blocks the request (`blocked_by_case`). A blocked request called no answer model; the answer is not billed, the decision step is. A streaming request gets the same 403 before any event. See Route requests by case.
404	Model id is not in the catalogue, or the caller's key doesn't have access to it.
429	Per-key or per-IP rate limit exceeded.
502	An upstream provider (Anthropic, OpenAI, etc.) returned an error.
503	Upstream Anthropic credential not configured on this deployment.

Every error code, what it means and what to do: Errors.

curl -X POST https://api.stav.ai/v1/messages \
  -H "Authorization: Bearer $STAV_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "anthropic/claude-sonnet-4-5",
    "max_tokens": 1024,
    "messages": [
      {
        "role": "user",
        "content": "Summarise CLOUD Act Section 102."
      }
    ]
  }'

Response · 200

{
  "id": "msg_01XYZ...",
  "type": "message",
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "string"
    }
  ],
  "model": "string",
  "stop_reason": "end_turn",
  "usage": {}
}