Rerank API

Rerank documents or passages by relevance to a query. Compatible with the Cohere Rerank API format. Useful for RAG pipelines, search result refinement, and context window optimization.

Base URL: https://api.jarvisclaw.ai/v1

Authentication

Method	Header	Description
API Key	Authorization: Bearer sk-...	Platform handles billing automatically
x402	PAYMENT-SIGNATURE	Agent pays per call via x402

Endpoint

POST /v1/rerank

Rerank a list of documents by relevance to a query.

Request

{
  "model": "cohere/rerank-v3.5",
  "query": "What is the capital of France?",
  "documents": [
    "Paris is the capital of France.",
    "Berlin is the capital of Germany.",
    "France is a country in Europe.",
    "The Eiffel Tower is in Paris."
  ],
  "top_n": 3,
  "return_documents": true
}

Parameters

Parameter	Type	Required	Description
model	string	Yes	Rerank model to use
query	string	Yes	The search query to rank against
documents	array	Yes	List of text strings or objects to rerank
top_n	integer	No	Return only the top N results (default: all)
return_documents	boolean	No	Include document text in response (default: false)

Response

{
  "id": "rerank-abc123",
  "results": [
    {
      "index": 0,
      "relevance_score": 0.98,
      "document": { "text": "Paris is the capital of France." }
    },
    {
      "index": 3,
      "relevance_score": 0.82,
      "document": { "text": "The Eiffel Tower is in Paris." }
    },
    {
      "index": 2,
      "relevance_score": 0.45,
      "document": { "text": "France is a country in Europe." }
    }
  ],
  "meta": {
    "billed_units": { "search_units": 1 }
  }
}

Quick Start

Python

from openai import OpenAI

client = OpenAI(
    api_key="sk-your-api-key",
    base_url="https://api.jarvisclaw.ai/v1"
)

# Using httpx directly (Cohere-compatible format)
import httpx

response = httpx.post(
    "https://api.jarvisclaw.ai/v1/rerank",
    headers={"Authorization": "Bearer sk-your-api-key"},
    json={
        "model": "cohere/rerank-v3.5",
        "query": "machine learning frameworks",
        "documents": [
            "TensorFlow is a popular ML framework by Google.",
            "React is a JavaScript UI library.",
            "PyTorch is widely used for deep learning research.",
            "Django is a Python web framework."
        ],
        "top_n": 2,
        "return_documents": True
    }
)
print(response.json())

curl

curl https://api.jarvisclaw.ai/v1/rerank \
  -H "Authorization: Bearer sk-your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "cohere/rerank-v3.5",
    "query": "machine learning frameworks",
    "documents": [
      "TensorFlow is a popular ML framework by Google.",
      "React is a JavaScript UI library.",
      "PyTorch is widely used for deep learning research."
    ],
    "top_n": 2,
    "return_documents": true
  }'

Available Models

No rerank model is currently published

The /v1/rerank route is registered and Cohere-compatible, but the current model catalogue (GET /v1/models) lists no rerank model — so a request naming one of the models below is rejected as an unknown model until a rerank channel is enabled on your deployment.

Check GET /v1/models before building against this endpoint.

Reference list for the models this endpoint is designed to proxy:

Model	Provider	Description
cohere/rerank-v3.5	Cohere	Latest multilingual rerank model
cohere/rerank-english-v3.0	Cohere	English-optimized rerank
cohere/rerank-multilingual-v3.0	Cohere	Multilingual rerank
jina/jina-reranker-v2	Jina AI	Fast and accurate reranker

Use Cases

• RAG pipelines — Rerank retrieved chunks before feeding to LLM
• Search refinement — Improve search result ordering
• Context optimization — Select the most relevant documents for limited context windows
• Multi-stage retrieval — Coarse retrieval → rerank → LLM generation