# Rerank

> Order documents by relevance to a query with a cross-encoder.

Source: http://localhost:3000/docs/endpoints/rerank

## Rerank: `POST /v1/rerank/`

Score documents against a query with a cross-encoder. Cost: 1 credit. Available on the free demo.

```bash
curl -X POST https://api.hushsearch.io/v1/rerank/ \
  -H "X-API-Key: hs_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "query": "how does RRF combine rankings?",
  "documents": [
    "Reciprocal rank fusion sums 1/(k + rank) across result lists.",
    "BM25 scores documents by term frequency and length.",
    "Cross-encoders read the query and document together."
  ],
  "top_n": 3
}'
```

Scores each document against the query and returns them best-first.

## Parameters

| Field | Type | Default | Notes |
|---|---|---|---|
| `query` | string | — | **Required.** |
| `documents` | string[] | — | **Required.** At least one. |
| `top_n` | integer | — | Return only the best N. |
| `return_documents` | boolean | `true` | Include document text in results. |

## Response

```json
{
  "model": "…",
  "results": [
    { "index": 1, "relevance_score": 0.91, "document": "HNSW builds a layered proximity graph…" },
    { "index": 0, "relevance_score": 0.12, "document": "Bananas are rich in potassium." }
  ],
  "credits_used": 1,
  "credits_remaining": 499,
  "response_time_ms": 140
}
```

`index` refers to the document's position in your request.
