---
title: "Rerank documents"
method: POST
path: "/v1/rerank"
tags: ["Embeddings"]
---

# Rerank documents

`POST /v1/rerank`

## Request

- Base URL: `https://api.tokenlab.sh`
- URL: `https://api.tokenlab.sh/v1/rerank`
- Auth: HTTP bearer

Reranks documents by relevance to a query using semantic similarity.

## Headers

- `X-TokenLab-Delivery-Policy` 'auto' | 'verified' | 'official'

## Request body

- object
  - `model` string, required: Reranker model to use
  - `query` string, required: Query to rank against
  - `documents` string[], required: Documents to rerank
  - `top_n` integer: Number of results to return
  - `return_documents` boolean

## Response `200`

Ranked results

- object
  - `id` string
  - `results` object[], required
  - `model` string, required
  - `usage` object

## Other responses

- `400`: Bad Request - Invalid input
- `401`: Unauthorized - Invalid or missing API key
- `503`: The requested Delivery tier is temporarily unavailable.

---

[API](https://skmtc.dev/tokenlab/apis/tokenlab-ai-gateway.md) · [All operations](https://skmtc.dev/tokenlab/apis/tokenlab-ai-gateway/llms.txt) · [OpenAPI document](https://skmtc.dev/tokenlab/apis/tokenlab-ai-gateway/revisions/3208bfbcda22?raw)