Skip to main content
POST
/
rerank
Rerank
curl --request POST \
  --url https://api.contextual.ai/v1/rerank \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "query": "<string>",
  "documents": [
    "<string>"
  ],
  "model": "<string>",
  "top_n": 123,
  "instruction": "<string>",
  "metadata": [
    "<string>"
  ]
}
'
{
  "results": [
    {
      "index": 123,
      "relevance_score": 123
    }
  ]
}

Authorizations

​
Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Body

application/json

Rerank input request object.

​
query
string
required

The string against which documents will be ranked for relevance

​
documents
string[]
required

The texts to be reranked according to their relevance to the query and the optional instruction

Minimum array length: 1
​
model
string
required

The version of the reranker to use. Currently, we have: "ctxl-rerank-v2-instruct-multilingual", "ctxl-rerank-v2-instruct-multilingual-mini", "ctxl-rerank-v1-instruct".

​
top_n
integer

The number of top-ranked results to return

​
instruction
string

Instructions that the reranker references when ranking documents, after considering relevance. We evaluated the model on instructions for recency, document type, source, and metadata, and it can generalize to other instructions as well. For instructions related to recency and timeframe, specify the timeframe (e.g., instead of saying "this year") because the reranker doesn't know the current date. Example: "Prioritize internal sales documents over market analysis reports. More recent documents should be weighted higher. Enterprise portal content supersedes distributor communications."

​
metadata
string[]

Metadata for documents being passed to the reranker. Must be the same length as the documents list. If a document does not have metadata, add an empty string.

Response

Successful Response

Rerank output response.

​
results
RerankedResultItem · object[]
required

The ranked list of documents containing the index of the document and the relevance score, sorted by relevance score.