Rerank | OpenDunes Docs

Reranking takes a query and a list of candidate documents and returns them sorted by relevance score. It is the retrieval step that sits between a vector search (which returns approximate neighbours fast) and the model prompt (which needs the most relevant passages, not just the closest vectors).

The openai SDK has no rerank resource, so call POST /v1/rerank directly with fetch.

Usage#

TypeScript

const res = await fetch("https://opendunes.com/api/v1/rerank", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.OPENDUNES_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    model: "cohere/rerank-v3.5",
    query: "ما هي عاصمة الجزائر؟",
    documents: [
      "الجزائر العاصمة مدينة كبيرة على ساحل البحر الأبيض المتوسط.",
      "وهران هي المدينة الثانية في الجزائر.",
      "تمتد الصحراء الكبرى عبر جنوب الجزائر.",
    ],
    top_n: 2,
  }),
});
const { results } = await res.json();

// results: [{ index, relevance_score }, ...] sorted descending
for (const r of results) {
  console.log(r.relevance_score.toFixed(4), r.index);
}

Response shape#

Field	Description
`results`	Array sorted by `relevance_score` descending
`results[].index`	Original position in the `documents` array — the text itself is not echoed back
`results[].relevance_score`	Float 0–1; higher = more relevant
`usage.search_units`	Billing unit (falls back to `total_tokens` for token-billed rerankers)

Reranking is billed in DA per search unit (provider-dependent; token-billed models bill by total_tokens). Rates appear on each model's catalog page.

Also see#

Rerank API reference