Tīrtha is still being built, so some features and models may not work as expected yet. Billing always follows the prices shown. Something broken? Email [email protected].

Tīrtha

Rerank

A reranker reads your query together with each document and scores how well that document answers it. You get the documents back best first, each with a score. It is slower and more precise than vector search, so it runs second: embeddings find 20 to 50 likely matches, the reranker orders them.

Request

POST https://api.tirtha.ai/v1/rerank with your key. Send model, query (a string) and documents (a list of strings). Two optional fields: top_n returns only the best n, and return_documents: true puts each document’s text in its result. Any other field is refused by name.

curl https://api.tirtha.ai/v1/rerank \
  -H "Authorization: Bearer $TIRTHA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "tirtha/qwen3-reranker-8b",
    "query": "How long does shipping take?",
    "documents": [
      "Orders ship within three to five business days.",
      "You can reset your password from the login page.",
      "Refunds go back to the original payment method."
    ],
    "top_n": 2,
    "return_documents": true
  }'
import os, requests

API = "https://api.tirtha.ai/v1"
H = {"Authorization": "Bearer " + os.environ["TIRTHA_API_KEY"]}

def rerank(query, documents, top_n=None):
    """Up to 100 documents, 200,000 characters with the query."""
    body = {"model": "tirtha/qwen3-reranker-8b",
            "query": query, "documents": documents}
    if top_n:
        body["top_n"] = top_n
    r = requests.post(API + "/rerank", headers=H, json=body, timeout=130)
    if r.status_code != 200:
        raise RuntimeError(r.status_code, r.json().get("error"))
    return r.json()["results"]            # best first

docs = ["Orders ship within three to five business days.",
        "You can reset your password from the login page.",
        "Refunds go back to the original payment method."]
for hit in rerank("How long does shipping take?", docs, top_n=2):
    print(round(hit["relevance_score"], 3), docs[hit["index"]])
const API = "https://api.tirtha.ai/v1";
const docs = [
  "Orders ship within three to five business days.",
  "You can reset your password from the login page.",
  "Refunds go back to the original payment method.",
];

const r = await fetch(API + "/rerank", {
  method: "POST",
  headers: {
    "Authorization": "Bearer " + process.env.TIRTHA_API_KEY,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    model: "tirtha/qwen3-reranker-8b",
    query: "How long does shipping take?",
    documents: docs,
    top_n: 2,
  }),
});
const body = await r.json();
if (!r.ok) throw new Error(r.status + " " + JSON.stringify(body.error));

for (const hit of body.results) {     // best first
  console.log(hit.relevance_score.toFixed(3), docs[hit.index]);
}

Response

results is sorted best first. index is the position of the document in the list you sent in this call. document appears only with return_documents: true.

Example shape; real recorded reply coming. The field names and types are the ones the API returns; the values are examples.

{
  "object": "list",
  "results": [
    {
      "index": 0,
      "relevance_score": 0.9871,
      "document": "Orders ship within three to five business days."
    },
    {
      "index": 2,
      "relevance_score": 0.0214,
      "document": "Refunds go back to the original payment method."
    }
  ],
  "model": "tirtha/qwen3-reranker-8b",
  "usage": {
    "tokens": 260,
    "charged": "0.000016",
    "estimated": false
  }
}
FieldTypeMeaning
results[].indexintegerPosition of the document in your documents list (0 is the first).
results[].relevance_scorenumberHow well it answers the query; higher is better.
results[].documentstringThe document text, only with return_documents: true.
usage.tokensintegerInput tokens the model counted: the billed amount.
usage.chargedstringWhat this call cost, in US dollars, with 6 decimals.
usage.estimatedbooleantrue only if the model did not report a count and our estimate was billed instead.

Pricing

Per 1M input tokens. The model reads the query again with every document, so the count grows with the number of documents, not only their length. Each model’s price is on the Rerank tab, the one price list for the site.

