> ## Documentation Index
> Fetch the complete documentation index at: https://docs.meliai.app/llms.txt
> Use this file to discover all available pages before exploring further.

# POST /v1/rerank — Reorder Documents by Relevance

> POST /v1/rerank — rerank a list of documents by relevance to a query using a cross-encoder model. Returns documents sorted by relevance score.

Reranking is a second-stage retrieval step that dramatically improves the precision of RAG pipelines. After a first-pass vector search returns a broad candidate set, a cross-encoder reranker reads both the query and each document together, producing a fine-grained relevance score that simple cosine similarity cannot capture. Submit your query and candidate documents to `/v1/rerank` and receive them back ordered from most to least relevant — ready to pass directly to your language model as context.

## Endpoint

```
POST https://api.meliai.ai/v1/rerank
```

**Authorization:** `Bearer sk-mel-<KEY>` via `Authorization` header.

***

## Parameters

<ParamField body="model" type="string" required>
  The reranking model ID to use. Cross-encoder models are listed under `GET /v1/models` with capability `rerank`. Routing flavor suffixes are supported.
</ParamField>

<ParamField body="query" type="string" required>
  The search query to rank documents against. The reranker scores each document by its relevance to this text.
</ParamField>

<ParamField body="documents" type="array" required>
  The candidate documents to rerank. Each element can be:

  * A plain string — the document text itself
  * An object with a `text` field — useful when you need to pass structured metadata alongside the text
</ParamField>

<ParamField body="top_n" type="integer">
  Return only the top N results by relevance score. If omitted, all documents are returned sorted by score.
</ParamField>

<ParamField body="return_documents" type="boolean">
  When `true`, the original document text is echoed back in each result object. Default: `false`. Set to `true` to avoid maintaining a separate lookup by index.
</ParamField>

***

## Example

<CodeGroup>
  ```bash curl theme={null}
  curl https://api.meliai.ai/v1/rerank \
    -H "Authorization: Bearer $MELIAI_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "model": "<RERANK_MODEL_ID>",
      "query": "European data protection",
      "documents": [
        "GDPR applies to all EU residents",
        "The Eiffel Tower is in Paris",
        "Data sovereignty is important for compliance"
      ],
      "top_n": 2
    }'
  ```

  ```python Python theme={null}
  import os
  import requests

  response = requests.post(
      "https://api.meliai.ai/v1/rerank",
      headers={"Authorization": f"Bearer {os.environ['MELIAI_API_KEY']}"},
      json={
          "model": "<RERANK_MODEL_ID>",
          "query": "European data protection",
          "documents": [
              "GDPR applies to all EU residents",
              "The Eiffel Tower is in Paris",
              "Data sovereignty is important for compliance",
          ],
          "top_n": 2,
          "return_documents": True,
      },
  )

  for result in response.json()["results"]:
      print(result["relevance_score"], result.get("document", {}).get("text"))
  ```

  ```javascript Node.js theme={null}
  const response = await fetch("https://api.meliai.ai/v1/rerank", {
    method: "POST",
    headers: {
      Authorization: `Bearer ${process.env.MELIAI_API_KEY}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      model: "<RERANK_MODEL_ID>",
      query: "European data protection",
      documents: [
        "GDPR applies to all EU residents",
        "The Eiffel Tower is in Paris",
        "Data sovereignty is important for compliance",
      ],
      top_n: 2,
      return_documents: true,
    }),
  });

  const data = await response.json();
  for (const result of data.results) {
    console.log(result.relevance_score, result.document?.text);
  }
  ```
</CodeGroup>

***

## Response

```json theme={null}
{
  "object": "list",
  "model": "<RERANK_MODEL_ID>",
  "results": [
    {
      "index": 0,
      "relevance_score": 0.9821,
      "document": {
        "text": "GDPR applies to all EU residents"
      }
    },
    {
      "index": 2,
      "relevance_score": 0.8743,
      "document": {
        "text": "Data sovereignty is important for compliance"
      }
    }
  ],
  "usage": {
    "total_tokens": 64
  },
  "environment_impact": {
    "energy_kwh": 0.000012,
    "carbon_g_co2": 0.0009,
    "water_liters": 0.00005,
    "renewable_percent": 93,
    "pue": 1.17,
    "provider_id": "provider-eu-west",
    "location": "Dublin, IE"
  },
  "billing_cost": {
    "energy": 0.000006,
    "credits": 0.000095,
    "paid_with": "credits"
  }
}
```

<ResponseField name="results" type="array">
  Array of result objects sorted from most to least relevant. Each contains:

  * `index` — position of the document in the original input array
  * `relevance_score` — float in `[0, 1]`, higher is more relevant
  * `document` — present only when `return_documents: true`; object with a `text` field
</ResponseField>

<ResponseField name="usage" type="object">
  Token count for the reranking pass: `total_tokens`.
</ResponseField>

<ResponseField name="environment_impact" type="object">
  Per-request environmental footprint. Fields: `energy_kwh`, `carbon_g_co2`, `water_liters`, `renewable_percent`, `pue`, `provider_id`, `location`.
</ResponseField>

<ResponseField name="billing_cost" type="object">
  Itemised cost: `energy` (EUR), `credits` deducted, and `paid_with`.
</ResponseField>

***

<Tip>
  In a typical RAG pipeline, retrieve the top 20–50 candidates via vector search, rerank them, and then pass the top 3–5 results as context to your language model. This keeps token usage low while maximising answer quality.
</Tip>

<Note>
  All reranking runs on GDPR-compliant European infrastructure. Document content never leaves the EU.
</Note>