Models

List what your key can call

curl https://api.stav.ai/v1/models \
  -H "Authorization: Bearer $STAV_API_KEY"

for m in client.models.list():
    print(m.id)

The list contains:

• auto first — the Smart Router, using your workspace's default Router
• every model your workspace may use and whose Inference Provider is currently available
• your workspace's Routers, as @workspace/router entries (owned_by: "stav")

It is "what this key can call now", not the whole catalogue. Requires inference:models.

Read one model

curl https://api.stav.ai/v1/models/anthropic/claude-sonnet-4-5 \
  -H "Authorization: Bearer $STAV_API_KEY"

{
  "id": "anthropic/claude-sonnet-4-5",
  "object": "model",
  "owned_by": "anthropic",
  "context_length": 200000,
  "max_completion_tokens": 64000,
  "top_provider": { "context_length": 200000, "max_completion_tokens": 64000 },
  "stav_category": "llm",
  "stav_context_window": 200000,
  "stav_supports_thinking": true,
  "stav_capabilities": {

The stav_* fields are extensions; the OpenAI SDK exposes them via model_extra.

context_length, max_completion_tokens and top_provider use OpenRouter's names, so code written for OpenRouter reads them unchanged.

Use them as a pre-flight check:

info = client.models.retrieve("anthropic/claude-sonnet-4-5")
caps = info.model_extra.get("stav_capabilities") or {}
if not caps.get("vision"):
    raise RuntimeError("this pipeline needs a vision model")

GET /v1/models/{id} takes anything you can send as model: the canonical creator/model id, a bare name with exactly one match (nb-whisper-large), or a Router (@your-workspace/router). The answer always carries the canonical id. A pinned endpoint (creator/model/provider) is not a model: find it on the model's /endpoints.

See every Provider Endpoint

Different Inference Providers serve the same model with different limits and precision. List them:

curl https://api.stav.ai/v1/models/openai/gpt-oss-120b/endpoints \
  -H "Authorization: Bearer $STAV_API_KEY"

{
  "data": {
    "id": "openai/gpt-oss-120b",
    "name": "gpt-oss-120b",
    "endpoints": [
      {
        "id": "openai/gpt-oss-120b/groq",
        "provider_name": "Groq",
        "tag": "groq",
        "context_length": 131072,
        "max_completion_tokens": 65536,
        "quantization": null,
        "pricing": { "currency": "EUR",

• The numbers in this example are illustrative. Call the endpoint for current values.
• The list holds only the endpoints your key can reach. Your workspace's policy applies: sovereignty floor, compute region, ZDR, blocked providers.
• The order is the order Stav tries them in.
• Send an entry's id as model to pin that endpoint.
• pricing is what a request on that endpoint is charged, per token, in your workspace's currency. It is the same price billing uses. stav_conditional_rates: true means the endpoint also has prices that depend on the request, such as long context.
• The shape matches OpenRouter's /api/v1/models/{author}/{slug}/endpoints.
• A Router works here too, and so does auto: GET /v1/models/@your-workspace/router/endpoints lists every endpoint of every model the Router can pick, under the Router's own rules (ZDR, region, floor) as well as your workspace's, best model first. Each entry's model_id names its model, and data.stav_router is true. The models come 100 to a page: ?page=2, and data.stav_total_models is the whole pool.

Model ids

creator/model

The canonical form. Copy it from /v1/models or the catalogue. When a model has more than one Provider Endpoint, Stav chooses among those your workspace's policy allows.

creator/model/provider

Pins one Inference Provider. Some providers serve the same model in more than one region; each region is its own Provider Endpoint, and creator/model/provider lets Stav use any of them that your workspace's policy allows. A pin narrows the choice; it never overrides your workspace's policy.

To pin one region, add its code after a colon: deepseek/deepseek-v3-2/amazon-bedrock:eu-west-2. GET /v1/models/{id}/endpoints lists every endpoint with its id and its stav_provider_region. Where an endpoint computes is stav_region (eu, eea, …) and stav_compute_countries, the same facts X-Stav-Compute-Region gives on a request.

Some Inference Providers also take a short name in the pin: baai/bge-m3/ovh pins the same endpoint as baai/bge-m3/ovhcloud-ai-endpoints. The short names are exact; Stav never guesses one. The policy decides on a short name exactly as it decides on the full slug.

• No endpoint with that slug → endpoint_not_found. The message lists the endpoints of the model you can pin, closest first, and says "Did you mean …?" when one is clearly the name you meant. Stav never sends the request to the suggested endpoint; send it again with that slug.
• The endpoint exists but cannot serve this request → endpoint_not_admissible. The message says which check refused it: the endpoint or your node is offline, its Inference Provider is not serving, it has no price in your workspace's currency, Stav Tunnel is off for your workspace, or a rule in your workspace policy (for example the compute country or zero data retention). Act on that check, or use the model slug alone to let Stav choose.

A few endpoints carry another variant after a colon, e.g. zai-org/glm-5-2/fireworks-ai:fast. Such a variant is not a region, and Stav uses it only when you name it.

Bare names and aliases

A name without a slash is resolved in order:

1. a registered alias — old slugs from before the creator/model rename, and ids the Inference Provider itself uses
2. the one active model whose id ends in /<name>

If two models share that last segment, the bare name matches nothing. Use creator/model in code you keep.

Unknown model

{
  "error": {
    "message": "The model 'openai/gpt-4o-turbo' does not exist. Call GET /v1/models to list the models your workspace can use.",
    "type": "invalid_request_error",
    "param": "model",
    "code": "model_not_found"
  }
}

A model that is on Stav but that you cannot call yet answers 404 model_not_published instead — a draft, a model that is coming soon, or one that is retired. The message says which. A model your workspace's policy excludes is a 403 model_not_permitted.

Browse the full catalogue

The public catalogue needs no key:

curl "https://api.stav.ai/v1/public/models?page_size=20"
curl "https://api.stav.ai/v1/public/providers"

In Your workspace, Connect → Models and Connect → Inference Providers show the same catalogue with pricing, sovereignty and endpoints. Use /v1/models for "what can this key call"; use the catalogue for everything else.

Filter by type

Every model has a type — the door it is served on: chat, embedding or transcription. The catalogue opens on Chat; pass category= to switch, and filter on the type's own facts with capability=:

# embedding models with at least 1024 dimensions that support Norwegian
curl "https://api.stav.ai/v1/public/models?category=embedding&capability=embedding_dimensions:>=1024,languages:no"

# transcription models with word timestamps, priced at or under €0.01 per audio minute
curl "https://api.stav.ai/v1/public/models?category=transcription&capability=stt_timestamps_word&max_price=0.01&price_unit=audio_minutes"

A capability term is a slug (vision_input), slug:>=N for a number, or slug:code for a list; an unknown slug, or a value the fact does not take, is refused by name (422). Each item carries price_from and price_unit in the type's own unit (tokens_in, request or audio_minutes), and type_counts says how many models of each type match the other filters. GET /v1/public/model-types lists the types with their filters, units and benchmark sets.

Pin or route?

• Pin a model when you reproduce an evaluation or a contract names the model.
• Pin an endpoint when you need one Inference Provider specifically.
• Use a Router for most production traffic: failover, cost and latency trade-offs, and a sovereignty floor set once for the workspace. Change the Router, not your code.

Next

• Smart Router
• Request parameters
• Sovereignty