OneRouter Rerank API

OneRouter Now Supports the Rerank API

OneRouter Now Supports the Rerank API
OneRouter Now Supports the Rerank API
OneRouter Now Supports the Rerank API
Date

Dec 21, 2025

Author

Andrew Zheng

How Does Reranker Work?

A reranker takes a query and a set of candidate documents as input, returning a reordered list based on their semantic relevancy. The documents are typically the preliminary results from an embedding-based retrieval system, and the reranker refines the ranks of these candidate documents and provides more accurate relevancy scores.

Unlike embedding models that encode queries and documents separately, rerankers are cross-encoders that jointly process a pair of query and document, enabling more accurate relevancy prediction. Thus, it is a common practice to apply a reranker on the top candidates retrieved with embedding-based search (or with lexical search algorithms such as BM25 and TF-IDF).


Get Started

Example with Texts

In the example below, we use the Rerank API endpoint to index the list of documents from most to least relevant to the query "What is the capital of the United States?".

Request

In this example, the documents being passed in are a list of strings:

import requests
import json

url = "https://llm.onerouter.pro/v1/rerank"
headers = {
    "Content-Type": "application/json",
    "Authorization": "Bearer {{API_KEY}}"
}
data = {
    "model": "voyage-rerank-2.5",
    "query": "What is the capital of the United States?",
    "top_n": 3,
    "documents": [
        "Carson City is the capital city of the American state of Nevada. At the 2010 United States Census, Carson City had a population of 55,274.",
        "The Commonwealth of the Northern Mariana Islands is a group of islands in the Pacific Ocean that are a political division controlled by the United States. Its capital is Saipan.",
        "Charlotte Amalie is the capital and largest city of the United States Virgin Islands. It has about 20,000 people. The city is on the island of Saint Thomas.",
        "Washington, D.C. (also known as simply Washington or D.C., and officially as the District of Columbia) is the capital of the United States. It is a federal district. The President of the USA and many major national government offices are in the territory. This makes it the political center of the United States of America.",
        "Capital punishment has existed in the United States since before the United States was a country. As of 2017, capital punishment is legal in 30 of the 50 states. The federal government (including the United States military) also uses capital punishment.",
    ]        
}

response = requests.post(url, headers=headers, data=json.dumps(data))

print(response.json())

Response

{
  "id": "26c8ad0bb95011f0a5edda799fbd82e9",
  "results": [
    {
      "index": 3, // "Washington, D.C. (also known as simply Washington or D.C., and officially as the District of Columbia) ..."
      "relevance_score": 0.9990564
    },
    {
      "index": 4, // "Capital punishment has existed in the United States since before the United States was a country. As of 2017 ..."
      "relevance_score": 0.7516481
    },
    {
      "index": 1, // "The Commonwealth of the Northern Mariana Islands is a group of islands in the Pacific Ocean that are a political division ..."
      "relevance_score": 0.08882029
    },
    {
      "index": 0, // "Carson City is the capital city of the American state of Nevada. At the 2010 United States Census, Carson City had a ..."
      "relevance_score": 0.058238626
    },
    {
      "index": 2, // ""Charlotte Amalie is the capital and largest city of the United States Virgin Islands. It has about 20,000 people ..."
      "relevance_score": 0.019946935
    }
  ]
}


Example with Structured Data

To achieve optimal performance with structured data, we recommend formatting your documents as YAML strings.

Request

import requests
import json

url = "https://llm.onerouter.pro/v1/rerank"
headers = {
    "Content-Type": "application/json",
    "Authorization": "Bearer {{API_KEY}}"
}
data = {
    "model": "voyage-rerank-2.5",
    "query": "What is the capital of the United States?",
    "top_n": 3,
    "documents": [
        {
            "Title": "Facts about Carson City",
            "Content": "Carson City is the capital city of the American state of Nevada. At the 2010 United States Census, Carson City had a population of 55,274.",
        },
        {
            "Title": "The Commonwealth of Northern Mariana Islands",
            "Content": "The Commonwealth of the Northern Mariana Islands is a group of islands in the Pacific Ocean that are a political division controlled by the United States. Its capital is Saipan.",
        },
        {
            "Title": "The Capital of United States Virgin Islands",
            "Content": "Charlotte Amalie is the capital and largest city of the United States Virgin Islands. It has about 20,000 people. The city is on the island of Saint Thomas.",
        },
        {
            "Title": "Washington D.C.",
            "Content": "Washington, D.C. (also known as simply Washington or D.C., and officially as the District of Columbia) is the capital of the United States. It is a federal district. The President of the USA and many major national government offices are in the territory. This makes it the political center of the United States of America.",
        },
        {
            "Title": "Capital Punishment in the US",
            "Content": "Capital punishment has existed in the United States since before the United States was a country. As of 2017, capital punishment is legal in 30 of the 50 states. The federal government (including the United States military) also uses capital punishment.",
        },
    ]        
}

