Rerank

POST /v1/rerank

Cross-encoder reranking. After vector search returns top-K candidates, rerank narrows to the most relevant using a heavier model. Boosts Indonesian retrieval quality from ~85% to ~98% in our benchmarks.

Indonesian-tuned cross-encoder reranker, instruction-aware.

Request body

Field Type Required Description
model string yes Must be epithre-rerank.
query string yes The user search query.
documents array yes 1-64 candidate documents (strings). Typically the top-K from your vector search.
top_n int no Return top N after sorting (default: all).
return_documents bool no If true, response includes document text. Default false (just index + score).
instruction string no Custom reranking instruction. Overrides the default Indonesian-tuned instruction.

Response shape

{
  "id": "2b475d38-c17c-43b9-ba9a-7f485af38e0f",
  "results": [
    {"index": 3, "relevance_score": 0.1480, "document": {"text": "..."}},
    {"index": 0, "relevance_score": 0.0567, "document": {"text": "..."}},
    {"index": 1, "relevance_score": 0.0000}
  ],
  "meta": {"billed_units": {"search_units": 1}}
}

results are sorted by relevance_score descending. If top_n is unset, all input documents appear in results; if set, only the top N.

document.text is included when return_documents: true.

Example

import httpx
r = httpx.post(
    "https://api.epithre.com/v1/rerank",
    headers={"Authorization": f"Bearer {EPITHRE_KEY}"},
    json={
        "model": "epithre-rerank",
        "query": "perlindungan hutan lindung dari penebangan",
        "documents": [
            "UU 41/1999 pasal 50 - perusakan hutan",
            "Permen LHK satwa dilindungi",
            "Keppres pemilu 2024",
            "Pasal pengelolaan hutan lindung",
        ],
        "top_n": 3,
        "return_documents": True,
    },
).json()

for r in r["results"]:
    print(f'{r["relevance_score"]:.3f}  {r["document"]["text"]}')
# 0.148  Pasal pengelolaan hutan lindung
# 0.057  UU 41/1999 pasal 50 - perusakan hutan
# 0.000  Permen LHK satwa dilindungi   (irrelevant)

Score semantics

Scores are P(yes) / (P(yes) + P(no)) from the underlying cross-encoder. Range [0, 1]. Indonesian queries often produce low absolute values (0.05-0.30 for true matches).

Use rank order, not absolute threshold. A score of 0.15 may be the strongest match in your candidate set. Don't filter by score absolute value.

Combining with embed

The standard pattern:

# 1. Retrieve top-K via embed search (fast, broad recall)
qv = client.embeddings.create(model="epithre-embed", input=[query]).data[0].embedding
# ... cosine search returns top 50 candidates

# 2. Rerank to top 5 (slow, high precision)
candidates = [your_corpus[i] for i in top_50_indices]
r = httpx.post(".../v1/rerank", ..., json={
    "model": "epithre-rerank",
    "query": query,
    "documents": candidates,
    "top_n": 5,
    "return_documents": True,
}).json()

# 3. Use the reranked top-5 as context for chat completions

Full pattern in RAG cookbook.

Custom instructions

The default instruction is tuned for Indonesian general retrieval. For specialized domains, override:

{
    "instruction": "Given a query about Indonesian environmental law, rank the most legally-authoritative documents first.",
    ...
}

The instruction prefix influences how the reranker weighs aspects of relevance (recency, authority, specificity, etc).

Pricing

See pricing.

Errors

HTTP Cause
400 Missing query or documents, more than 64 documents, invalid top_n.
429 Rate limit.

See also