Reranking

POST /v1/rerank orders a list of documents by how well each answers a query. It is a drop-in replacement for Cohere Rerank, and it is the same reranker Hindsight uses for recall, tuned for agent memory: short factual snippets and questions about who did what, when.

Use it as the second stage of a search pipeline. Retrieve a generous candidate set with keyword or vector search, then rerank it and keep the top few.

Models

Model	Description	Price (input)
hs-decide-1-flash (default)	Hindsight's own decision model, tuned for agent memory. Returns rank positions.	$0.02 / 1M
hs-rerank-1	Cross-encoder reranker (mmBERT), multilingual.	$0.015 / 1M

Name the one you want with model; omit it to get hs-decide-1-flash.

Quick Start

curl

curl https://inference.hindsight.vectorize.io/v1/rerank \
  -H "Authorization: Bearer $HINDSIGHT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "hs-decide-1-flash",
    "query": "When did Caroline go to the support group?",
    "documents": [
      "Caroline is planning a camping trip next month.",
      "Caroline went to a support group on 7 May.",
      "Melanie painted a sunrise last year."
    ],
    "top_n": 1
  }'

Python (Cohere SDK)

import cohere

# The Cohere SDK appends /v1/rerank itself, so pass the host only.
co = cohere.ClientV2(
    api_key="<your Hindsight API key>",
    base_url="https://inference.hindsight.vectorize.io",
)

response = co.rerank(
    model="hs-decide-1-flash",
    query="When did Caroline go to the support group?",
    documents=[
        "Caroline is planning a camping trip next month.",
        "Caroline went to a support group on 7 May.",
        "Melanie painted a sunrise last year.",
    ],
)
for r in response.results:
    print(r.index, r.relevance_score)

Self-hosted Hindsight

Self-hosted Hindsight can rerank recall results with this API through its Cohere provider. Set:

HINDSIGHT_API_RERANKER_PROVIDER=cohere
HINDSIGHT_API_RERANKER_COHERE_BASE_URL=https://inference.hindsight.vectorize.io/v1/rerank
HINDSIGHT_API_RERANKER_COHERE_MODEL=hs-decide-1-flash
HINDSIGHT_API_RERANKER_COHERE_API_KEY=<your Hindsight API key>

Unlike the SDK, Hindsight's provider uses the base URL verbatim, so include /v1/rerank.

Request

Field	Type	Required	Description
query	string	Yes	The question or search text
documents	array	Yes	Up to 1,000 documents, each a string or an object with a text field
model	string	No	hs-decide-1-flash (the default) or hs-rerank-1
top_n	integer	No	Return only the best n results. Omit it to get a score for every document
return_documents	boolean	No	Include each document's text in the results
context	string	No	What every document shares, such as Current date: 2026-10-26. Decision models read it once, above the query, instead of on each document. Cross-encoder models ignore it
prune	boolean	No	Drop documents the model judges unhelpful. See Pruning

Documents longer than 4,096 tokens are truncated, not rejected. Sending more than 1,000 documents returns 400.

Response

{
  "id": "5b0c6a0e-…",
  "results": [
    { "index": 1, "relevance_score": 1.0 },
    { "index": 0, "relevance_score": 0.667 },
    { "index": 2, "relevance_score": 0.333 }
  ],
  "meta": {
    "api_version": { "version": "2" },
    "billed_units": { "search_units": 1, "input_tokens": 64 }
  }
}

results is sorted best first. index points back into the documents you sent. With return_documents: true, each result also has "document": {"text": "…"}.

Understanding Scores

Scores are rank positions, not probabilities

With hs-decide-1-flash, relevance_score reflects a document's position in the ranking. The best document scores 1.0, and scores step down evenly from there. A score of 0.5 means "ranked halfway down this list", not "50% relevant".

So a fixed threshold such as relevance_score > 0.7 keeps a fixed fraction of whatever you sent, relevant or not. To drop irrelevant documents, use prune or top_n instead.

Pruning

With "prune": true, documents the model judges unhelpful get a score of 0.0 and are removed from results: those barely helpful at all, or much less helpful than the best document. The best document always stays, so you get at least one result. Pruning reuses the ranking answers, so it costs nothing extra.

Use pruning when you would otherwise pass every reranked document on, for example into an LLM prompt, and want to keep only the ones that matter.

Billing

Reranking with hs-decide-1-flash costs $0.02 per 1M input tokens; the hs-rerank-1 cross-encoder costs $0.015 per 1M input tokens. Both count the query and the documents as sent to the model, and output is free. meta.billed_units.input_tokens reports exactly what was billed. See Pricing & billing.

search_units is reported for Cohere compatibility only. Billing uses input tokens.