API-referanse

Base-URL

https://api.stav.ai/v1

Last ned OpenAPI 3.1-filen på /docs/api/spec for Postman, Insomnia eller openapi-generator. Alle kall unntatt den offentlige katalogen trenger en API-nøkkel: se Autentisering.

The Stav AI API gives you OpenAI-compatible and Anthropic-compatible inference against a curated catalogue of commercial models, with routing, a per-workspace sovereignty floor, and a per-request audit trail.

Two SDK contracts, one API

• OpenAI-compatible (/v1/chat/completions, /v1/embeddings, /v1/models) — drop-in for the official OpenAI SDKs. Set base_url="https://api.stav.ai/v1" and your existing code works.
• Anthropic-compatible (/v1/messages) — drop-in for the official Anthropic SDK. Set base_url="https://api.stav.ai" (the SDK appends /v1 itself) and anthropic/claude-* models proxy verbatim to Anthropic (preserving cache_control, thinking, beta features). Every other catalogue model translates to the OpenAI Chat Completions contract under the hood — same call, same shape, different upstream.

Sovereignty model

Every inference response carries an X-Stav-Sovereignty-Level header with the effective sovereignty level of the endpoint that served the request, on Stav's graded L0–L4 ladder:

• L0 — foreign jurisdiction (served under third-country law, outside the EU/EEA guarantees).
• L1 — EU/EEA location: inference runs on EU/EEA soil.
• L2 — EU/EEA operation + certification.
• L3 — EU/EEA ownership & control of the serving operator.
• L4 — full sovereignty, no exceptions.
• UNCLASSIFIED — not yet assessed (a data-quality state, not a rung).

The same level is recorded on every request log entry, so your compliance evidence can state per request which rung served it.

Models are proxied through Stav from their upstream providers (OpenAI, Anthropic, Mistral, Google, xAI, Cohere and others). Stav holds the upstream relationship, so your traffic terms are governed by Stav's Terms of Service rather than the commercial vendor's, and every call is logged, billed and audit-trailed by Stav.

A routing floor is set per workspace (and optionally raised per router); it applies to routing decisions, and combines by taking the strictest value. See the sovereignty ladder.

Smart Router

Pass model="auto" to let Stav's Smart Router pick a model for the request, or @workspace-slug/router-slug to use a named routing policy your workspace authored. Selection scores the eligible pool on quality, expected request cost and measured end-to-end latency using your workspace's weights, after hard-filtering on your sovereignty floor, quality floor and the capabilities the request needs.

What the response tells you:

• model — the model that actually served, which may differ from what you sent.
• X-Stav-Model and X-Stav-Provider — the same, in headers.
• X-Stav-Route-Reason — a one-line, human-readable rationale. Prose; do not parse it.
• X-Stav-Router — the router that handled the request, when one did.
• X-Stav-Served-By: own-resource and X-Stav-Node-Id — the request was served by one of your own Stav Tunnel nodes (non-streaming only; usage costs €0).
• X-Stav-Reasoning-Effort — when the request carried a reasoning control, or the router chose one, the level the provider actually received (see reasoning_effort).
• X-Stav-Reasoning-Chosen-By — who chose that level: caller, router (the request set none and the Smart Router picked one) or provider_default.
• X-Stav-Upstream-Surface — the provider API that served the request (chat, responses or messages). See the header's own description for when it differs from the path you called.

The full decision — every candidate, its score, and the alternatives retained for failover — is in Your workspace: open the request in Monitor → Request log.

Request parameters

Stav does not silently drop parameters a provider cannot honour. A parameter is either honoured, or refused with a 400 (unsupported_parameter) naming the parameter and the model that resolved. An undeclared field is likewise refused by name.

Support is keyed by wire dialect, not vendor: the openai dialect also backs xAI, Cohere, Azure and OpenAI-compatible servers.

no-op — accepted and ignored on that dialect, never a 400. Stav — meant for Stav's router and forwarded to no provider.

Per-model capabilities are discoverable before you send anything — GET /v1/models/{model_id} returns stav_capabilities.

Rate limits

Default 300 requests/minute per production key (30 for test keys); a per-key override can change the number. Headers on a successful response report:

• X-RateLimit-Limit — the key's per-minute cap
• X-RateLimit-Remaining — requests left in this window
• X-RateLimit-Reset — Unix timestamp when the window rolls over

Exceeding the cap returns 429 with a Retry-After header.

Request IDs

Every response carries X-Stav-Request-Id — on a success it is the same value as the completion id. Quote it when contacting support.

Every error carries the same identifier twice: on the X-Stav-Request-Id header, and as error.request_id in the body. That holds for streaming errors too, where the SSE error frame carries error.request_id even though the HTTP status is 200.

Endepunkter