---
title: "Reranking"
method: POST
path: "/rerankings"
tags: ["Rerankings"]
---

# Reranking

`POST /rerankings`

Score and rank documents by their relevance to queries with an Isaacus reranker.

## Request body

- RerankingRequest — A request to rerank documents by their relevance to a query with an Isaacus reranker.
  - `model` union, required — The ID of the model to use for reranking, being either a [reranking model](https://docs.isaacus.com/models/introduction#reranking) or [universal classification model](https://docs.isaacus.com/models/introduction#universal-classification).
    - 'kanon-2-reranker'
    - 'kanon-universal-classifier'
  - `query` string, required — The query to evaluate the relevance of the texts to. The query must contain at least one non-whitespace character. Unlike the texts being reranked, the query cannot be so long that it exceeds the maximum input length of the reranker.
  - `texts` string[], required — The texts to rerank. There must be at least one text. Each text must contain at least one non-whitespace character.
  - `top_n` integer, nullable — A whole number greater than or equal to 1.
  - `is_iql` boolean — Whether the query should be interpreted as an [Isaacus Query Language (IQL)](https://docs.isaacus.com/iql) query, which is not the case by default. If you allow untrusted users to construct their own queries, think carefully before enabling IQL since queries can be crafted to consume an excessively large amount of tokens.
  - `scoring_method` 'auto' | 'chunk_max' | 'chunk_avg' | 'chunk_min' — The method to use for producing an overall relevance score for a text that exceeds the model's local context window and has, therefore, been split into multiple chunks. `auto` is the default scoring method and is recommended for most use cases. Currently, it is equivalent to `chunk_max`. In the future, it will automatically select the best method based on the model and inputs. `chunk_max` uses the highest relevance score of all of a text's chunks. `chunk_avg` averages the relevance scores of all of a text's chunks. `chunk_min` uses the lowest relevance score of all of a text's chunks.
  - `chunking_options` ChunkingOptions — Options for how to split text into smaller chunks.
    - `size` integer, nullable — A whole number greater than or equal to 1.
    - `overlap_ratio` number, nullable — A number greater than or equal to 0 and less than 1.
    - `overlap_tokens` integer, nullable — A whole number greater than or equal to 0.

## Response `200`

Request fulfilled, document follows

- RerankingResponse
  - `results` RerankingResult[], required — The texts reranked by relevance to the query, in order from highest to lowest relevance score.
    - `index` integer, required — The index of the text in the input array of texts, starting from `0` (and, therefore, ending at the number of texts minus `1`).
    - `score` number, required — A score between `0` and `1`, inclusive, representing the relevance of the text to the query.
  - `usage` RerankingUsage, required — Statistics about the usage of resources in the process of reranking the texts.
    - `input_tokens` integer, required — The number of tokens inputted to the model.

## Other responses

- `400` — The request was invalid or could not be processed.
- `401` — The API key you provided does not exist, is expired or revoked, or is not authorized to access this resource.
- `402` — Your account is overdue, please pay any outstanding invoices to continue using our services.
- `403` — You are not allowed to access this resource.
- `413` — The request is larger than the server is willing or able to process.
- `500` — An unexpected error occurred while processing the request.

## Changes

- **2026-03-11** `3fc0da1b03c0` — 4 breaking, 1 info
  - removed the enum value `kanon-2-reranker` of the request property `model`
  - removed the enum value `kanon-universal-classifier` of the request property `model`
  - removed the enum value `kanon-universal-classifier-mini` of the request property `model`
  - the `model` request property type/format changed from `string`/`` to ``/``
  - …1 more
- **2026-03-09** `0768ad934de9` — 1 info
  - the `query` request property's maxLength was increased from `5000` to `10000000`
- **2026-03-09** `cc6e47db2f93` — 1 info
  - added the new `kanon-2-reranker` enum value to the request property `model`
- **2026-02-04** `eb64c01e148b` — 1 warning
  - the `chunking_options/oneOf[subschema #1: Chunking options]/overlap_tokens/oneOf[subschema #1: Non-negative integer]/` request property's min was set to `0.00`

[Change history](https://skmtc.dev/isaacus-dev/apis/isaacus-api/changes/rerankings/post.md)

---

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