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

# Create Rerank

`POST /v1/rerank`

## Request

- The document declares no server URL.
- Auth: HTTP bearer

## Request body

- CreateRerankBody
  - `query` string, required: The search query to use for the reranking. `query` and `prompt` cannot both be provided.
  - `documents` string[], required
  - `model` string, required: The model to use for the reranking, call `/v1/models` endpoint to get the list of available models, only `text-classification` model type is supported.
  - `top_n` integer, nullable: The number of top results to return. If set to None, all results will be returned.

## Response `200`

Successful Response

- RerankResponse
  - `object` 'list': Type of object.
  - `id` string, required: A unique identifier for the request.
  - `results` RerankResult[], required: The list of reranked texts.
    - `relevance_score` number, required: The relevance score of the reranked text.
    - `index` integer, required: The index of the reranked text.
  - `model` string, required: The model used to generate the reranking.
  - `usage` Usage
    - `prompt_tokens` integer
    - `completion_tokens` integer
    - `total_tokens` integer
    - `prompt_tokens_details` PromptTokensDetails
      - `cached_tokens` integer
    - `cost` number
    - `impacts` ApiDomainUsageEntitiesEnvironmentalImpacts
      - `kWh` number
      - `kgCO2eq` number

## Other responses

- `400`: Insufficient budget.
- `401`: Invalid authentication scheme.<br>Invalid API key.
- `403`: Your account has expired. Please contact support to renew your account.
- `404`: Model {name} not found.
- `422`: Model has wrong type. Expected: {expected_type}. Actual: {actual_type}.
- `429`: Token/request limit per minute/day exceeded.
- `503`: Model is too busy, please try again later.

## Changes

- **2026-09-29** `2f7a4a0aac8f`: 1 info
  - endpoint added
- **2026-09-29** `da70d9cd1957`: 1 breaking
  - api path removed without deprecation
- **2026-09-21** `5fdbd3614b8c`: 1 info
  - added the optional property `usage/prompt_tokens_details` to the response with the `200` status
- **2026-07-11** `0fd1d281f985`: 1 info
  - added the non-success response with the status `400`
- **2026-06-12** `0c595f53fc63`: 1 breaking, 2 warning, 10 info
  - the `detail` response's property type changed from `array` to `string` for status `422`
  - removed the optional property `usage/carbon` from the response with the `200` status
  - removed the optional property `usage/requests` from the response with the `200` status
  - api operation id `rerank_v1_rerank_post` removed and replaced with `create_rerank_v1_rerank_post`
  - …9 more

[Operation history](https://skmtc.dev/betagouv/apis/opengatellm/changes/v1/rerank/post.md)

---

[API](https://skmtc.dev/betagouv/apis/opengatellm.md) - [All operations](https://skmtc.dev/betagouv/apis/opengatellm/llms.txt) - [OpenAPI document](https://skmtc.dev/betagouv/apis/opengatellm/revisions/2f7a4a0aac8f?raw)