Score documents by relevance to a query

Scores documents by relevance to a query with a reranker and returns them highest first. The request and answer shape are Cohere v2's, Jina's and vLLM's: change only the base URL (https://api.stav.ai/v1/rerank) and the key. Scope inference:rerank.

Name a model listed with the rerank surface on GET /v1/models; auto and Routers are refused (router_not_supported). Any field not listed here is refused by name (unsupported_parameter), and so is stream. 1 to 1,000 documents per request, strings or {"text"} objects (one form). top_n cuts the answer; return_documents echoes each result's text from your request.

Billing: one unit per request, the provider's own — per query where the endpoint is priced per query, else the input tokens the provider reports; never output tokens. usage.cost is the charge in the workspace currency, from Stav's own ledger (absent when the workspace's own key served the call). A provider answer with an out-of-range index or a score that is not a finite number is never returned in part: the next Provider Endpoint is tried, else 502 upstream_invalid_answer. The query and the documents are never stored outside a capture window the workspace opened.

Forespørselsinnholdapplication/json

• modelstringpåkrevd
• querystringpåkrevd

  What the documents are scored against.

• documentsarray of string | objectpåkrevd

  Strings, or objects with a text field — one form, not mixed.

  Vis 1 form

  Form 1

  • textstringpåkrevd
• providerobject

  Stav extension, region per request. Narrows where this one request may run and which Inference Providers may serve it, on top of your workspace policy — it can only narrow, never widen. It filters Provider Endpoints: the serving endpoint and every failover stay inside it, and when no endpoint of the model passes, the request is refused (403 endpoint_not_admissible, or provider_blocked when every endpoint is on a provider you named in ignore) and nothing is sent. A provider pinned in the model id (creator/model/provider) that the filter excludes is 400 invalid_value with param provider.

  Any other key is refused by name (400 unsupported_parameter, param provider.<key>). Never forwarded to a provider.

  Vis 4 underfelt

  • 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".

  • 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).

• top_ninteger

  Return only the best N documents (1 to the number of documents). Omit for every document, scored.

• return_documentsboolean

  Echo each result's text under document.text, from your request.

  Standard: false

Merknader

POST https://api.stav.ai/v1/rerank takes the same JSON as Cohere's v2 rerank API, Jina's and vLLM's /v1/rerank. A reranker reads a query and a list of documents and answers with each document's relevance score — the second step of retrieval, after your vector search returned candidates.

Coming from Cohere, Jina or a provider's own rerank API, change two things: the base URL (https://api.stav.ai/v1) and the key. With the Vercel AI SDK, use @ai-sdk/cohere with createCohere({ baseURL: "https://api.stav.ai/v1", apiKey }): its rerank() posts to {baseURL}/rerank.

Request

Any other field — stream, rank_fields, max_tokens_per_doc — is refused by name with 400 unsupported_parameter. Nothing is dropped silently.

Nothing is truncated either. A reranker reads the query with one document at a time, up to a token limit per model. Before the request leaves Stav, the query with its longest document is checked against that limit; if no Provider Endpoint of the model reads that much, the request is refused with 400 rerank_input_too_long and param names the document (documents[3]) or query. The check uses an estimate of about 4 bytes a token, so keep documents well below the limit: split long documents into passages.

Response

{
  "id": "rr-3f9c…",
  "model": "qwen/qwen3-reranker-8b",
  "results": [
    {"index": 0, "relevance_score": 0.97},
    {"index": 2, "relevance_score": 0.12}
  ],
  "usage": {"input_tokens": 41, "total_tokens": 41, "cost": 0.0000071, "cost_currency": "EUR"}
}

results is sorted by relevance_score, highest first, and cut to top_n. Each index is a position in the documents you sent. relevance_score is always between 0 and 1, so a threshold means the same on every Provider Endpoint and after a failover: where a provider scores on another scale (a raw logit), Stav maps its score to 0–1 with the logistic function, 1 / (1 + e^-score), and keeps the provider's order. usage.total_tokens equals usage.input_tokens: a reranker has no output tokens. On a provider priced per query, usage.search_units carries the provider's own unit count.

usage.cost is what your wallet is charged, in your workspace's currency, from Stav's own ledger — never the provider's own figure. It is absent when your workspace's own provider key (BYOK) served the call. The usual response headers come with it: the serving provider, its sovereignty level, the countries the documents may have been processed in, and X-Stav-Cost.

How it differs from chat

• Name the model. auto and Routers serve the chat surfaces only.
• Which models qualify. A model is callable here when a Provider Endpoint of it has been proven to rerank — Stav sends each endpoint one query and two documents with a known order and records whether the right document came first.
• The same policy wall. Compute country, zero data retention, no-training, the sovereignty floor and blocked providers apply exactly as on chat. Some rerankers are hosted in the US; a workspace whose policy excludes that is refused with the same codes as chat, and the refusal says why.
• Your key needs the inference:rerank scope. Without it: 403 insufficient_scope. A key with no scopes has full access.
• Billing. One unit per request, the provider's own: per query where the provider prices per query, else the input tokens the provider reports — never output tokens, never an estimate. A token-priced endpoint whose provider reports no token count is not callable. A failed request is not charged. See Credits and billing.
• Your data. The query and the documents are not kept in the request log, which records the document count and top_n. Inside a capture window you opened, the request and answer JSON are kept like a chat prompt.

Errors

Every error body has a top-level message beside error, with the same text as error.message. Cohere clients read the first, OpenAI clients the second.

Full catalogue: Errors.

On the model page

A reranker's page has a Try model button: a query, your documents (one per row, or pasted one per line), top_n, the documents re-ordered with a score bar each and their original position, the receipt with the cost, and Get code for the call you just ran.

Svarheadere

Feil

Alle feilkoder, hva de betyr og hva du gjør: Feil.