Rerank

Rerank search results for relevance.

POST /v1/rerank

Overview

Reranking improves search quality by scoring how relevant each document is to a query. Use after initial retrieval to boost precision.

Query: "How do I reset my password?"

Initial Results (BM25/embedding search):
1. "Password policies and requirements"
2. "How to reset your password"     ← Most relevant
3. "Account security settings"
4. "Contact support"

After Rerank:
1. "How to reset your password"     ← Moved to top
2. "Password policies and requirements"
3. "Account security settings"
4. "Contact support"

Request

curl https://api.gateflow.ai/v1/rerank \
  -H "Authorization: Bearer gw_prod_..." \
  -H "Content-Type: application/json" \
  -d '{
    "model": "rerank-english-v3.0",
    "query": "How do I reset my password?",
    "documents": [
      "Password policies and requirements",
      "How to reset your password",
      "Account security settings",
      "Contact support"
    ]
  }'

Parameters

Parameter	Type	Required	Description
model	string	Yes	Rerank model ID
query	string	Yes	The search query
documents	array	Yes	Documents to rerank
top_n	integer	No	Return only top N results
return_documents	boolean	No	Include document text in response

Supported Models

Model	Provider	Best For
rerank-english-v3.0	Cohere	English documents
rerank-multilingual-v3.0	Cohere	Multiple languages
rerank-english-v2.0	Cohere	Legacy, lower cost

Document Formats

// Simple strings
"documents": [
  "First document text",
  "Second document text"
]

// Objects with metadata
"documents": [
  {"text": "First document", "id": "doc1"},
  {"text": "Second document", "id": "doc2"}
]

Response

{
  "id": "rerank-abc123",
  "results": [
    {
      "index": 1,
      "relevance_score": 0.9875,
      "document": {
        "text": "How to reset your password"
      }
    },
    {
      "index": 0,
      "relevance_score": 0.7234,
      "document": {
        "text": "Password policies and requirements"
      }
    },
    {
      "index": 2,
      "relevance_score": 0.4567,
      "document": {
        "text": "Account security settings"
      }
    },
    {
      "index": 3,
      "relevance_score": 0.1234,
      "document": {
        "text": "Contact support"
      }
    }
  ],
  "meta": {
    "billed_units": {
      "search_units": 1
    }
  },
  "gateflow": {
    "request_id": "req_xyz789",
    "provider": "cohere",
    "latency_ms": 145,
    "cost": {
      "total": 0.001
    }
  }
}

Response Fields

Field	Type	Description
id	string	Rerank request ID
results	array	Reranked documents
meta	object	Billing information

Result Object

Field	Type	Description
index	integer	Original position in input
relevance_score	float	Relevance score (0-1)
document	object	Document (if return_documents: true)

Examples

Basic Reranking

Python

import requests

response = requests.post(
    "https://api.gateflow.ai/v1/rerank",
    headers={
        "Authorization": "Bearer gw_prod_...",
        "Content-Type": "application/json"
    },
    json={
        "model": "rerank-english-v3.0",
        "query": "machine learning basics",
        "documents": [
            "Introduction to Python programming",
            "Machine learning fundamentals and concepts",
            "Data science with pandas",
            "Deep learning neural networks"
        ],
        "top_n": 2
    }
)

results = response.json()["results"]
for r in results:
    print(f"Score: {r['relevance_score']:.4f} - Index: {r['index']}")

cURL

curl https://api.gateflow.ai/v1/rerank \
  -H "Authorization: Bearer gw_prod_..." \
  -H "Content-Type: application/json" \
  -d '{
    "model": "rerank-english-v3.0",
    "query": "machine learning basics",
    "documents": [
      "Introduction to Python programming",
      "Machine learning fundamentals and concepts",
      "Data science with pandas",
      "Deep learning neural networks"
    ],
    "top_n": 2
  }'

RAG Pipeline

# 1. Initial retrieval (fast, recall-optimized)
initial_results = vector_db.search(
    query="How do I configure SSL?",
    limit=20
)

# 2. Rerank for precision
reranked = requests.post(
    "https://api.gateflow.ai/v1/rerank",
    headers={"Authorization": "Bearer gw_prod_..."},
    json={
        "model": "rerank-english-v3.0",
        "query": "How do I configure SSL?",
        "documents": [r["text"] for r in initial_results],
        "top_n": 5
    }
).json()

# 3. Use top results for context
context = "\n".join([
    initial_results[r["index"]]["text"]
    for r in reranked["results"]
])

# 4. Generate answer
response = client.chat.completions.create(
    model="gpt-4o",
    messages=[
        {"role": "system", "content": f"Context:\n{context}"},
        {"role": "user", "content": "How do I configure SSL?"}
    ]
)

With Document IDs

documents = [
    {"text": "Password reset instructions", "id": "doc-123"},
    {"text": "Account security guide", "id": "doc-456"},
    {"text": "Contact information", "id": "doc-789"}
]

response = requests.post(
    "https://api.gateflow.ai/v1/rerank",
    headers={"Authorization": "Bearer gw_prod_..."},
    json={
        "model": "rerank-english-v3.0",
        "query": "reset password",
        "documents": documents,
        "return_documents": True
    }
).json()

# Access by original index
for result in response["results"]:
    original_doc = documents[result["index"]]
    print(f"ID: {original_doc['id']}, Score: {result['relevance_score']}")

Multilingual

response = requests.post(
    "https://api.gateflow.ai/v1/rerank",
    headers={"Authorization": "Bearer gw_prod_..."},
    json={
        "model": "rerank-multilingual-v3.0",
        "query": "Wie setze ich mein Passwort zurück?",  # German
        "documents": [
            "Anleitung zum Zurücksetzen des Passworts",  # German
            "Password reset instructions",               # English
            "Instructions de réinitialisation",          # French
        ]
    }
).json()

Use Cases

Search Quality

Improve search results by reranking top candidates:

• E-commerce product search
• Documentation search
• Support ticket matching

RAG Enhancement

Better context selection for LLM:

• Retrieve 20 candidates with embeddings
• Rerank to top 5 most relevant
• Use top 5 as LLM context

Duplicate Detection

Find similar documents:

• Rerank against a reference document
• High scores indicate similarity

Pricing

Model	Price per 1000 searches
rerank-english-v3.0	$1.00
rerank-multilingual-v3.0	$1.00
rerank-english-v2.0	$0.50

Error Codes

Code	Description
invalid_documents	Documents array is empty or invalid
query_too_long	Query exceeds maximum length
too_many_documents	Exceeded document limit (usually 1000)

See Error Handling for details.