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

# Create rerank

`POST /v2/router/rerank`

Rerank a list of documents based on their relevance to a query.

## Request body

- object
  - `query` string, required — The search query
  - `documents` string[], required — A list of texts that will be compared to the `query`. For optimal performance we recommend against sending more than 1,000 documents in a single request.
  - `model` string, required — The identifier of the model to use
  - `top_n` integer — The number of most relevant documents or indices to return, defaults to the length of the documents
  - `return_documents` boolean — Whether to return the documents in the response
  - `filename` string, nullable — The filename of the document to rerank
  - `name` string — The name to display on the trace. If not specified, the default system name will be used.
  - `fallbacks` object[] — Array of fallback models to use if primary model fails
    - `model` string, required — Fallback model identifier
  - `retry` object — Retry configuration for the request
    - `count` number — Number of retry attempts (1-5)
    - `on_codes` number[] — HTTP status codes that trigger retry logic
  - `cache` object — Cache configuration for the request.
    - `ttl` number — Time to live for cached responses in seconds. Maximum 259200 seconds (3 days).
    - `type` 'exact_match', required
  - `load_balancer` object — Load balancer configuration for the request.
    - `type` 'weight_based', required
    - `models` object[], required
      - `model` string, required — Model identifier for load balancing
      - `weight` number — Weight assigned to this model for load balancing
  - `timeout` object — Timeout configuration to apply to the request. If the request exceeds the timeout, it will be retried or fallback to the next model if configured.
    - `call_timeout` number, required — Timeout value in milliseconds
  - `plugins` union[] — Request-scoped transforms applied to the text exchanged with the model. Currently supports `pii_redaction`, which replaces PII with placeholders before the provider sees it and restores the original values in the response.
    - union
      - PIIRedactionPluginAuto
        - `id` 'pii_redaction', required — Plugin discriminator. Must be `pii_redaction`.
        - `on_failure` 'block' | 'passthrough' — Behavior when redaction is unavailable. `block` (default) fails the request; `passthrough` sends the original text.
        - `threshold` number — Detector confidence cutoff in [0,1].
        - `entities` string[] — Entity types to redact when no detector language is configured. Omit to redact every detected type.
      - PIIRedactionPluginEn
        - `id` 'pii_redaction', required — Plugin discriminator. Must be `pii_redaction`.
        - `on_failure` 'block' | 'passthrough' — Behavior when redaction is unavailable. `block` (default) fails the request; `passthrough` sends the original text.
        - `threshold` number — Detector confidence cutoff in [0,1].
        - `language` 'en', required — Detector language.
        - `entities` string[] — English entity types to redact. Omit to redact every type detected for the language.
      - PIIRedactionPluginNl
        - `id` 'pii_redaction', required — Plugin discriminator. Must be `pii_redaction`.
        - `on_failure` 'block' | 'passthrough' — Behavior when redaction is unavailable. `block` (default) fails the request; `passthrough` sends the original text.
        - `threshold` number — Detector confidence cutoff in [0,1].
        - `language` 'nl', required — Detector language.
        - `entities` string[] — Dutch entity types to redact. Omit to redact every type detected for the language.
  - `orq` object
    - `name` string — The name to display on the trace. If not specified, the default system name will be used.
    - `fallbacks` object[] — Array of fallback models to use if primary model fails
      - `model` string, required — Fallback model identifier
    - `cache` object — Cache configuration for the request.
      - `ttl` number — Time to live for cached responses in seconds. Maximum 259200 seconds (3 days).
      - `type` 'exact_match', required
    - `retry` object — Retry configuration for the request
      - `count` number — Number of retry attempts (1-5)
      - `on_codes` number[] — HTTP status codes that trigger retry logic
    - `identity` PublicIdentity — Information about the identity making the request. If the identity does not exist, it will be created automatically.
      - `id` string, required — Unique identifier for the contact
      - `display_name` string — Display name of the contact
      - `email` string, email — Email address of the contact
      - `metadata` object[] — A hash of key/value pairs containing any other data about the contact
      - `logo_url` string — URL to the contact's avatar or logo
      - `tags` string[] — A list of tags associated with the contact
    - `contact` PublicContact — @deprecated Use identity instead. Information about the contact making the request.
      - `id` string, required — Unique identifier for the contact
      - `display_name` string — Display name of the contact
      - `email` string, email — Email address of the contact
      - `metadata` object[] — A hash of key/value pairs containing any other data about the contact
      - `logo_url` string — URL to the contact's avatar or logo
      - `tags` string[] — A list of tags associated with the contact
    - `load_balancer` object — Array of models with weights for load balancing requests
      - `type` 'weight_based', required
      - `models` object[], required
        - `model` string, required — Model identifier for load balancing
        - `weight` number — Weight assigned to this model for load balancing
    - `timeout` object — Timeout configuration to apply to the request. If the request exceeds the timeout, it will be retried or fallback to the next model if configured.
      - `call_timeout` number, required — Timeout value in milliseconds

## Response `200`

Returns the reranked documents.

- object
  - `id` string — A unique identifier for the rerank.
  - `object` 'list', required
  - `results` object[], required — An ordered list of ranked documents
    - `object` 'rerank', required — The object type, which is always `rerank`.
    - `index` number, required — Corresponds to the index in the original list of documents to which the ranked document belongs.
    - `relevance_score` number, required — Relevance scores are normalized to be in the range [0, 1]. Scores close to 1 indicate a high relevance to the query, and scores closer to 0 indicate low relevance.
    - `document` object — If return_documents is set as false this will return none, if true it will return the documents passed in
      - `text` string, required — The text of the document to rerank
  - `usage` object
    - `total_tokens` number, required — The total number of tokens used in the rerank

---

[API](https://skmtc.net/orq-ai/apis/orq-ai-api.md) · [All operations](https://skmtc.net/orq-ai/apis/orq-ai-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/orq-ai/orq-ai-api/revisions/4fdc24e562eb/schema)