Rerank Documents

curl --request POST \
  --url https://api.nugen.in/api/v3/inference/reranker \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "model": "model_01kmqm4nrn9fw6r",
  "query": "What is Python?",
  "documents": [
    "Python is a programming language",
    "Java is a language"
  ],
  "method": "fast",
  "model_cross": "<string>",
  "top_n": 2,
  "stage1_top_k": 100,
  "max_tokens_per_doc": 512,
  "batch_size": 2,
  "return_documents": false
}
'

import requests

url = "https://api.nugen.in/api/v3/inference/reranker"

payload = {
    "model": "model_01kmqm4nrn9fw6r",
    "query": "What is Python?",
    "documents": ["Python is a programming language", "Java is a language"],
    "method": "fast",
    "model_cross": "<string>",
    "top_n": 2,
    "stage1_top_k": 100,
    "max_tokens_per_doc": 512,
    "batch_size": 2,
    "return_documents": False
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    model: 'model_01kmqm4nrn9fw6r',
    query: 'What is Python?',
    documents: ['Python is a programming language', 'Java is a language'],
    method: 'fast',
    model_cross: '<string>',
    top_n: 2,
    stage1_top_k: 100,
    max_tokens_per_doc: 512,
    batch_size: 2,
    return_documents: false
  })
};

fetch('https://api.nugen.in/api/v3/inference/reranker', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.nugen.in/api/v3/inference/reranker",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'model' => 'model_01kmqm4nrn9fw6r',
    'query' => 'What is Python?',
    'documents' => [
        'Python is a programming language',
        'Java is a language'
    ],
    'method' => 'fast',
    'model_cross' => '<string>',
    'top_n' => 2,
    'stage1_top_k' => 100,
    'max_tokens_per_doc' => 512,
    'batch_size' => 2,
    'return_documents' => false
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.nugen.in/api/v3/inference/reranker"

	payload := strings.NewReader("{\n  \"model\": \"model_01kmqm4nrn9fw6r\",\n  \"query\": \"What is Python?\",\n  \"documents\": [\n    \"Python is a programming language\",\n    \"Java is a language\"\n  ],\n  \"method\": \"fast\",\n  \"model_cross\": \"<string>\",\n  \"top_n\": 2,\n  \"stage1_top_k\": 100,\n  \"max_tokens_per_doc\": 512,\n  \"batch_size\": 2,\n  \"return_documents\": false\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.nugen.in/api/v3/inference/reranker")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"model\": \"model_01kmqm4nrn9fw6r\",\n  \"query\": \"What is Python?\",\n  \"documents\": [\n    \"Python is a programming language\",\n    \"Java is a language\"\n  ],\n  \"method\": \"fast\",\n  \"model_cross\": \"<string>\",\n  \"top_n\": 2,\n  \"stage1_top_k\": 100,\n  \"max_tokens_per_doc\": 512,\n  \"batch_size\": 2,\n  \"return_documents\": false\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.nugen.in/api/v3/inference/reranker")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"model\": \"model_01kmqm4nrn9fw6r\",\n  \"query\": \"What is Python?\",\n  \"documents\": [\n    \"Python is a programming language\",\n    \"Java is a language\"\n  ],\n  \"method\": \"fast\",\n  \"model_cross\": \"<string>\",\n  \"top_n\": 2,\n  \"stage1_top_k\": 100,\n  \"max_tokens_per_doc\": 512,\n  \"batch_size\": 2,\n  \"return_documents\": false\n}"

response = http.request(request)
puts response.read_body

{
  "results": [
    {
      "index": 123,
      "relevance_score": 123,
      "document": "<string>"
    }
  ],
  "meta": {
    "method": "<string>",
    "deployed_model_id": "<string>",
    "model_cross": "<string>",
    "stage1_top_k": 123
  }
}

{
  "detail": [
    {
      "loc": [
        "<string>"
      ],
      "msg": "<string>",
      "type": "<string>"
    }
  ]
}

Inference

Rerank Documents

Rerank documents based on semantic relevance to a query.

This endpoint computes semantic relevance scores for a list of documents against a query, returning them in descending order of relevance. Supports multiple reranking methods from fast bi-encoders to advanced hybrid approaches. Ideal for improving search results and retrieval-augmented generation (RAG) pipelines.

