# Rerank

Score a candidate list against a query and return it in relevance order — the
usual second stage after vector recall.

`POST /v1/rerank`

```bash
curl "https://sharellm.net/v1/rerank" \
  -H "Authorization: Bearer $SHARE_LLM_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "<model-id>",
    "query": "how does the platform verify a channel?",
    "documents": [
      "Base-URL certification pools and probe reports",
      "Unrelated text about image generation"
    ],
    "top_n": 1
  }'
```

## Request fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `model` | string | yes | Rerank model ID from the market. |
| `query` | string | yes | The search query. |
| `documents` | string[] | yes | Candidate passages to score. |
| `top_n` | integer | no | Return only the best n results. |
| `return_documents` | boolean | no | Include the passage text in each result. |

## Response

```json
{
  "results": [
    {"index": 0, "relevance_score": 0.93, "document": {"text": "..."}}
  ],
  "usage": {"total_tokens": 128}
}
```

## Billing

Rerank bills per call on the mode its model is configured for; the usage log row
shows the amount and the mode that applied.