Rerank
POST https://api-staging.heimdallm.com/api/v1/rerankThe retrieval half of the embeddings rail: a query and a set of documents go in, and one relevance score per document comes back. Requires a bearer API key.
Routed only to models whose output modality is rerank — filter the model list or look for
"output_modalities": ["rerank"] in the catalogue. A model with no scoring head
is refused with 503 naming rerank_unsupported rather than being sent the request, because a
relevance ask answered in prose would be recorded against an endpoint that never offered the rail.
Routing and provider preferences otherwise work as on chat.
An image or video in the query or a document requires an endpoint declaring the corresponding input
modality. Text-only endpoints and endpoints with no input declaration are excluded. If none qualify, the API returns
503 with input_unsupported in the routing details, before calling a provider or reserving credit.
Plain strings and objects carrying only text require no visual input declaration. An instruction is sent
only to an endpoint that declares it; otherwise routing rejects the request.
Request body
| Field | Type | Notes |
|---|---|---|
model | string | Required. |
query | string / object | Required. Text, or an object carrying text, image, video, or a combination. |
documents | array | Required. Up to 2048 entries, each a string or an object carrying these content fields. |
top_n | integer | How many of the highest-scoring documents come back. Absent returns all of them. |
return_documents | boolean | Echo each result's document back beside its score, in the shape it was submitted. |
instruction | string | Optional task instruction; requires a seller that declares it. |
user | string (≤ 256) | Opaque end-user identifier. |
provider | object | Provider preferences. |
Other controls may be sent by name when a seller declares them. The model's endpoint listing shows
each seller's parameter_domains; routing refuses an undeclared name or a value outside that domain
before contacting the seller. ImpCC's Qwen3-VL reranker declares positive
truncate_prompt_tokens, truncation_side (left or right, with a token limit), nonnegative
max_tokens_per_query and max_tokens_per_doc, boolean use_activation, string cache_salt, and
chat_template_kwargs with optional instruction or instruct text. A future seller can publish a
different control without a new marketplace request field.
Example
curl https://api-staging.heimdallm.com/api/v1/rerank \
-H "Authorization: Bearer $HEIMDALL_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "baai/bge-reranker-v2-m3",
"query": "How many legs does a spider have?",
"documents": [
"A spider has eight legs.",
"The Danube flows through ten countries.",
"Bread dough rises because yeast releases carbon dioxide."
],
"top_n": 2
}'{
"id": "gen_01J8Z4K6V9",
"model": "baai/bge-reranker-v2-m3",
"provider": "ImpCC",
"results": [
{ "index": 0, "relevance_score": 0.9871 },
{ "index": 2, "relevance_score": 0.0142 }
],
"usage": { "search_units": 1, "total_tokens": 26, "cost": 0.000026 }
}
For an image query, use a model listing image input. The image value can be a URL or an inline data URL:
{
"model": "qwen/qwen3-vl-reranker-8b",
"query": { "image": "data:image/png;base64,<image bytes>" },
"documents": ["a red ceramic cube", "a blue chair"],
"instruction": "Match the image to the most accurate caption."
}
For a video query or document, use a model listing video input. The video value can be a URL or an
inline video data URL. A seller may declare image, video, both, or neither; routing checks each visual
input in the request separately.
Response fields
| Field | Type | Notes |
|---|---|---|
id | string | The generation id, also sent as X-Generation-Id. (Heimdallm) |
model | string | The model that served the request. |
provider | string | The serving provider's display name. (Heimdallm) |
results[].index | integer | Position of the scored document in the submitted documents array. |
results[].relevance_score | number | How well the document answers the query; higher is more relevant. |
results[].document | string / object | The submitted document, present only under return_documents. |
usage.search_units | integer | One query against up to 100 documents is one unit; ceil(documents / 100). |
usage.total_tokens | integer | Tokens the endpoint reported; omitted when it reported none. |
usage.cost | number | Exact charge in USD. (Heimdallm) |
Results arrive ordered by relevance_score, highest first, whatever order the endpoint answered in,
and are cut to top_n where one was named. Scores are comparable within one reply and not between
models: a reranker is trained to order documents, not to put them on a shared scale.
Billing
A rerank scores the query against every document, so one call consumes one token figure covering the
whole batch. It is billed per token where the endpoint publishes a prompt price and reports a count,
and per request where it publishes a request price; an endpoint publishing both is charged both.
Tokens consumed against no published price are recorded as unpriced rather than billed at zero, and
usage.total_tokens is omitted entirely when the endpoint reported no count — an unreported figure is
unknown, not none.
usage.search_units is reported for reconciliation against the Cohere search-unit shape and is not
itself charged. A request price coincides with one search unit only while a call carries at most 100
of the 2048 documents a request may carry.
The X-Generation-Id and X-Provider-Name headers are sent as on chat completions.