Rerank

Re-rank a list of documents based on their relevance to a query. Reranking is commonly used as a second-stage retrieval step to improve the precision of search results after an initial retrieval pass (e.g., vector search or keyword search).

Endpoint

POST https://api.tensoras.ai/v1/rerank

Authentication

Authorization: Bearer tns_your_key_here

Request Body

Parameter	Type	Required	Default	Description
`model`	string	Yes	—	The reranking model to use.
`query`	string	Yes	—	The search query to rank documents against.
`documents`	array	Yes	—	A list of documents to rerank. Each element can be a string or an object with a `text` field.
`top_n`	integer	No	All documents	The number of top-ranked results to return. If omitted, all documents are returned in ranked order.
`return_documents`	boolean	No	`true`	Whether to include the document text in the response.

Response Body

{
  "object": "list",
  "results": [
    {
      "index": 2,
      "relevance_score": 0.9865,
      "document": {
        "text": "Machine learning is a subset of artificial intelligence..."
      }
    },
    {
      "index": 0,
      "relevance_score": 0.7432,
      "document": {
        "text": "AI has transformed many industries..."
      }
    },
    {
      "index": 1,
      "relevance_score": 0.1204,
      "document": {
        "text": "The stock market closed higher today..."
      }
    }
  ],
  "model": "bge-reranker-v2-m3",
  "usage": {
    "total_tokens": 156
  }
}

Field	Type	Description
`object`	string	Always `"list"`.
`results`	array	The reranked results, sorted by relevance score in descending order.
`results[].index`	integer	The original index of the document in the input array.
`results[].relevance_score`	number	The relevance score between 0 and 1. Higher scores indicate greater relevance.
`results[].document`	object	The document text, included when `return_documents` is `true`.
`model`	string	The reranking model used.
`usage`	object	Token usage statistics.

Examples

Basic Reranking

curl

curl https://api.tensoras.ai/v1/rerank \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer tns_your_key_here" \
  -d '{
    "model": "bge-reranker-v2-m3",
    "query": "What is machine learning?",
    "documents": [
      "AI has transformed many industries including healthcare and finance.",
      "The stock market closed higher today after positive earnings reports.",
      "Machine learning is a subset of artificial intelligence that enables systems to learn from data.",
      "The new restaurant downtown serves excellent Italian cuisine.",
      "Deep learning uses neural networks with many layers to model complex patterns."
    ],
    "top_n": 3
  }'

Python

import requests
 
response = requests.post(
    "https://api.tensoras.ai/v1/rerank",
    headers={
        "Content-Type": "application/json",
        "Authorization": "Bearer tns_your_key_here",
    },
    json={
        "model": "bge-reranker-v2-m3",
        "query": "What is machine learning?",
        "documents": [
            "AI has transformed many industries including healthcare and finance.",
            "The stock market closed higher today after positive earnings reports.",
            "Machine learning is a subset of artificial intelligence that enables systems to learn from data.",
            "The new restaurant downtown serves excellent Italian cuisine.",
            "Deep learning uses neural networks with many layers to model complex patterns.",
        ],
        "top_n": 3,
    },
)
 
results = response.json()["results"]
for result in results:
    print(f"Score: {result['relevance_score']:.4f} | {result['document']['text'][:80]}...")

Node.js

const response = await fetch("https://api.tensoras.ai/v1/rerank", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    Authorization: "Bearer tns_your_key_here",
  },
  body: JSON.stringify({
    model: "bge-reranker-v2-m3",
    query: "What is machine learning?",
    documents: [
      "AI has transformed many industries including healthcare and finance.",
      "The stock market closed higher today after positive earnings reports.",
      "Machine learning is a subset of artificial intelligence that enables systems to learn from data.",
      "The new restaurant downtown serves excellent Italian cuisine.",
      "Deep learning uses neural networks with many layers to model complex patterns.",
    ],
    top_n: 3,
  }),
});
 
const data = await response.json();
for (const result of data.results) {
  console.log(
    `Score: ${result.relevance_score.toFixed(4)} | ${result.document.text.slice(0, 80)}...`
  );
}

Reranking in a RAG Pipeline

Combine vector search with reranking for higher-quality retrieval.

Python

import requests
 
API_BASE = "https://api.tensoras.ai/v1"
HEADERS = {
    "Content-Type": "application/json",
    "Authorization": "Bearer tns_your_key_here",
}
 
query = "How do I configure SSL certificates?"
 
# Step 1: Retrieve candidate documents via vector search
retrieval_response = requests.post(
    f"{API_BASE}/knowledge-bases/kb_abc123/retrieve",
    headers=HEADERS,
    json={
        "query": query,
        "top_k": 20,
        "search_type": "vector",
    },
)
candidates = retrieval_response.json()["results"]
 
# Step 2: Rerank the candidates for better precision
rerank_response = requests.post(
    f"{API_BASE}/rerank",
    headers=HEADERS,
    json={
        "model": "bge-reranker-v2-m3",
        "query": query,
        "documents": [c["text"] for c in candidates],
        "top_n": 5,
    },
)
reranked = rerank_response.json()["results"]
 
# Step 3: Use the top reranked results as context for generation
context = "\n\n".join([r["document"]["text"] for r in reranked])
print(f"Top {len(reranked)} reranked results ready for generation.")

Error Handling

{
  "error": {
    "message": "documents array must contain at least 1 document",
    "type": "invalid_request_error",
    "param": "documents",
    "code": "invalid_value"
  }
}

Embeddings Models