Request Body:

model: Model ID (required). Use your aligned model id (e.g. model_01kmqm4nrn9fw6r); the same aligned id serves chat completions, completions and embeddings too
query: Search query or question text (required)
documents: Array of document texts or objects to rerank (required) - Can be strings or dictionaries

Returns:

results: Array of reranked documents with relevance scores, each containing:
- index: Original position in input array
- relevance_score: Computed relevance score (higher = more relevant)
- document (optional): Document text or object (if requested)
meta: Operation metadata containing:
- method: Reranking method used
- deployed_model_id: Model ID that was used
- model_cross (optional): Cross-encoder model used (if applicable)
- stage1_top_k (optional): Stage 1 top-k for hybrid methods

Example Request (Fast Method):

POST /api/v3/inference/reranker
Headers: {"Authorization": "Bearer <api_key>"}

{
  "model": "model_01kmqm4nrn9fw6r",
  "query": "How do I rotate API keys?",
  "documents": [
    "Rotate keys from the admin console; the old key stays valid.",
    "Python is a popular programming language for web development.",
    "Expired keys are purged after a ninety day grace.",
    "The canteen menu changes on Mondays.",
    "Key rotation requires the security admin role."
  ],
  "method": "fast",
  "top_n": 3
}

Example Response:

{
  "results": [
    {
      "index": 0,
      "relevance_score": 0.95,
      "document": "Rotate keys from the admin console; the old key stays valid."
    },
    {
      "index": 4,
      "relevance_score": 0.82,
      "document": "Key rotation requires the security admin role."
    },
    {
      "index": 2,
      "relevance_score": 0.76,
      "document": "Expired keys are purged after a ninety day grace."
    }
  ],
  "meta": {
    "method": "fast",
    "deployed_model_id": "bge-reranker-v2-m3"
  }
}

Example Request (Hybrid Method):

POST /api/v3/inference/reranker
Headers: {"Authorization": "Bearer <api_key>"}

{
  "model": "model_01kmqm4nrn9fw6r",
  "query": "How is regional failover tested?",
  "documents": [
    "Failover drills run each quarter against the standby region.",
    "The stock market is volatile today.",
    "Rollback restores the previous release build."
  ],
}

Example Response (Hybrid Method):

{
  "results": [
    {
      "index": 0,
      "relevance_score": 0.92,
      "document": "Failover drills run each quarter against the standby region."
    },
    {
      "index": 2,
      "relevance_score": 0.88,
      "document": "Rollback restores the previous release build."
    }
  ],
  "meta": {
    "deployed_model_id": "model_01kmqm4nrn9fw6r",
  }
}

Use Cases:

Search Enhancement: Improve search result ranking by semantic relevance
RAG Pipelines: Select most relevant context chunks for LLM prompts
Semantic Filtering: Find documents most related to a specific topic
Question Answering: Rank candidate answers by relevance to the question

Notes:

Documents can be plain strings or structured objects (dictionaries)
Documents are returned in descending order of relevance (most relevant first)
Results are always sorted by relevance_score in descending order (highest first)
Relevance scores typically range from 0.0 to 1.0

POST

api

inference

reranker

Rerank Documents

curl --request POST \
  --url https://api.nugen.in/api/v3/inference/reranker \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "model": "model_01kmqm4nrn9fw6r",
  "query": "What is Python?",
  "documents": [
    "Python is a programming language",
    "Java is a language"
  ],
  "method": "fast",
  "model_cross": "<string>",
  "top_n": 2,
  "stage1_top_k": 100,
  "max_tokens_per_doc": 512,
  "batch_size": 2,
  "return_documents": false
}
'

import requests

url = "https://api.nugen.in/api/v3/inference/reranker"

payload = {
    "model": "model_01kmqm4nrn9fw6r",
    "query": "What is Python?",
    "documents": ["Python is a programming language", "Java is a language"],
    "method": "fast",
    "model_cross": "<string>",
    "top_n": 2,
    "stage1_top_k": 100,
    "max_tokens_per_doc": 512,
    "batch_size": 2,
    "return_documents": False
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    model: 'model_01kmqm4nrn9fw6r',
    query: 'What is Python?',
    documents: ['Python is a programming language', 'Java is a language'],
    method: 'fast',
    model_cross: '<string>',
    top_n: 2,
    stage1_top_k: 100,
    max_tokens_per_doc: 512,
    batch_size: 2,
    return_documents: false
  })
};

