# 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.

**Pricing:** Metered: you pay exactly each call's cost at the selected model's rates (default Cohere: Rerank v3.5: $0.002 per search). Each model's rates are listed with the `model` parameter's options in the API schema.

**Endpoint:** `POST /v1/data/ai/rerank/run`

**Auth:** `Authorization: Bearer mk_live_...`

## Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `queries` | array | Yes | The search query, or several queries; each is ranked against the same documents and is one call. |
| `documents` | array | Yes | The documents to rank (up to 1,000). |
| `model` | string | No | 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. |
| `topN` | integer | No | Return only the best N documents for each query. Leave empty to rank them all. |

## Example

`?wait=true` holds the request open until the run finishes (up to 60s) and returns the rows inline: one request, no polling.

```bash
curl -X POST "https://api.mindcase.co/v1/data/ai/rerank/run?wait=true" \
  -H "Authorization: Bearer mk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"params":{"queries":["..."],"documents":["..."]}}'
```

```python
import requests

resp = requests.post(
    "https://api.mindcase.co/v1/data/ai/rerank/run",
    params={"wait": "true"},
    headers={"Authorization": "Bearer mk_live_YOUR_API_KEY"},
    json={"params": {
    "queries": [
        "..."
    ],
    "documents": [
        "..."
    ]
}},
)
rows = resp.json()["data"]
```

## Longer runs

If the run is still going at the 60s ceiling you get back `{ job_id, status: "running" }` instead of rows (same if the result is over 100 rows; those come back `truncated`). Poll with that `job_id`:

```bash
# 1) check status
curl https://api.mindcase.co/v1/jobs/JOB_ID \
  -H "Authorization: Bearer mk_live_YOUR_API_KEY"

# 2) when status == completed, fetch the rows
curl https://api.mindcase.co/v1/jobs/JOB_ID/results \
  -H "Authorization: Bearer mk_live_YOUR_API_KEY"
```

Full API reference (auth, jobs, balance, SDKs, MCP): https://mindcase.co/skills.md

## Response columns

| Field | Display 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 |
