v21

latestOpenAPI 3.1.0raw.githubusercontent.com2026-01-1340148239.5 KB

/rerank

Rerank

Rank a list of documents according to their relevance to a query primarily and your custom instructions secondarily. We evaluated the model on instructions for recency, document type, source, and metadata, and it can generalize to other instructions as well. The reranker supports multilinguality.

The total request cannot exceed 400,000 tokens. The combined length of the query, instruction and any document with its metadata must not exceed 8,000 tokens.

See our blog post and code examples. Email rerank-feedback@contextual.ai with any feedback or questions.

post/rerank

Request body

querystring required

The string against which documents will be ranked for relevance

documentsstring[] required

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

modelstring 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_ninteger

The number of top-ranked results to return

instructionstring

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

metadatastring[]

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