More APIs

Second-stage retrieval

Reranking

Rerank candidate documents by relevance to a query using supported reranking models.

Reranking models are accessed via a single unified endpoint. DEVUP AI provides a consistent request and response contract across all supported reranker models, with real per-token billing based on actual usage.

Endpoint

POSThttps://api.devupai.com/v1/rerank

Reranking flow

User query

Initial retrieval

Candidate documents

Reranker API

Ranked results

Selected context

1. User query

2. Initial retrieval

3. Candidate documents

4. Reranker API

5. Ranked results

6. Selected context

Quickstart example

The example below uses the Qwen/Qwen3-Reranker-8B model to rank a list of documents. Since this is a custom unified endpoint, standard HTTP clients are recommended over the OpenAI SDK.

import os
import requests

response = requests.post(
    "https://api.devupai.com/v1/rerank",
    headers={
        "Authorization": "Bearer " + os.environ['DEVUP_API_KEY'],
        "Content-Type": "application/json"
    },
    json={
        "model": "Qwen/Qwen3-Reranker-8B",
        "query": "What is the capital of France?",
        "documents": [
            "Paris is the capital of France.",
            "Berlin is the capital of Germany.",
            "The Eiffel Tower is located in Paris."
        ],
        "top_n": 2,
        "return_documents": False
    }
)

print(response.json())

Request parameters

All supported reranker models use a single, unified JSON request schema.

Required input

model

Reranker model identifier (e.g., Qwen/Qwen3-Reranker-8B).

query

The search query (must be a non-empty string).

documents

A non-empty array of non-empty strings to rank against the query.

Optional parameters

top_n

Integer between 1 and the length of documents. Defaults to returning all documents.

return_documents

Boolean indicating whether to include the document text in the results. Default is false.

Response anatomy

Returned fields

object: Always list.
model: The exact model identifier used.
results: Array of ranked document scores, sorted by relevance_score descending.
results[].index: The original position in the documents input array.
results[].document: Included only when return_documents: true.
_devup: Platform-specific metadata (cost and balance).

Illustrative response

json

{
  "object": "list",
  "model": "Qwen/Qwen3-Reranker-8B",
  "results": [
    {
      "index": 2,
      "relevance_score": 0.9732
    },
    {
      "index": 0,
      "relevance_score": 0.6121
    }
  ],
  "_devup": {
    "cost_dzd": 0.05,
    "balance_dzd": 12.50
  }
}

Score interpretation

Relative ordering

Scores rank documents relative to the current query. A higher value generally indicates stronger predicted relevance.

Not a probability

Scores should not be interpreted as factual confidence. Scales differ between models, and thresholds should be calibrated on the application's own dataset.

RAG workflow

Reranking can improve relevance for some retrieval workloads and datasets. A standard implementation pattern:

Retrieve candidate chunks using vector search or another retrieval method.
Send the query and candidate documents to the reranker API.
Extract and map returned relevance scores back to the original documents using the index field.
Sort or select the highest-ranked candidates.
Send only the selected context to the generation model.

Practical use cases

Retrieval-Augmented Generation

Provide highly relevant context to generation models.

Search result refinement

Reorder keyword or semantic search results for end users.

Document question answering

Locate exact passages within large document sets.

Recommendation refinement

Filter candidate items against a specific user intent.

Knowledge-base retrieval

Rank support articles for automated ticket resolution.

Limitations and operations

When implementing reranking in production systems, consider these operational realities:

Model behavior: The request and response contract is uniform across models, but score ranges and calibration still vary by model.
Latency: Reranking adds sequential latency after the initial retrieval step.
Payload limits: The API does not currently enforce an explicit maximum on the number of documents or payload size — requests are only bounded by the platform's general body-size limits and the upstream model's context window, so very large document sets may fail or time out rather than being rejected upfront.
Evaluation: Always benchmark retrieval quality improvements on real-world datasets.

Browse Reranking Models