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

# Rerank API

> Rank documents by how well they answer a query with the rerank model you pick (Cohere, Voyage, Qwen and more): one row per query and document with its rank and relevance score, the exact model version, its maker and its exact share of the call's cost. You pay exactly what each call costs at the model's own rate.

`POST /v1/data/ai/rerank/run`

**Pricing:** Metered: you pay exactly each call's cost at the selected model's rates (default Cohere: Rerank v3.5: the model's own rate).

## Request

Send the inputs under `params`. Only the keys below are accepted; any other key returns `422 invalid_params`.

**queries** `string[]` *required*

The search query, or several queries; each is ranked against the same documents and is one call.

**documents** `string[]` *required*

The documents to rank (up to 1,000).

**model** `string` (default: cohere/rerank-v3.5)

The rerank model. Pick from the list (popular models first). Each model shows its own rate (per search, or per 1M tokens), and that is exactly what each call costs.

Allowed values: `cohere/rerank-v3.5` (Cohere: Rerank v3.5), `cohere/rerank-5-fast` (Cohere: Rerank 5 Fast), `cohere/rerank-5-pro` (Cohere: Rerank 5 Pro), `cohere/rerank-4-pro` (Cohere: Rerank 4 Pro), `mongodb/rerank-3-lite` (VoyageAI by MongoDB: rerank-3-lite), `mongodb/rerank-3` (VoyageAI by MongoDB: rerank-3), `qwen/qwen3-reranker-0.6b` (Qwen3 Reranker 0.6B), `cohere/rerank-4-fast` (Cohere: Rerank 4 Fast), `qwen/qwen3-reranker-8b` (Qwen3 Reranker 8B), `mongodb/rerank-2.5` (VoyageAI by MongoDB: rerank-2.5), `mongodb/rerank-2.5-lite` (VoyageAI by MongoDB: rerank-2.5-lite).

**topN** `integer`

Return only the best N documents for each query. Leave empty to rank them all.

Min `1`; max `1000`.

## Example

```bash cURL theme={null}
curl -X POST "https://api.mindcase.co/v1/data/ai/rerank/run?wait=true" \
  -H "Authorization: Bearer $MINDCASE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "params": {
    "queries": [
      "How do I reset my password?"
    ],
    "documents": [
      "To reset your password, open Settings, choose Security and click Reset password.",
      "Our office is closed on public holidays.",
      "Invoices are emailed on the first day of each month."
    ],
    "model": "cohere/rerank-v3.5"
  }
}'
```

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

r = requests.post(
    "https://api.mindcase.co/v1/data/ai/rerank/run",
    params={"wait": "true"},
    headers={"Authorization": f"Bearer {os.environ['MINDCASE_API_KEY']}"},
    json={"params": {
    "queries": [
        "How do I reset my password?"
    ],
    "documents": [
        "To reset your password, open Settings, choose Security and click Reset password.",
        "Our office is closed on public holidays.",
        "Invoices are emailed on the first day of each month."
    ],
    "model": "cohere/rerank-v3.5"
}},
)
job = r.json()
rows = job.get("data", [])  # if job["status"] == "running", poll /v1/jobs/{job_id}/results
```

```javascript Node.js theme={null}
const r = await fetch("https://api.mindcase.co/v1/data/ai/rerank/run?wait=true", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.MINDCASE_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ params: {
  "queries": [
    "How do I reset my password?"
  ],
  "documents": [
    "To reset your password, open Settings, choose Security and click Reset password.",
    "Our office is closed on public holidays.",
    "Invoices are emailed on the first day of each month."
  ],
  "model": "cohere/rerank-v3.5"
} }),
});
const job = await r.json();
const rows = job.data ?? []; // if job.status === "running", poll /v1/jobs/{job_id}/results
```

## Response fields

Each row in `data` is one ranked document, keyed by these fields.

| Field | Name | Type |
| - | - | - |
| `id` | ID | text |
| `query` | Query | text |
| `document` | Document | text |
| `documentIndex` | Document Index | number |
| `rank` | Rank | number |
| `relevanceScore` | Relevance Score | number |
| `model` | Model | text |
| `provider` | Provider | text |
| `costUsd` | Cost (USD) | number |
| `error` | Error | text |
| `createdAt` | Created At | datetime |

## Example response

Abridged: long text and lists are shortened.

```json theme={null}
{
  "job_id": "7f3a1c2e-0b9d-4c55-9a51-3f2e8d1b6a40",
  "agent": "ai/rerank",
  "status": "completed",
  "row_count": 1,
  "truncated": false,
  "data": [
    {
      "rank": 1,
      "provider": "Cohere",
      "error": null,
      "model": "cohere/rerank-v3.5",
      "id": "gen-rerank-1794260962-o2btgDJae5kLLHWn2vP9-0",
      "documentIndex": 0,
      "query": "How do I reset my password?",
      "costUsd": 0.0002,
      "createdAt": "2026-11-09T21:49:23Z",
      "document": "To reset your password, open Settings, choose Security and click Reset password.",
      "relevanceScore": 0.81665546
    }
  ]
}
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.