API Reference

Rerank

Score documents against a query and return the most relevant results first. Use reranking after retrieval to improve the order of a candidate set.

Overview

The endpoint uses Jina- and Cohere-compatible request and response shapes. Reranking shares the embeddings service and model catalogue. Discover available reranker models with /v1/models?scope=embeddings, or select a specific service with service_id.

This endpoint requires the embeddings scope and records input-token usage; it does not generate output tokens.

Rerank documents

POST/v1/rerank

Scopeembeddings

Score each document against the query and return them sorted by descending relevance.

Request

modelrequiredstring: Reranker model id or alias. Discover options with GET /v1/models?scope=embeddings.
queryrequiredstring: The search query to rank the documents against.
documentsrequiredstring[] | {text}[]: Documents to rank: plain strings or { "text": "..." } objects, up to 1000 per request.
top_ninteger: Return only the N most relevant documents. Omitted means all documents come back, ranked.
return_documentsboolean: Echo each result’s document text back as results[].document.text. Defaults to false, so results carry only the index into your request array.
service_idstring: Optional. Route to a specific embeddings service (see GET /v1/services). Falls back to the org’s default embeddings service when omitted.

bash

curl https://api.inferada.com/v1/rerank \
  -H "Authorization: Bearer inf_YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "reranker",
    "query": "How do I rotate an API token?",
    "documents": [
      "Tokens can be created from the dashboard.",
      "Our office is closed on public holidays.",
      "Rotate a token by revoking it and issuing a replacement."
    ],
    "top_n": 2
  }'

Response · 200

objectstring: Always "list".
results[].indexnumber: Position of this document in the request’s documents array. Results are sorted by relevance, so use this to map back to your inputs.
results[].relevance_scorenumber: How relevant the document is to the query. Higher is more relevant; compare scores within one response rather than across models.
results[].document.textstring: The document text, present only when return_documents is true.
usage.prompt_tokensnumber: Input tokens consumed (equals total_tokens for rerank).

json

{
  "object": "list",
  "model": "reranker",
  "results": [
    { "index": 2, "relevance_score": 0.94 },
    { "index": 0, "relevance_score": 0.61 },
    { "index": 1, "relevance_score": 0.08 }
  ],
  "usage": { "prompt_tokens": 42, "total_tokens": 42 }
}

Errors

A 400 response means the query or document list is invalid, or the resolved model does not support reranking. A 404 response means the model is unknown or unavailable to your token. A 502 response means the reranking service failed; retry the request and contact support if the problem continues.