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-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
Stav extension. Same object as on /v1/chat/completions. On an explicitly named model, the model must pass only / ignore / max_price / quantizations or the request is refused. Never forwarded to Anthropic. sort, require_parameters and allow_fallbacks return 400.
Show 4 child fields
- onlyarray of string
- ignorearray of string
- max_priceobject
  Show 2 child fields
  - promptnumber
  - completionnumber
- quantizationsarray of string
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	API key lacks the required scope (e.g., `inference:messages`).
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-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
Stav extension. Same object as on /v1/chat/completions. On an explicitly named model, the model must pass only / ignore / max_price / quantizations or the request is refused. Never forwarded to Anthropic. sort, require_parameters and allow_fallbacks return 400.
Show 4 child fields
- onlyarray of string
- ignorearray of string
- max_priceobject
  Show 2 child fields
  - promptnumber
  - completionnumber
- quantizationsarray of string
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	API key lacks the required scope (e.g., `inference:messages`).
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": {}
}