Text Reranking

This page describes the text reranking (rerank) API, using the models-model.md style: Overview, Authentication, Parameters, Request example, Response example.

---

Overview

• Method: POST
• Path: /v1/rerank
• Content-Type: application/json

Authentication

• Use HTTP Bearer Token, e.g.: Authorization: Bearer sk-xxxxx

---

Request Parameters

Parameter	Type	Required	Description
model	string	yes	The reranking model name, e.g. gte-rerank-v2
query	string	yes	The query prompt used to match and rank candidate documents
documents	array[string]	yes	List of candidate documents (array of strings) to be ranked by relevance to query
top_n	integer	no	Return the top N documents; if omitted, all candidates are returned
return_documents	boolean	no	Whether to include the original document text in the response; default false

---

Request Example

{
  "model": "gte-rerank-v2",
  "query": "What is a text reranking model",
  "documents": [
    "Text reranking models are widely used in search engines and recommender systems to order candidate texts by relevance.",
    "Quantum computing is a cutting-edge field in computer science.",
    "Advances in pretrained language models have driven new progress in text reranking."
  ],
  "return_documents": true,
  "top_n": 5
}

curl

curl -X POST "https://api.gpt.ge/v1/rerank" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-xxxx" \
  -d '{"model":"gte-rerank-v2","query":"What is a text reranking model","documents":["Text reranking models are widely used in search engines and recommender systems to order candidate texts by relevance.","Quantum computing is a cutting-edge field in computer science.","Advances in pretrained language models have driven new progress in text reranking."],"return_documents":true,"top_n":5}'

JavaScript (fetch)

fetch('https://api.gpt.ge/v1/rerank', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json', 'Authorization': 'Bearer sk-xxxx' },
  body: JSON.stringify({ model: 'gte-rerank-v2', query: 'What is a text reranking model', documents: ['Text reranking models are widely used in search engines and recommender systems to order candidate texts by relevance.','Quantum computing is a cutting-edge field in computer science.','Advances in pretrained language models have driven new progress in text reranking.'], return_documents: true, top_n: 5 })
}).then(r => r.json()).then(console.log)

Python (requests)

import requests

payload = {
  'model': 'gte-rerank-v2',
  'query': 'What is a text reranking model',
  'documents': [
    'Text reranking models are widely used in search engines and recommender systems to order candidate texts by relevance.',
    'Quantum computing is a cutting-edge field in computer science.',
    'Advances in pretrained language models have driven new progress in text reranking.'
  ],
  'return_documents': True,
  'top_n': 5
}

resp = requests.post('https://api.gpt.ge/v1/rerank', headers={'Content-Type':'application/json','Authorization':'Bearer sk-xxxx'}, json=payload)
print(resp.json())

---

Response Example (200)

{
  "results": [
    {
      "document": { "text": "Text reranking models are widely used in search engines and recommender systems to order candidate texts by relevance." },
      "index": 0,
      "relevance_score": 0.9334521178273196
    },
    {
      "document": { "text": "Advances in pretrained language models have driven new progress in text reranking." },
      "index": 2,
      "relevance_score": 0.34100082626411193
    },
    {
      "document": { "text": "Quantum computing is a cutting-edge field in computer science." },
      "index": 1,
      "relevance_score": 0.005814161578735119
    }
  ],
  "usage": { "prompt_tokens": 79, "total_tokens": 79 }
}