response = requests.post(url, headers=headers, data=json.dumps(data))

print(response.json())

In the documents parameter, we are passing in a list YAML strings, representing the structured data.

Response

{
  "id": "26c8ad0bb95011f0a5edda799fbd82e9",
  "results": [
    {
      "index": 3, // "Washington, D.C. (also known as simply Washington or D.C., and officially as the District of Columbia) ..."
      "relevance_score": 0.9990564
    },
    {
      "index": 4, // "Capital punishment has existed in the United States since before the United States was a country. As of 2017 ..."
      "relevance_score": 0.7516481
    },
    {
      "index": 1, // "The Commonwealth of the Northern Mariana Islands is a group of islands in the Pacific Ocean that are a political division ..."
      "relevance_score": 0.08882029
    },
    {
      "index": 0, // "Carson City is the capital city of the American state of Nevada. At the 2010 United States Census, Carson City had a ..."
      "relevance_score": 0.058238626
    },
    {
      "index": 2, // ""Charlotte Amalie is the capital and largest city of the United States Virgin Islands. It has about 20,000 people ..."
      "relevance_score": 0.019946935
    }
  ]
}


Advanced features

OneRouter standardizes and aggregates API formats across multiple providers to deliver a consistent developer experience.This enables users to seamlessly interact with diverse model endpoints through a unified interface, eliminating the need for provider-specific code adjustments.

Please be aware that certain provider-specific Rerank APIs may include advanced features or custom parameters that extend beyond the unified specification. These additional capabilities are not always fully represented within the OneRouter unified API definition. For detailed information about such advanced parameters, behaviors, or usage examples, please refer to the original official documentation of the respective provider.

  • Jina Rerank API: Maximize the search relevancy and RAG accuracy with our cutting-edge reranker API.

  • Voyageai Rerank API: Voyage AI provides cutting-edge embedding and rerankers.

How Does Reranker Work?

A reranker takes a query and a set of candidate documents as input, returning a reordered list based on their semantic relevancy. The documents are typically the preliminary results from an embedding-based retrieval system, and the reranker refines the ranks of these candidate documents and provides more accurate relevancy scores.

Unlike embedding models that encode queries and documents separately, rerankers are cross-encoders that jointly process a pair of query and document, enabling more accurate relevancy prediction. Thus, it is a common practice to apply a reranker on the top candidates retrieved with embedding-based search (or with lexical search algorithms such as BM25 and TF-IDF).


Get Started

Example with Texts

In the example below, we use the Rerank API endpoint to index the list of documents from most to least relevant to the query "What is the capital of the United States?".

Request

In this example, the documents being passed in are a list of strings:

import requests
import json

url = "https://llm.onerouter.pro/v1/rerank"
headers = {
    "Content-Type": "application/json",
    "Authorization": "Bearer {{API_KEY}}"
}
data = {
    "model": "voyage-rerank-2.5",
    "query": "What is the capital of the United States?",
    "top_n": 3,
    "documents": [
        "Carson City is the capital city of the American state of Nevada. At the 2010 United States Census, Carson City had a population of 55,274.",
        "The Commonwealth of the Northern Mariana Islands is a group of islands in the Pacific Ocean that are a political division controlled by the United States. Its capital is Saipan.",
        "Charlotte Amalie is the capital and largest city of the United States Virgin Islands. It has about 20,000 people. The city is on the island of Saint Thomas.",
        "Washington, D.C. (also known as simply Washington or D.C., and officially as the District of Columbia) is the capital of the United States. It is a federal district. The President of the USA and many major national government offices are in the territory. This makes it the political center of the United States of America.",
        "Capital punishment has existed in the United States since before the United States was a country. As of 2017, capital punishment is legal in 30 of the 50 states. The federal government (including the United States military) also uses capital punishment.",
    ]        
}

response = requests.post(url, headers=headers, data=json.dumps(data))

print(response.json())

Response

