Cookies

We use cookies to improve your experience on our site. You can manage your preferences below.

Mixedbread

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.

  • 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.

Request
POST/v1/reranking
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)
Response
json
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