Order results by relevance
Score candidate documents against a query with a cross-encoder and get them back ranked.
How it works
- 01
Find candidate documents with your existing search or vector query.
- 02
Send the
queryand thedocumentstoPOST /api/v1/rerank. - 03
Set
top_nto keep only the best matches.
Authentication
Send your key as Authorization: Bearer. Reranking needs rerank:write. Cohere clients can call the same endpoint at /api/v2/rerank.
Example
A cross-encoder reads the query against every document, so it ranks more accurately than vector similarity alone. The price grows with the number of candidates, so search broadly and rerank a shortlist.
API reference
Request fields, responses, prices and code samples for every endpoint, with a form that sends a real request.
Stored locally in your browser only.
Rerank
Cross-encoder reranking for retrieval pipelines. Cohere-compatible — available at both /v1/rerank and /v2/rerank.
POST /v1/rerank
Rerank documents
Scores each document against the query with a cross-encoder and returns them ordered by relevance. Cohere-compatible; the same handler serves `/api/v1/rerank` and `/api/v2/rerank`. Billed per token across the query and all documents.
Pricing
per 1K tokens- Input
- 0.1 credits
Request body
| Field | Description |
|---|---|
modelRequiredstring | maxLen: 128 |
queryRequiredstring | |
top_ninteger | null | min: 1 |
return_documentsboolean | null | |
documentsRequiredstring[] |
Responses
| Header | Description |
|---|---|
X-Costnumber | The price billed, in credits. |
X-Request-Idstring | Identifies this request. A JSON body carries it as `request_id` too; quote it to support. |
X-RateLimit-Limitinteger | The requests a minute the rate limit on this endpoint allows. Sent once the limit has counted the request, so not when the key itself is refused. |
X-RateLimit-Remaininginteger | How many of them are left this minute. |
| Field | Description |
|---|---|
idRequiredstring | |
modelRequiredstring | |
resultsRequiredobject[] | |
metaRequiredobject | |
usageRequiredobject |
X-Request-Id: string| Field | Description |
|---|---|
errorRequiredobject | |
request_idRequiredstring | The same ID as the `X-Request-Id` header. format: uuid |
| Header | Description |
|---|---|
X-Request-Idstring | Identifies this request. A JSON body carries it as `request_id` too; quote it to support. |
X-RateLimit-Limitinteger | The requests a minute the rate limit on this endpoint allows. Sent once the limit has counted the request, so not when the key itself is refused. |
X-RateLimit-Remaininginteger | How many of them are left this minute. |
| Field | Description |
|---|---|
errorRequiredobject | |
request_idRequiredstring | The same ID as the `X-Request-Id` header. format: uuid |
| Header | Description |
|---|---|
X-Request-Idstring | Identifies this request. A JSON body carries it as `request_id` too; quote it to support. |
X-RateLimit-Limitinteger | The requests a minute the rate limit on this endpoint allows. Sent once the limit has counted the request, so not when the key itself is refused. |
X-RateLimit-Remaininginteger | How many of them are left this minute. |
| Field | Description |
|---|---|
errorRequiredobject | |
request_idRequiredstring | The same ID as the `X-Request-Id` header. format: uuid |
| Header | Description |
|---|---|
X-Request-Idstring | Identifies this request. A JSON body carries it as `request_id` too; quote it to support. |
X-RateLimit-Limitinteger | The requests a minute the rate limit on this endpoint allows. Sent once the limit has counted the request, so not when the key itself is refused. |
X-RateLimit-Remaininginteger | How many of them are left this minute. |
| Field | Description |
|---|---|
errorRequiredobject | |
request_idRequiredstring | The same ID as the `X-Request-Id` header. format: uuid |
| Header | Description |
|---|---|
X-Request-Idstring | Identifies this request. A JSON body carries it as `request_id` too; quote it to support. |
X-RateLimit-Limitinteger | The requests a minute the rate limit on this endpoint allows. Sent once the limit has counted the request, so not when the key itself is refused. |
X-RateLimit-Remaininginteger | How many of them are left this minute. |
| Field | Description |
|---|---|
errorRequiredobject | |
request_idRequiredstring | The same ID as the `X-Request-Id` header. format: uuid |
| Header | Description |
|---|---|
X-Request-Idstring | Identifies this request. A JSON body carries it as `request_id` too; quote it to support. |
Retry-Afterinteger | Seconds to wait before retrying. |
X-RateLimit-Limitinteger | The requests a minute the rate limit on this endpoint allows. Sent once the limit has counted the request, so not when the key itself is refused. |
X-RateLimit-Remaininginteger | How many of them are left this minute. |
X-RateLimit-Resetinteger | When the rate limit lets requests through again, as a Unix time in seconds. Sent with a 429 for `rate_limit_exceeded`. |
| Field | Description |
|---|---|
errorRequiredobject | |
request_idRequiredstring | The same ID as the `X-Request-Id` header. format: uuid |
| Header | Description |
|---|---|
X-Request-Idstring | Identifies this request. A JSON body carries it as `request_id` too; quote it to support. |
X-RateLimit-Limitinteger | The requests a minute the rate limit on this endpoint allows. Sent once the limit has counted the request, so not when the key itself is refused. |
X-RateLimit-Remaininginteger | How many of them are left this minute. |
| Field | Description |
|---|---|
errorRequiredobject | |
request_idRequiredstring | The same ID as the `X-Request-Id` header. format: uuid |
| Header | Description |
|---|---|
X-Request-Idstring | Identifies this request. A JSON body carries it as `request_id` too; quote it to support. |
Retry-Afterinteger | Seconds to wait before retrying. Sent with a 503 during maintenance, when a retry time was set. |
X-RateLimit-Limitinteger | The requests a minute the rate limit on this endpoint allows. Sent once the limit has counted the request, so not when the key itself is refused. |
X-RateLimit-Remaininginteger | How many of them are left this minute. |
| Field | Description |
|---|---|
errorRequiredobject | |
request_idRequiredstring | The same ID as the `X-Request-Id` header. format: uuid |
Examples
Try it
Set your API key in the bar above to send authenticated requests.