POST /v1/rerank — Reorder Documents by Relevance

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

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.

string

required

The search query to rank documents against. The reranker scores each document by its relevance to this text.

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

integer

Return only the top N results by relevance score. If omitted, all documents are returned sorted by score.

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.

Example

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
  }'

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"))

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);
}

Response

{
  "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"
  }
}

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

object

Token count for the reranking pass: total_tokens.

object

Per-request environmental footprint. Fields: energy_kwh, carbon_g_co2, water_liters, renewable_percent, pue, provider_id, location.

object

Itemised cost: energy (EUR), credits deducted, and paid_with.

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.

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

Overview

Inference

Batch & Files

Models

POST /v1/rerank — Reorder Documents by Relevance

Endpoint

Parameters

Example

Response

​Endpoint

​Parameters

​Example

​Response

Endpoint

Parameters

Example

Response