# Rerank documents

**POST /rerank**

Reranks a list of documents based on their relevance to a query.

This endpoint accepts a query and a list of documents, then returns the documents sorted by relevance score in descending order.



## Servers
- https://ai.mongodb.com/v1: https://ai.mongodb.com/v1 ()


## Authentication methods
- Api key auth


## Parameters



### Body: application/json (object)

- **query** (string)
  The search query as a string.

  Maximum query length:
  - 8,000 tokens for `rerank-2.5` and `rerank-2.5-lite`
  - 4,000 tokens for `rerank-2`
  - 2,000 tokens for `rerank-2-lite`
- **documents** (array[string])
  A list of documents to be reranked, provided as strings.

  Constraints:
  - Maximum number of documents: 1,000
  - Maximum tokens per query + document pair:
    - 32,000 for `rerank-2.5` and `rerank-2.5-lite`
    - 16,000 for `rerank-2`
    - 8,000 for `rerank-2-lite`
  - Maximum total tokens (query tokens × number of documents + sum of all document tokens):
    - 600K for `rerank-2.5`, `rerank-2.5-lite`, `rerank-2`, and `rerank-2-lite`
- **model** (string)
  The reranking model to use. Recommended models: `rerank-2.5`, `rerank-2.5-lite`.
- **top_k** (integer | null)
  The number of most relevant documents to return. If not specified, all documents are returned with their reranking scores.
- **return_documents** (boolean)
  Whether to include the document text in the response.

  - `false` (default): Returns only `{"index", "relevance_score"}` for each document
  - `true`: Returns `{"index", "document", "relevance_score"}` for each document
- **truncation** (boolean)
  Whether to truncate inputs that exceed the context length limit.

  - `true` (default): The query and documents are automatically truncated to fit within the context length limit.
  - `false`: An error is returned if the query or any query-document pair exceeds the context length limit.


## Responses
### 200
Success

#### Body: application/json (object)
- **object** (string)
  The object type. Always returns "list".
- **data** (array[object])
  An array of reranking results, sorted by relevance score in descending order.
- **model** (string)
  The name of the model used for reranking.
- **usage** (object)


### 400
Invalid Request

#### Body: application/json (object)
- **detail** (string)
  The request is invalid. This error can occur due to invalid JSON, invalid parameter types, incorrect data types, batch size too large, total tokens exceeding the limit, or tokens in an example exceeding context length.

### 401
Unauthorized

#### Body: application/json (object)
- **detail** (string)
  Invalid authentication. Ensure your model API key is correctly specified in the Authorization header as `Bearer VOYAGE_API_KEY`.

### 403
Forbidden

#### Body: application/json (object)
- **detail** (string)
  Access forbidden. This may occur if the IP address you are sending the request from is not allowed.

### 429
Rate Limit Exceeded

#### Body: application/json (object)
- **detail** (string)
  Rate limit exceeded. Your request frequency or token usage is too high. Reduce your request rate or wait before retrying.

### 500
Internal Server Error

#### Body: application/json (object)
- **detail** (string)
  An unexpected error occurred on the server. Retry your request after a brief wait.

### 502
Bad Gateway

#### Body: application/json (object)
- **detail** (string)
  The server received an invalid response from an upstream server. Retry your request after a brief wait.

### 503
Service Unavailable

#### Body: application/json (object)
- **detail** (string)
  The service is temporarily unavailable due to high traffic or maintenance. Retry your request after a brief wait.

### 504
Gateway Timeout

#### Body: application/json (object)
- **detail** (string)
  The server did not receive a timely response from an upstream server. Retry your request after a brief wait.


[Powered by Bump.sh](https://bump.sh)