Rerank

A Cohere-compatible rerank API. Re-orders a list of documents by relevance to a query.

POST /v1/reranktakes a query and an array of documents, scores each document's relevance, and returns them ranked. It is compatible with the Cohere /v1/rerank API and follows Vercel AI Gateway parity — you can reuse existing Cohere SDK setup unchanged.

POST/v1/rerank

Connecting#

To connect with the Cohere SDK, set base_url to https://apirouter.pleum.ai/v1 and api_key to your plm_ key. The SDK appends /rerank. It is the same host as the OpenAI-compatible path.

Cohere SDK (Python)

import cohere

client = cohere.ClientV2(
    base_url="https://apirouter.pleum.ai/v1",
    api_key="plm_...",
)

response = client.rerank(
    model="rerank-v3.5",
    query="What is the capital of France?",
    documents=["Paris is the capital of France.", "London is the capital of the UK."],
    top_n=2,
)
print(response.results)

HTTP (Python)

import requests

resp = requests.post(
    "https://apirouter.pleum.ai/v1/rerank",
    headers={
        "Authorization": "Bearer plm_...",
        "Content-Type": "application/json",
    },
    json={
        "model": "rerank-v3.5",
        "query": "What is the capital of France?",
        "documents": [
            "Paris is the capital of France.",
            "London is the capital of the UK.",
        ],
        "top_n": 2,
    },
)
print(resp.json())

HTTP (TypeScript)

const res = await fetch("https://apirouter.pleum.ai/v1/rerank", {
  method: "POST",
  headers: {
    Authorization: "Bearer plm_...",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    model: "rerank-v3.5",
    query: "What is the capital of France?",
    documents: [
      "Paris is the capital of France.",
      "London is the capital of the UK.",
    ],
    top_n: 2,
  }),
});

const data = await res.json();
console.log(data.results);

Authenticate with a plm_ API key in the Authorization: Bearer header.

Request body#

Parameter	Type	Required	Description
model	string	Required	Rerank model ID, e.g. `rerank-v3.5`. Find rerank-family models via `GET /v1/models`.
query	string	Required	The search query to compare documents against. An empty string returns 400.
documents	array	Required	An array of strings or `{text: ...}` objects. An empty array returns 400.
top_n	integer \| null	Optional	How many top documents to return. Omit to return all documents.
return_documents	boolean	Optional	When true, each result's `document` field includes the original text. Defaults to false.
max_chunks_per_doc	integer \| null	Optional	Cohere-compatible optional parameter. Only a minimal set is accepted.

request

curl https://apirouter.pleum.ai/v1/rerank \
  -H "Authorization: Bearer $PLEUM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "rerank-v3.5",
    "query": "What is the capital of France?",
    "documents": [
      "Paris is the capital of France.",
      "London is the capital of the UK."
    ],
    "top_n": 2
  }'

Response#

results is sorted by relevance_score descending; each entry carries the index from the original array. usage contains search_units (Cohere) or a token estimate.

200 OK

{
  "id": "rerank-01J9X2Qm7...",
  "results": [
    {"index": 0, "relevance_score": 0.998},
    {"index": 1, "relevance_score": 0.102}
  ],
  "model": "rerank-v3.5",
  "usage": {"search_units": 1},
  "cost": {"usd": 0.0001, "krw": 1, "fx_rate": 1525.0, "markup_rate": 0.0}
}

Billing#

Billing is token-based settlement from the provider-reported usage (search_units → tokens, or direct tokens). cost is a PleumRouter extension with KRW cost, FX rate, and markup.