---
title: "Rerank"
method: POST
path: "/v1/rerank"
---

# Rerank

`POST /v1/rerank`

Rerank documents against a query using a cross-encoder reranker. Cohere-compatible API.

## Request body

- object
  - `model` string, required — ID of the rerank model to use.
  - `query` string, required — The search query to rank documents against.
  - `documents` string[], required — Array of document strings to rerank.
  - `top_n` integer — Number of top results to return. Defaults to all documents when omitted.
  - `return_documents` boolean — Whether to include the document text in the response. Default false.
  - `max_chunks_per_doc` integer — Maximum number of chunks per document (accepted, but not all providers support this).

## Response `200`

Rerank response with ranked results.

- object — Cohere-compatible rerank response payload.
  - `id` string
  - `model` string, required
  - `results` object[], required
    - `index` integer, required
    - `relevance_score` number, required
    - `document` string
  - `meta` object
    - `api_version` object
      - `version` string
    - `billed_units` object
      - `input_tokens` integer
      - `total_tokens` integer

## Other responses

- `400` — Invalid request body or parameters.
- `401` — Unauthorized request.
- `402` — Payment required / Insufficient credits.
- `403` — Forbidden upstream response.
- `404` — Not found upstream response.
- `410` — Archived or unavailable project.
- `429` — Rate limited upstream response.
- `500` — Internal server error.
- `502` — Bad gateway / Upstream fetch failure.
- `503` — Service unavailable.
- `504` — Gateway timeout.

---

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