Rerank

Re-orders a list of documents by relevance to a query. Useful as the second stage of a RAG pipeline, after an initial vector search with Embeddings.

A separate paid product from chat — no free daily pool. Rate limit: 30 requests/min per account.

Request body

modelstringRequired

The rerank model id, e.g. cohere/rerank-4-fast, voyageai/rerank-2.5, or qwen/qwen3-reranker-8b. See Models.

querystringRequired

The search query to rank documents against.

documentsstring[]Required

A non-empty array of candidate documents (plain text) to re-order.

top_nintegerOptional

If set, only the top n ranked documents are returned instead of the full list.

curl https://api.dravenai.lat/v1/rerank \
  -H "Authorization: Bearer sk-drv-your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "cohere/rerank-4-fast",
    "query": "How do I authenticate against the Draven AI API?",
    "documents": [
      "Send an Authorization: Bearer sk-drv-... header.",
      "The console lets you manage billing and invoices.",
      "Rate limits are enforced per user, not per API key."
    ],
    "top_n": 2
  }'

import requests

response = requests.post(
    "https://api.dravenai.lat/v1/rerank",
    headers={"Authorization": "Bearer sk-drv-your-api-key"},
    json={
        "model": "cohere/rerank-4-fast",
        "query": "How do I authenticate against the Draven AI API?",
        "documents": ["Send an Authorization header.", "..."],
        "top_n": 2,
    },
)

const response = await fetch("https://api.dravenai.lat/v1/rerank", {
  method: "POST",
  headers: { "Authorization": "Bearer sk-drv-your-api-key", "Content-Type": "application/json" },
  body: JSON.stringify({
    model: "cohere/rerank-4-fast",
    query: "How do I authenticate against the Draven AI API?",
    documents: ["Send an Authorization header.", "..."],
    top_n: 2,
  }),
});

Response

200 OK

{
  "id": "rerank-...",
  "model": "cohere/rerank-4-fast",
  "results": [
    { "index": 0, "relevance_score": 0.94 },
    { "index": 2, "relevance_score": 0.31 }
  ],
  "pricing": { "unit": "per_mtoken", "usd_per_mtoken": 0.1, "usd_total": 0.0000032 }
}

index refers to the position of the document in the documents array you sent — results are sorted by relevance_score descending. Some models price per token (unit: "per_mtoken"), others per search (unit: "per_search"); check the pricing object in the response.

For error responses, see Errors.