The second pass that fixes retrieval

The call

curl https://freemodel.online/v1/rerank \
  -H "Authorization: Bearer sk-your-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "auto/rerank",
    "query": "how do I rotate an API key?",
    "documents": [
      "Keys can be rotated from the console.",
      "Billing is metered per request.",
      "Rotating a key invalidates the old one immediately."
    ],
    "top_n": 2
  }'

{
  "results": [
    { "index": 2, "relevance_score": 0.93 },
    { "index": 0, "relevance_score": 0.71 }
  ],
  "usage": { … }
}

index refers to the position in your documents array — the API does not echo the text back unless you ask for it. Pass return_documents: true and each result gains a document field.

Where this fits

The usual shape of a retrieval pipeline is two stages. First a fast approximate search — embeddings, an index, a top_k that is deliberately generous, because recall matters more than precision at this step. Then a slower, more accurate pass over those candidates.

auto/rerank is the second stage. It is worth adding when your top_k is larger than what you actually feed the model — which is most of the time, because the good answer is usually somewhere in the top twenty and rarely at position one.

It pairs with the embedding alias: embed once, store the vectors, then rerank at query time.

Request fields

One model sits behind the alias. A reranking model swap reorders your results without telling you — the same query returns a different ranking, and nothing in the response looks unusual. Failing is the safer behaviour.

Related capabilities

Same naming scheme, one alias per capability — all listed in /v1/models: