Rerank

kenari provides a Cohere-style rerank endpoint for ordering documents by relevance to a query. This endpoint only serves rerank models in the catalog. Calling it with an ordinary chat model returns status 400. Rerank has no OpenAI standard wire, so this is kenari’s own contract, not a passthrough of any single provider’s wire.

Available models

The list of rerank models is dynamic. Call GET /v1/models?modality=rerank (public, no key) to read the ids that are currently active. A bare GET /v1/models lists chat models only, so rerank models do not appear there.

As of 29 July 2026 the public catalog shows bge-reranker-base as the active rerank model. The examples below use that id. If it is no longer sold, swap in one returned by ?modality=rerank.

Endpoint

POST /v1/rerank

Send query and documents, and the gateway returns the same documents ordered from most to least relevant.

Request parameters

Field	Type	Required	Description
`model`	string	yes	Rerank model id from the catalog.
`query`	string	yes	The query relevance is measured against. Up to 8192 bytes.
`documents`	array of strings	yes	Documents to rank, in the order sent. Up to 100 documents, each up to 8192 bytes, 512 KiB combined.
`top_n`	integer	no	Limit how many results come back (1 through the document count). Default: every document.
`return_documents`	boolean	no	Include each result’s document text. Default: `false`.

Billing

Billing is calculated per input token, from the character count of query plus every entry in documents (roughly four characters per token, rounded up), then deducted from the Rupiah balance. Cost is computed before the request is forwarded to the provider and never depends on the usage figure a provider reports. See Billing for balance and deduction details.

Response shape

object is "list", model echoes the model id you requested (never the provider’s internal name), and the results array holds one entry per relevant document, ordered from the highest score down. index points back into the documents array you sent. document appears only when return_documents is true.

{
  "object": "list",
  "model": "bge-reranker-base",
  "results": [
    { "index": 2, "relevance_score": 0.91 },
    { "index": 0, "relevance_score": 0.42 }
  ],
  "usage": { "prompt_tokens": 24, "total_tokens": 24 }
}

Examples

curl

curl https://kenari.id/v1/rerank \
  -H "Authorization: Bearer kn-..." \
  -H "Content-Type: application/json" \
  -d '{
    "model": "bge-reranker-base",
    "query": "spicy fried rice recipe",
    "documents": [
      "how to brew iced coffee",
      "growing chili peppers in a pot",
      "spicy home-style fried rice recipe"
    ],
    "top_n": 2
  }'

Python

import requests

resp = requests.post(
    "https://kenari.id/v1/rerank",
    headers={"Authorization": "Bearer kn-..."},
    json={
        "model": "bge-reranker-base",
        "query": "spicy fried rice recipe",
        "documents": [
            "how to brew iced coffee",
            "growing chili peppers in a pot",
            "spicy home-style fried rice recipe",
        ],
        "top_n": 2,
    },
)
print(resp.json()["results"])

JavaScript

const resp = await fetch("https://kenari.id/v1/rerank", {
  method: "POST",
  headers: {
    Authorization: "Bearer kn-...",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    model: "bge-reranker-base",
    query: "spicy fried rice recipe",
    documents: [
      "how to brew iced coffee",
      "growing chili peppers in a pot",
      "spicy home-style fried rice recipe",
    ],
    top_n: 2,
  }),
});
const { results } = await resp.json();