Rerank

Order a list of documents from most to least relevant to a query. Use it as the second stage of search: fetch candidates with embeddings or keyword search, then rerank the best few. The request and response follow the Cohere and Jina rerank style, since OpenAI has no rerank API.

POST /v1/rerank

Only rerank models are served here. Calling it with a chat model returns 400. List the current rerank models with a public call that needs no key:

curl "https://kenari.id/v1/models?modality=rerank"

A plain GET /v1/models does not list embedding, rerank, moderation or System One models. It does list chat, image, speech, transcription and video models. The examples below use bge-reranker-base. Swap in any id the call above returns. Prices are on Models and pricing.

Request

Field	Type	Required	Description
`model`	string	yes	A rerank model id.
`query`	string	yes	What relevance is measured against. Up to 8,192 bytes.
`documents`	array of strings	yes	The documents to rank. Up to 100, each up to 8,192 bytes and a non-empty string, and up to 512 KiB in total.
`top_n`	integer	no	Return only the best `n` results. From 1 up to the number of documents. Default: all documents.
`return_documents`	boolean	no	Include each document’s text in its result. Default: `false`.

Response

results holds one entry per returned document, best match first. Each entry has index, the position of the document in the documents array you sent, and relevance_score. A higher score means a closer match. document is an object with a text field and appears only when return_documents is true. usage reports the input tokens.

{
  "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 $KENARI_API_KEY" \
  -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

The OpenAI SDK has no rerank method, so use requests.

import os
import requests

resp = requests.post(
    "https://kenari.id/v1/rerank",
    headers={"Authorization": f"Bearer {os.environ['KENARI_API_KEY']}"},
    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 ${process.env.KENARI_API_KEY}`,
    "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();

Billing

Rerank is billed per input token, estimated from the query plus every document. The estimate is the charge, and the usage in the response is for display only. See How billing works for how the reservation and price dimensions work.

Errors

Size limits are checked first. A request over a limit fails with 400 before any charge.

Status	Code	When
400	`bad_request`	`model` is unknown or is not a rerank model, `query` or `documents` is missing or empty, a limit is exceeded, or `top_n` is not an integer between 1 and the number of documents.
400	`model_not_found`	The model is listed but no provider serves it right now. Retry later.

See Errors for the shared codes, such as insufficient_balance and all_providers_failed.