Reranking
API reference for Mixedbread's Reranking endpoint. This documentation covers request parameters, response structure, and includes examples for reordering documents based on their relevance to a given query.
Rerank Documents
POST/v1/reranking
This endpoint sorts a list of documents based on their relevance to a given query. It returns a relevance score for each document, which you can use to enhance search results and recommendations.
Request Body
- model
model
- Type
- string
- Required or Optional
- required
- Description
The model to be used for reranking the documents.
- Must be a valid model. Refer to our supported models.
- query
query
- Type
- string
- Required or Optional
- required
- Description
The query to rerank the documents for.
- Max 256 Tokens.
- input
input
- Type
- string[] | object[]
- Required or Optional
- required
- Description
The input documents to be reranked. These can either be plain strings or structured objects.
- Between 1-1000 items.
- Documents exceeding token limit will be truncated.
- rank fields
rank fields
- Type
- string[]
- Required or Optional
- optional
- Description
Specifies the fields within the objects that should be considered for ranking.
- Must adhere to JMESPath or a similar JSON query language syntax.
- top_k
top_k
- Type
- integer
- Required or Optional
- optional
- Description
The number of top documents to return after reranking. If not provided, all input documents will be returned.
- Between 1 and the number of passed documents
- Default is the number of input documents
- return_input
return_input
- Type
- boolean
- Required or Optional
- optional
- Description
Option to include the original input documents in the response. Default is false.
Response Body
- model
model
- Type
- string
- Required or Optional
- required
- Description
The reranking model used, which can be one of our hosted models or a custom fine-tuned model.
- top_k
top_k
- Type
- integer
- Required or Optional
- required
- Description
The number of top documents returned after reranking.
- return_input
return_input
- Type
- boolean
- Required or Optional
- required
- Description
Indicates whether the original input documents are included in the response.
- object
object
- Type
- string
- Required or Optional
- required
- Description
The type of the returned object. Always "list".
- data
data
- Type
- RankedDocument[]
- Required or Optional
- required
- Description
A list of the reranked documents.
- data[x].index
data[x].index
- Type
- integer
- Required or Optional
- required
- Description
The index of the document in the original input list.
- data[x].score
data[x].score
- Type
- number
- Required or Optional
- required
- Description
The relevance score of the document to the query. Higher values indicate higher relevance.
- data[x].input
data[x].input
- Type
- object
- Required or Optional
- optional
- Description
The original input document, if
return_input
was set to true.
- data[x].object
data[x].object
- Type
- string
- Required or Optional
- required
- Description
The type of the returned object. Always "text_document".
- usage
usage
- Type
- object
- Required or Optional
- required
- Description
Information about API usage for this request.
- usage.prompt_tokens
usage.prompt_tokens
- Type
- integer
- Required or Optional
- required
- Description
The number of tokens in the query and input documents.
- usage.total_tokens
usage.total_tokens
- Type
- integer
- Required or Optional
- required
- Description
The total tokens used for reranking, including the model's overhead.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20
from mixedbread import Mixedbread mxbai = Mixedbread(api_key="YOUR_API_KEY") res = mxbai.rerank( model="mixedbread-ai/mxbai-rerank-large-v2", query="Who is the author of To Kill a Mockingbird?", input=[ 'To Kill a Mockingbird is a novel by Harper Lee published in 1960. It was immediately successful, winning the Pulitzer Prize, and has become a classic of modern American literature.', 'The novel Moby-Dick was written by Herman Melville and first published in 1851. It is considered a masterpiece of American literature and deals with complex themes of obsession, revenge, and the conflict between good and evil.', 'Harper Lee, an American novelist widely known for her novel To Kill a Mockingbird, was born in 1926 in Monroeville, Alabama. She received the Pulitzer Prize for Fiction in 1961.', 'Jane Austen was an English novelist known primarily for her six major novels, which interpret, critique and comment upon the British landed gentry at the end of the 18th century.', 'The Harry Potter series, which consists of seven fantasy novels written by British author J.K. Rowling, is among the most popular and critically acclaimed books of the modern era.', 'The Great Gatsby, a novel written by American author F. Scott Fitzgerald, was published in 1925. The story is set in the Jazz Age and follows the life of millionaire Jay Gatsby and his pursuit of Daisy Buchanan.' ], top_k=3, return_input=False ) print(res.data)
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30
{ "model": "mixedbread-ai/mxbai-rerank-large-v2", "top_k": 3, "return_input": true, "object": "list", "data": [ { "index": 0, "score": 0.9876, "input": "Harper Lee, an American novelist widely known for her novel To Kill a Mockingbird, was born in 1926 in Monroeville, Alabama. She received the Pulitzer Prize for Fiction in 1961.", "object": "text_document" }, { "index": 1, "score": 0.8765, "input": "To Kill a Mockingbird is a novel by Harper Lee published in 1960. It was immediately successful, winning the Pulitzer Prize, and has become a classic of modern American literature.", "object": "text_document" }, { "index": 2, "score": 0.7654, "input": "The Great Gatsby, a novel written by American author F. Scott Fitzgerald, was published in 1925. The story is set in the Jazz Age and follows the life of millionaire Jay Gatsby and his pursuit of Daisy Buchanan.", "object": "text_document" } ], "usage": { "prompt_tokens": 453, "total_tokens": 1276 } }
Last updated on 4/7/2025