Rerank

A rerank model takes a query and a list of documents and scores how relevant each document is to the query. Use it after a fast first search (keyword, or embeddings) to put the best results on top before you show them or pass them to a chat model.

Rerank is not an OpenAI endpoint, so the OpenAI SDKs have no method for it. Call it over plain HTTP with the same API key. The request and response follow OpenRouter's rerank API, which is Cohere's rerank shape.

Endpoint

POST https://backend.sovereigneg.com/v1/rerank

Request

Any other field is ignored and never sent to the provider.

Images. On models whose input_modalities list image, a document can be {"image": "data:image/png;base64,..."} (or carry both text and image). Images must be inline base64 data URLs; hosted image URLs are refused. Up to 20 images per request.

Example

curl https://backend.sovereigneg.com/v1/rerank \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "cohere/rerank-v3.5",
    "query": "What is the capital of Egypt?",
    "documents": [
      "Paris is the capital of France.",
      "Cairo is the capital of Egypt.",
      "Madrid is the capital of Spain."
    ],
    "top_n": 2
  }'

import os
import httpx
 
response = httpx.post(
    "https://backend.sovereigneg.com/v1/rerank",
    headers={"Authorization": f"Bearer {os.environ['OPENAI_API_KEY']}"},
    json={
        "model": "cohere/rerank-v3.5",
        "query": "What is the capital of Egypt?",
        "documents": [
            "Paris is the capital of France.",
            "Cairo is the capital of Egypt.",
            "Madrid is the capital of Spain.",
        ],
        "top_n": 2,
    },
    timeout=30,
)
response.raise_for_status()
for result in response.json()["results"]:
    print(result["index"], round(result["relevance_score"], 3))

const response = await fetch("https://backend.sovereigneg.com/v1/rerank", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.OPENAI_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    model: "cohere/rerank-v3.5",
    query: "What is the capital of Egypt?",
    documents: [
      "Paris is the capital of France.",
      "Cairo is the capital of Egypt.",
      "Madrid is the capital of Spain.",
    ],
    top_n: 2,
  }),
})
 
const { results } = await response.json()
for (const r of results) console.log(r.index, r.relevance_score)

Response

{
  "id": "req_8f2c1a7d9e4b",
  "model": "cohere/rerank-v3.5",
  "results": [
    { "index": 1, "relevance_score": 0.98, "document": { "text": "Cairo is the capital of Egypt." } },
    { "index": 0, "relevance_score": 0.07, "document": { "text": "Paris is the capital of France." } }
  ],
  "usage": { "total_tokens": 42, "search_units": 1, "cost": 0.1 }
}

• results is sorted from most to least relevant. index is the document's position in the documents you sent, so you can map each result back to your own data.
• relevance_score is the model's score. Compare scores within one response; different models use different scales.
• id is the same request ID as the X-Request-Id header. Quote it when you contact support.
• usage.cost is what this request cost, in EGP. The other usage fields come from the model's provider: total_tokens when it counts tokens, search_units for Cohere models.

Rerank responses are never streamed: each request returns one JSON body.

Available models

Rerank models are listed in the model catalog under Modality: Rerank, or with GET https://backend.sovereigneg.com/v1/models where modality is "rerank". Each model page shows ready-to-run code for that model, and input_modalities tells you whether it takes images.

Pricing

Each rerank request is billed once, at the model's catalog price in EGP. The catalog shows that price in the model's own unit: per 1M input tokens (the query plus the documents) for most models, or per search for Cohere models. One search is one query with up to 100 documents, and a document longer than 500 tokens together with the query counts as one document per started 500 tokens. usage.cost on the response is that request's price. Your usage page shows what was actually charged, after your spend limits.

You need credit left to call a rerank model: with none, the request is refused with 402 before anything runs.

Errors