---
title: "Rerank caller-supplied document embeddings"
method: POST
path: "/v1/rerank"
tags: ["LLM API"]
---

# Rerank caller-supplied document embeddings

`POST /v1/rerank`

## Request

- Base URL: `https://api.algenta.ai`
- URL: `https://api.algenta.ai/v1/rerank`
- Auth: one of:
  - HTTP bearer
  - API key in header `X-API-Key`

Runs a deterministic reranking pass over caller-supplied embedding vectors. This route does not generate embeddings from text; it ranks the provided documents with the selected runtime-backed similarity or distance metric.

## Request body

- RerankRequest
  - `model` string: Reranking model identifier from GET /v1/models.
  - `query_embedding` number[], required: Precomputed query embedding vector.
  - `documents` RerankDocumentInput[], required: Candidate documents with caller-supplied embeddings.
    - `id` string, required: Stable document identifier for the returned ranking row.
    - `embedding` number[], required: Precomputed embedding vector for the candidate document.
    - `text` string, nullable: Optional raw document text returned unchanged in the ranking output.
    - `metadata` object, nullable: Optional structured document metadata returned unchanged in the ranking output.
  - `top_n` integer, nullable: Optional number of ranked documents to return. Defaults to all documents.

## Response `200`

Successful Response

- RerankResponse
  - `object` 'list'
  - `model` string, required
  - `similarity_metric` string, required
  - `total_documents` integer, required
  - `returned_documents` integer, required
  - `data` RerankResult[], required
    - `object` 'rerank_result'
    - `id` string, required
    - `index` integer, required
    - `rank` integer, required
    - `score` number, required
    - `text` string, nullable
    - `metadata` object, nullable

## Other responses

- `422`: Validation Error

---

[API](https://skmtc.dev/codna/apis/algenta-api.md) · [All operations](https://skmtc.dev/codna/apis/algenta-api/llms.txt) · [OpenAPI document](https://skmtc.dev/codna/apis/algenta-api/revisions/35d30f84a5df?raw)