Text & embeddings

Rerank

Sort documents by relevance to a query.

POST /v1/rerank

Scores a list of documents against a query and returns them ordered by relevance. The request and response follow the Jina / Cohere rerank format. Typical use: re-order the candidates returned by a vector search before passing the best ones to an LLM.

Authentication

Authorization: Bearer sk-xxxx

Request body

Parameter	Type	Required	Description
`model`	string	Yes	Rerank model ID, e.g. `bge-reranker-v2-m3`.
`query`	string	Yes	Search query.
`documents`	array	Yes	Documents to score: strings, or objects such as `{"text": "..."}`.
`top_n`	integer	No	Return only the N most relevant documents. Default: all.
`return_documents`	boolean	No	Include the document text in each result. Default `false`.

Request example

cURL

curl https://rutoken.ai/v1/rerank \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $API_KEY" \
  -d '{
    "model": "bge-reranker-v2-m3",
    "query": "What is the capital of France?",
    "documents": [
      "Berlin is the capital of Germany.",
      "Paris is the capital and largest city of France.",
      "France is famous for its wine."
    ],
    "top_n": 2,
    "return_documents": true
  }'

Python

import requests

resp = requests.post(
    "https://rutoken.ai/v1/rerank",
    headers={"Authorization": "Bearer sk-xxxx"},
    json={
        "model": "bge-reranker-v2-m3",
        "query": "What is the capital of France?",
        "documents": [
            "Berlin is the capital of Germany.",
            "Paris is the capital and largest city of France.",
            "France is famous for its wine.",
        ],
        "top_n": 2,
        "return_documents": True,
    },
)
for r in resp.json()["results"]:
    print(r["index"], r["relevance_score"])

Node.js

const resp = await fetch("https://rutoken.ai/v1/rerank", {
  method: "POST",
  headers: { "Content-Type": "application/json", Authorization: "Bearer sk-xxxx" },
  body: JSON.stringify({
    model: "bge-reranker-v2-m3",
    query: "What is the capital of France?",
    documents: [
      "Berlin is the capital of Germany.",
      "Paris is the capital and largest city of France.",
      "France is famous for its wine.",
    ],
    top_n: 2,
    return_documents: true,
  }),
});
const { results } = await resp.json();
for (const r of results) console.log(r.index, r.relevance_score);

Response

json

{
  "results": [
    {
      "index": 1,
      "relevance_score": 0.9921,
      "document": {"text": "Paris is the capital and largest city of France."}
    },
    {
      "index": 2,
      "relevance_score": 0.1573,
      "document": {"text": "France is famous for its wine."}
    }
  ],
  "usage": {
    "prompt_tokens": 42,
    "completion_tokens": 0,
    "total_tokens": 42
  }
}

Field	Type	Description
`results[].index`	integer	Position of the document in the request `documents` array.
`results[].relevance_score`	number	Relevance score; higher is more relevant. Results are sorted by this value.
`results[].document`	object	The document, only when `return_documents` is `true`.
`usage`	object	Token counts used for billing.

Scores are comparable within one request but their range depends on the model. Pick a cut-off threshold per model rather than using a fixed value.

← Previous

Embeddings

Moderations