Mixedbread

Rerank Documents

POST/v1/reranking

Authorization

Authorizationstringrequired

Bearer token for API authentication. Format: `Bearer YOUR_API_KEY`

Request Body

modelstringdefault: mixedbread-ai/mxbai-rerank-large-v2

The model to use for reranking documents.

Constraints

•Minimum length: 1•Maximum length: 500
querystringrequired

The query to rerank the documents.

Constraints

•Minimum length: 1•Maximum length: 32000
inputany[]required

The input documents to rerank.

Constraints

•Minimum items: 1•Maximum items: 1000
rank_fieldsarray

The fields of the documents to rank.

Constraints

•Minimum items: 1
top_kintegerdefault: -1

The number of documents to return.

Constraints

•Minimum: 1
return_inputbooleandefault: false

Whether to return the documents.

rewrite_querybooleandefault: false

Wether or not to rewrite the query before passing it to the reranking model

Response Body

modelstringrequired

The model used

objectstringdefault: list

The object type of the response

top_kintegerrequired

The number of documents to return.

return_inputbooleanrequired

Whether to return the documents.

Request
POST/v1/reranking
from mixedbread import Mixedbread

mxbai = Mixedbread(api_key="YOUR_API_KEY")

response = 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(response.data)
Response
JSON
{
  "model": "mixedbread-ai/mxbai-rerank-large-v2",
  "top_k": 3,
  "return_input": false,
  "object": "list",
  "data": [
    {
      "index": 2,
      "score": 0.9876,
      "object": "text_document"
    },
    {
      "index": 0,
      "score": 0.8765,
      "object": "text_document"
    },
    {
      "index": 5,
      "score": 0.7654,
      "object": "text_document"
    }
  ],
  "usage": {
    "prompt_tokens": 453,
    "total_tokens": 1276
  }
}
Last updated: January 7, 2026