---
title: "Rerank Documents"
method: POST
path: "/rerank"
tags: ["rerank"]
---

# Rerank Documents

`POST /rerank`

Rerank documents based on relevance to a query.

This endpoint allows you to rerank a list of documents based on their relevance
to a given query using state-of-the-art reranking models.

The documents will be returned in order of relevance, with the most relevant
documents first. Each result includes the original document index and a
relevance score.

## Request body

- RerankRequestModel — Request model for reranking.
  - `query` string, required — The search query to rank documents against
  - `documents` RerankDocument[], required — List of documents to rerank
    - `text` string, required — The text content of the document
    - `metadata` object, nullable — Optional metadata associated with the document
  - `model` string, required — The reranking model to use
  - `top_k` integer, nullable — Number of top documents to return. Defaults to all documents.
  - `return_documents` boolean — Whether to return document content in the response
  - `max_chunks_per_doc` integer, nullable — Maximum number of chunks per document

## Response `200`

Successful Response

- RerankResponseModel — Response model for reranking.
  - `id` string, required — Unique identifier for this rerank request
  - `results` RerankResult[], required — Ranked results
    - `index` integer, required — Original index of the document
    - `relevance_score` number, required — Relevance score between 0 and 1
    - `document` RerankDocument — Document to be reranked.
      - `text` string, required — The text content of the document
      - `metadata` object, nullable — Optional metadata associated with the document
  - `model` string, required — The model used for reranking
  - `usage` object, required — Usage information
  - `cost` RerankCost — Cost information for reranking.
    - `generation` number, required — Cost of the reranking request in USD
    - `platform` number, required — Platform fee in USD (percentage of generation cost)
    - `total` number, required — Total cost in USD (generation + platform)

## Other responses

- `400` — Bad Request
- `401` — Unauthorized
- `402` — Payment Required (out of credits)
- `404` — Not Found
- `422` — Request Validation Error

---

[API](https://skmtc.dev/opper/apis/opper-api-v2.md) · [All operations](https://skmtc.dev/opper/apis/opper-api-v2/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/opper/opper-api-v2/revisions/d3ccdaa15678/schema)