> ## Documentation Index
> Fetch the complete documentation index at: https://docs.contextual.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# 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](https://contextual.ai/blog/introducing-instruction-following-reranker/) and [code examples](https://colab.research.google.com/github/ContextualAI/examples/blob/main/03-standalone-api/03-rerank/rerank.ipynb). Email [rerank-feedback@contextual.ai](mailto:rerank-feedback@contextual.ai) with any feedback or questions.



## OpenAPI

````yaml api-reference/openapi.json post /rerank
openapi: 3.1.0
info:
  title: Endpoints
  version: '1.0'
servers:
  - url: https://api.contextual.ai/v1
security:
  - BearerAuth: []
paths:
  /rerank:
    post:
      tags:
        - /rerank
      summary: Rerank
      description: >-
        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](https://contextual.ai/blog/introducing-instruction-following-reranker/)
        and [code
        examples](https://colab.research.google.com/github/ContextualAI/examples/blob/main/03-standalone-api/03-rerank/rerank.ipynb).
        Email
        [rerank-feedback@contextual.ai](mailto:rerank-feedback@contextual.ai)
        with any feedback or questions.
      operationId: rerank_rerank_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RerankRequestV1'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RerankResponseV1'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
components:
  schemas:
    RerankRequestV1:
      properties:
        query:
          type: string
          title: Query
          description: The string against which documents will be ranked for relevance
        documents:
          items:
            type: string
          type: array
          minItems: 1
          title: Documents
          description: >-
            The texts to be reranked according to their relevance to the query
            and the optional instruction
        model:
          type: string
          title: Model
          description: >-
            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:
          type: integer
          title: Top N
          description: The number of top-ranked results to return
        instruction:
          type: string
          title: Instruction
          description: >-
            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:
          items:
            type: string
          type: array
          minLength: 1
          title: Metadata
          description: >-
            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.
      additionalProperties: false
      type: object
      required:
        - query
        - documents
        - model
      title: RerankRequestV1
      description: Rerank input request object.
    RerankResponseV1:
      properties:
        results:
          items:
            $ref: '#/components/schemas/RerankedResultItem'
          type: array
          title: Reranked Results
          description: >-
            The ranked list of documents containing the index of the document
            and the relevance score, sorted by relevance score.
      type: object
      required:
        - results
      title: RerankResponseV1
      description: Rerank output response.
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    RerankedResultItem:
      properties:
        index:
          type: integer
          title: Index
          description: Index of the document in the input list, starting with 0
        relevance_score:
          type: number
          title: Relevance Score
          description: >-
            Relevance scores assess how likely a document is to have information
            that is helpful to answer the query. Our model outputs the scores in
            a wide range, and we normalize scores to a 0-1 scale and truncate
            the response to 8 decimal places. Our reranker is designed for RAG,
            so its purpose is to check whether a document has information that
            is helpful to answer the query. A reranker that is designed for
            direct Q&A (Question & Answer) would behave differently.
      type: object
      required:
        - index
        - relevance_score
      title: RerankedResultItem
      description: Reranked result object.
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
              - type: string
              - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
      type: object
      required:
        - loc
        - msg
        - type
      title: ValidationError
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: API Key

````