# Rerank documents

> Scores how relevant each document is to a query, in the format of the rerank APIs of Cohere and Jina, with `qwen3-reranker-0.6b` (alias `qwen/qwen3-reranker-0.6b`). At most 1000 documents per request, a query of at most 4096 characters and about 300,000 tokens (the estimate below); the model reads each document with the query up to 8,192 tokens.

Source: https://docs.serenityedge.ai/docs/api/edge/rerank-documents/

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

Scores how relevant each document is to a query, in the format of the rerank APIs of Cohere and Jina, with `qwen3-reranker-0.6b` (alias `qwen/qwen3-reranker-0.6b`). At most 1000 documents per request, a query of at most 4096 characters and about 300,000 tokens (the estimate below); the model reads each document with the query up to 8,192 tokens.

The model reports no usage, so the request is billed on an estimate that the API writes into `usage`: for each document, `ceil((characters(query) + characters(document)) / 4)` tokens, added up, with characters counted as Unicode code points. Every document is scored and billed, also when `top_n` returns fewer. Output is not billed. Only Serenity Edge API keys can use this route. See the [Embeddings, rerank and redaction guide](https://docs.serenityedge.ai/docs/embeddings-rerank-and-redaction#rerank).

## Request body (`application/json`)

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `model` | string | yes | Id of the rerank model: `qwen3-reranker-0.6b`, or its alias `qwen/qwen3-reranker-0.6b`. `GET /v1/models?format=openai` lists it with `endpoints: ["/v1/rerank"]`. |
| `query` | string | yes | The query the documents are scored against, at most 4096 characters. It is counted once per document in the token estimate. At most 4096 characters. |
| `documents` | array of one of string, object | yes | The documents to score, 1 to 1000. At least 1 item. At most 1000 items. |
| `documents[] (Object).text` | string | yes |  |
| `top_n` | integer | no | Return only the `top_n` most relevant documents. Every document is still scored and billed. At least 1. |
| `return_documents` | boolean | no | Accepted for compatibility with Cohere and Jina clients; results never repeat the documents. Use `index`. |

Example:

```json
{
  "model": "qwen3-reranker-0.6b",
  "query": "Which city is the capital of Spain?",
  "documents": [
    "Madrid is the capital and largest city of Spain.",
    "Valencia is known for paella and the City of Arts and Sciences.",
    "Málaga lies on the Costa del Sol, in Andalucía."
  ],
  "top_n": 2
}
```

## Responses

### 200: The most relevant documents with their scores, the model id and the estimated tokens the request is billed on. The scores of the example are illustrative; its usage is the estimate for the example request (21 + 25 + 21 tokens).

Body (`application/json`): `RerankResponse`

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `results` | array of RerankResult (object) | yes | The `top_n` most relevant documents, or every document when `top_n` is not set. |
| `results[].index` | integer | yes | Position of the document in `documents`. |
| `results[].relevance_score` | number | yes | How relevant the document is to the query, between 0 and 1: the higher, the more relevant. Results are sorted from the most to the least relevant. |
| `model` | string | yes | `qwen3-reranker-0.6b`, also when the request named the alias. |
| `usage` | RerankUsage (object) | yes | The token estimate the request is billed on, written by the API into every answer: for each document, `ceil((characters(query) + characters(document)) / 4)`, added up, with characters counted as Unicode code points. |
| `usage.prompt_tokens` | integer | yes | Estimated input tokens, billed at the model's input price. |
| `usage.total_tokens` | integer | yes | Equal to `prompt_tokens`. |

### 400: The request was refused: a body that is not a JSON object, a missing or invalid `model`, `query`, `documents`, `top_n` or `return_documents`, more than 1000 documents, a query over 4096 characters, more than about 300,000 tokens, a model served on another route, or a request the model server could not process (`The model server rejected the request. Check the input sizes and parameters.`). `param` names the field at fault when there is one.

Body (`application/json`): `ErrorResponse`

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `error` | Error (object) | yes | OpenAI-style error object. |
| `error.message` | string | yes | Human-readable description of the problem. |
| `error.type` | string | yes | Error category. One of `invalid_request_error`, `authentication_error`, `permission_error`, `not_found_error`, `rate_limit_error`, `server_error`. |
| `error.code` | string or null | no | Machine-readable error code, when available. |
| `error.param` | string or null | no | The request parameter the error refers to, when applicable. |

### 401: Missing or invalid API key.

Body (`application/json`): `ErrorResponse`, the same fields as under 400.

### 403: The key is valid but cannot use this route: only Serenity Edge API keys can. Any other key, such as a key from a Serenity Star account, gets `permission_denied` with a message that names the route's API (`embeddings`, `rerank` or `redact`).

Body (`application/json`): `ErrorResponse`, the same fields as under 400.

### 404: The model id is unknown, or it is a chat or decision model, which cannot be used on this route (`model_not_found`).

Body (`application/json`): `ErrorResponse`, the same fields as under 400.

### 413: The request body is larger than this route accepts (4 MB, `request_too_large`).

Body (`application/json`): `ErrorResponse`, the same fields as under 400.

### 429: Rate limit exceeded, or the service is temporarily at capacity for this model. Wait for the number of seconds in the `Retry-After` header before retrying.

Header `Retry-After`: Seconds to wait before retrying.

Body (`application/json`): `ErrorResponse`, the same fields as under 400.

### 500: Unexpected server error: the model service returned an unexpected response (`upstream_error`), the request got no answer within 600 seconds (`timeout`), or an error in the gateway. Retry with backoff.

Body (`application/json`): `ErrorResponse`, the same fields as under 400.

### 503: The model service is temporarily unavailable (`upstream_unavailable`). Retry later and check the status page at https://status.serenityedge.ai.

Body (`application/json`): `ErrorResponse`, the same fields as under 400.