Before the call runs, a hold for an upper estimate is set aside from your credit; the bill is the counted tokens, and the reply gives the exact amount in usage.charged. Requests that fail are not charged.

Limits

LimitValue
Documents per callUp to 100
Characters per callUp to 200,000 in total, query included
Each documentNot empty. The gateway has no separate cap per document; the query and each document together must fit what the model accepts, or the model refuses with 400 request_rejected and nothing is charged.
top_n1 up to the number of documents sent. Leave it out to get them all back.
Requests per minuteSet per key. A key with a limit gets 429 quota_exceeded over it, with Retry-After: 60.
At capacity429 media_busy with Retry-After: 2; nothing is charged.
TimeThe gateway waits up to 120 seconds for the model. Set your client timeout a little above that.

Errors

StatusCodeMessageWhat to do
400invalid_input'query' and 1-100 non-empty 'documents' strings are required.Also sent when the query plus documents pass 200,000 characters, or a document is empty.
400invalid_top_n'top_n' must be 1-<number of documents>.Send a whole number no larger than the documents you sent.
404model_not_foundUnknown rerank model.Use an id from the Rerank tab, with the tirtha/ prefix.
400request_rejectedThe request was rejected. Nothing was charged.The model refused the input, most often a query plus document longer than it accepts. Use shorter chunks.
402insufficient_creditsNot enough prepaid credit for this request (it may need <amount>).Add credits. A real recorded reply is below.

Recorded reply, 2026-11-13: HTTP 402 from a key with no credit.

{
  "error": {
    "message": "Not enough prepaid credit for this request (it may need 0.000038).",
    "type": "invalid_request_error",
    "code": "insufficient_credits"
  }
}

Every other error these routes can return (key, terms, rate limit, spend cap, busy, billing) is on Common errors, with what to do for each. Anything refused before the model runs costs nothing.

Best practices

  1. Rerank the top 20 to 50, not everything.

    The reranker reads every pair of query and document, so cost and time grow with each document you add. Vector search narrows a large collection fast; give the reranker only its best 20 to 50:

    # uses docs, scores and question from the full example on
    # /docs/embeddings, and rerank() from the Python request example
    order = sorted(range(len(docs)), key=lambda i: scores[i], reverse=True)
    candidates = order[:30]
    hits = rerank(question, [docs[i] for i in candidates], top_n=5)
    best = [docs[candidates[h["index"]]] for h in hits]
  2. Map index back to your own ids.

    index points into the list you sent in this call, not into your database. Keep the candidate list you built, as above, and look each result up in it.

  3. Use top_n when you only show a few.

    If the page shows five results, ask for five. The reply is smaller and already in order.

  4. Compare scores within one call.

    A score ranks documents against one query. Do not compare scores across queries or models, and do not read 0.8 as twice as good as 0.4. If you need a cut-off, pick it from a few dozen of your own real queries with known good and bad answers.

  5. Turn records into short text, key fields first.

    The reranker reads text. For products, tickets or rows, write each record as a few labelled lines with the fields that decide relevance first, so a long description cannot push them out:

    # a product record as one short block of text, the key fields first
    def as_text(p):
        return (f"Title: {p['title']}\n"
                f"Category: {p['category']}\n"
                f"Price: {p['price']}\n"
                f"Description: {p['description']}")
    
    documents = [as_text(p) for p in products]   # products: your own records
  6. Rerank the chunks you embedded, not whole files.

    A long document mixes topics and can lose to a short one that answers the question directly.

  7. Keep the query short and the documents clean.

    The query is read once per document, so a long query multiplies. Strip markup, boilerplate and empty strings; an empty document refuses the whole call with invalid_input.

Full example

The complete search flow (embed once, the query with its instruction, normalized vectors, then this reranker on the top candidates) is the full example on the Embeddings page. It runs as pasted.

Checked against the API code on 2026-11-14. Tīrtha is still being built; limits and fields may change, and this page changes with them.