{
  "id": "26c8ad0bb95011f0a5edda799fbd82e9",
  "results": [
    {
      "index": 3, // "Washington, D.C. (also known as simply Washington or D.C., and officially as the District of Columbia) ..."
      "relevance_score": 0.9990564
    },
    {
      "index": 4, // "Capital punishment has existed in the United States since before the United States was a country. As of 2017 ..."
      "relevance_score": 0.7516481
    },
    {
      "index": 1, // "The Commonwealth of the Northern Mariana Islands is a group of islands in the Pacific Ocean that are a political division ..."
      "relevance_score": 0.08882029
    },
    {
      "index": 0, // "Carson City is the capital city of the American state of Nevada. At the 2010 United States Census, Carson City had a ..."
      "relevance_score": 0.058238626
    },
    {
      "index": 2, // ""Charlotte Amalie is the capital and largest city of the United States Virgin Islands. It has about 20,000 people ..."
      "relevance_score": 0.019946935
    }
  ]
}


Example with Structured Data

To achieve optimal performance with structured data, we recommend formatting your documents as YAML strings.

Request

import requests
import json

url = "https://llm.onerouter.pro/v1/rerank"
headers = {
    "Content-Type": "application/json",
    "Authorization": "Bearer {{API_KEY}}"
}
data = {
    "model": "voyage-rerank-2.5",
    "query": "What is the capital of the United States?",
    "top_n": 3,
    "documents": [
        {
            "Title": "Facts about Carson City",
            "Content": "Carson City is the capital city of the American state of Nevada. At the 2010 United States Census, Carson City had a population of 55,274.",
        },
        {
            "Title": "The Commonwealth of Northern Mariana Islands",
            "Content": "The Commonwealth of the Northern Mariana Islands is a group of islands in the Pacific Ocean that are a political division controlled by the United States. Its capital is Saipan.",
        },
        {
            "Title": "The Capital of United States Virgin Islands",
            "Content": "Charlotte Amalie is the capital and largest city of the United States Virgin Islands. It has about 20,000 people. The city is on the island of Saint Thomas.",
        },
        {
            "Title": "Washington D.C.",
            "Content": "Washington, D.C. (also known as simply Washington or D.C., and officially as the District of Columbia) is the capital of the United States. It is a federal district. The President of the USA and many major national government offices are in the territory. This makes it the political center of the United States of America.",
        },
        {
            "Title": "Capital Punishment in the US",
            "Content": "Capital punishment has existed in the United States since before the United States was a country. As of 2017, capital punishment is legal in 30 of the 50 states. The federal government (including the United States military) also uses capital punishment.",
        },
    ]        
}

response = requests.post(url, headers=headers, data=json.dumps(data))

print(response.json())

In the documents parameter, we are passing in a list YAML strings, representing the structured data.

Response

{
  "id": "26c8ad0bb95011f0a5edda799fbd82e9",
  "results": [
    {
      "index": 3, // "Washington, D.C. (also known as simply Washington or D.C., and officially as the District of Columbia) ..."
      "relevance_score": 0.9990564
    },
    {
      "index": 4, // "Capital punishment has existed in the United States since before the United States was a country. As of 2017 ..."
      "relevance_score": 0.7516481
    },
    {
      "index": 1, // "The Commonwealth of the Northern Mariana Islands is a group of islands in the Pacific Ocean that are a political division ..."
      "relevance_score": 0.08882029
    },
    {
      "index": 0, // "Carson City is the capital city of the American state of Nevada. At the 2010 United States Census, Carson City had a ..."
      "relevance_score": 0.058238626
    },
    {
      "index": 2, // ""Charlotte Amalie is the capital and largest city of the United States Virgin Islands. It has about 20,000 people ..."
      "relevance_score": 0.019946935
    }
  ]
}


Advanced features

OneRouter standardizes and aggregates API formats across multiple providers to deliver a consistent developer experience.This enables users to seamlessly interact with diverse model endpoints through a unified interface, eliminating the need for provider-specific code adjustments.

Please be aware that certain provider-specific Rerank APIs may include advanced features or custom parameters that extend beyond the unified specification. These additional capabilities are not always fully represented within the OneRouter unified API definition. For detailed information about such advanced parameters, behaviors, or usage examples, please refer to the original official documentation of the respective provider.

  • Jina Rerank API: Maximize the search relevancy and RAG accuracy with our cutting-edge reranker API.

  • Voyageai Rerank API: Voyage AI provides cutting-edge embedding and rerankers.

Scale without limits

Seamlessly integrate OneRouter with just a few lines of code and unlock unlimited AI power.

Scale without limits

Seamlessly integrate OneRouter with just a few lines of code and unlock unlimited AI power.

Scale without limits

Seamlessly integrate OneRouter with just a few lines of code and unlock unlimited AI power.