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": "aligned-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": "aligned-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: 'aligned-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' => 'aligned-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\": \"aligned-model-01kmqm4nrn9fw6r\",\n  \"query\": [\n    \"What is Python?\"\n  ],\n  \"documents\": [\n    [\n      \"Python is a programming language\",\n      \"Java is a language\"\n    ]\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\": \"aligned-model-01kmqm4nrn9fw6r\",\n  \"query\": [\n    \"What is Python?\"\n  ],\n  \"documents\": [\n    [\n      \"Python is a programming language\",\n      \"Java is a language\"\n    ]\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\": \"aligned-model-01kmqm4nrn9fw6r\",\n  \"query\": [\n    \"What is Python?\"\n  ],\n  \"documents\": [\n    [\n      \"Python is a programming language\",\n      \"Java is a language\"\n    ]\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: Reranker model ID (required) - e.g., aligned-model-01kmqm4nrn9fw6r
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": "aligned-model-01kmqm4nrn9fw6r",
  "query": "What is machine learning?",
  "documents": [
    "Machine learning is a subset of artificial intelligence that enables computers to learn from data.",
    "Python is a popular programming language for web development.",
    "Deep learning uses neural networks with multiple layers.",
    "The weather today is sunny and warm.",
    "Supervised learning requires labeled training data."
  ],
  "method": "fast",
  "top_n": 3
}

Example Response:

{
  "results": [
    {
      "index": 0,
      "relevance_score": 0.95,
      "document": "Machine learning is a subset of artificial intelligence that enables computers to learn from data."
    },
    {
      "index": 4,
      "relevance_score": 0.82,
      "document": "Supervised learning requires labeled training data."
    },
    {
      "index": 2,
      "relevance_score": 0.76,
      "document": "Deep learning uses neural networks with multiple layers."
    }
  ],
  "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": "aligned-model-01kmqm4nrn9fw6r",
  "query": "How do neural networks work?",
  "documents": [
    "Neural networks are computing systems inspired by biological neural networks.",
    "The stock market is volatile today.",
    "Backpropagation is used to train neural networks."
  ],
}

Example Response (Hybrid Method):

{
  "results": [
    {
      "index": 0,
      "relevance_score": 0.92,
      "document": "Neural networks are computing systems inspired by biological neural networks."
    },
    {
      "index": 2,
      "relevance_score": 0.88,
      "document": "Backpropagation is used to train neural networks."
    }
  ],
  "meta": {
    "deployed_model_id": "aligned-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": "aligned-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": "aligned-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: 'aligned-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' => 'aligned-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\": \"aligned-model-01kmqm4nrn9fw6r\",\n  \"query\": [\n    \"What is Python?\"\n  ],\n  \"documents\": [\n    [\n      \"Python is a programming language\",\n      \"Java is a language\"\n    ]\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\": \"aligned-model-01kmqm4nrn9fw6r\",\n  \"query\": [\n    \"What is Python?\"\n  ],\n  \"documents\": [\n    [\n      \"Python is a programming language\",\n      \"Java is a language\"\n    ]\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\": \"aligned-model-01kmqm4nrn9fw6r\",\n  \"query\": [\n    \"What is Python?\"\n  ],\n  \"documents\": [\n    [\n      \"Python is a programming language\",\n      \"Java is a language\"\n    ]\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

Model ID to use for reranking

Example:

"aligned-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

Alignment Project

Models

Agents

Documents

Benchmark

Evaluations

Inference

Rerank Documents

Authorizations

Body

Response