fetch('https://api.nugen.in/api/v3/inference/reranker', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.nugen.in/api/v3/inference/reranker",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'model' => 'model_01kmqm4nrn9fw6r',
    'query' => 'What is Python?',
    'documents' => [
        'Python is a programming language',
        'Java is a language'
    ],
    'method' => 'fast',
    'model_cross' => '<string>',
    'top_n' => 2,
    'stage1_top_k' => 100,
    'max_tokens_per_doc' => 512,
    'batch_size' => 2,
    'return_documents' => false
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.nugen.in/api/v3/inference/reranker"

	payload := strings.NewReader("{\n  \"model\": \"model_01kmqm4nrn9fw6r\",\n  \"query\": \"What is Python?\",\n  \"documents\": [\n    \"Python is a programming language\",\n    \"Java is a language\"\n  ],\n  \"method\": \"fast\",\n  \"model_cross\": \"<string>\",\n  \"top_n\": 2,\n  \"stage1_top_k\": 100,\n  \"max_tokens_per_doc\": 512,\n  \"batch_size\": 2,\n  \"return_documents\": false\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.nugen.in/api/v3/inference/reranker")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"model\": \"model_01kmqm4nrn9fw6r\",\n  \"query\": \"What is Python?\",\n  \"documents\": [\n    \"Python is a programming language\",\n    \"Java is a language\"\n  ],\n  \"method\": \"fast\",\n  \"model_cross\": \"<string>\",\n  \"top_n\": 2,\n  \"stage1_top_k\": 100,\n  \"max_tokens_per_doc\": 512,\n  \"batch_size\": 2,\n  \"return_documents\": false\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.nugen.in/api/v3/inference/reranker")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"model\": \"model_01kmqm4nrn9fw6r\",\n  \"query\": \"What is Python?\",\n  \"documents\": [\n    \"Python is a programming language\",\n    \"Java is a language\"\n  ],\n  \"method\": \"fast\",\n  \"model_cross\": \"<string>\",\n  \"top_n\": 2,\n  \"stage1_top_k\": 100,\n  \"max_tokens_per_doc\": 512,\n  \"batch_size\": 2,\n  \"return_documents\": false\n}"

response = http.request(request)
puts response.read_body

{
  "results": [
    {
      "index": 123,
      "relevance_score": 123,
      "document": "<string>"
    }
  ],
  "meta": {
    "method": "<string>",
    "deployed_model_id": "<string>",
    "model_cross": "<string>",
    "stage1_top_k": 123
  }
}

{
  "detail": [
    {
      "loc": [
        "<string>"
      ],
      "msg": "<string>",
      "type": "<string>"
    }
  ]
}

Authorizations

Authorization

string

header

required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Body

application/json

model

string

required

Use your aligned model id (e.g. model_01kmqm4nrn9fw6r). The same aligned id serves chat completions, completions, embeddings and reranking.

Example:

"model_01kmqm4nrn9fw6r"

query

string

required

Search query

Example:

"What is Python?"

documents

(string | object)[]

required

Documents to rank

Example:

[
  "Python is a programming language",
  "Java is a language"
]

method

enum<string>

default:fast

Rerank method: fast (bi-encoder), standard (cross-encoder), optimal (hybrid bi+cross), best (subspace+attention)

Available options:

fast,

standard,

optimal,

best

model_cross

string | null

Cross-encoder model (required for standard/optimal methods)

top_n

integer | null

Return top N results

Required range: x >= 1

stage1_top_k

integer

default:100

Stage 1 top-k for hybrid methods (optimal/best)

Required range: x >= 1

max_tokens_per_doc

integer

default:512

Max tokens per document

Required range: x >= 1

batch_size

integer | null

Batch size for processing

Required range: x >= 1

return_documents

boolean

default:false

Include documents in response

Response

Return the re-ranked chunks based on similarity

results

RerankResult · object[]

required

Ranked results

Show child attributes

General

Models

Documents

Benchmarks

Evaluations

Inference

BYOC

Rerank Documents

Authorizations

Body

Response