Skip to main content

Documentation Index

Fetch the complete documentation index at: https://doc.hitopen.com/llms.txt

Use this file to discover all available pages before exploring further.

The rerank endpoint takes a search query and a list of candidate documents and returns them sorted by relevance. Use it as a second-pass ranker after an initial retrieval step (such as a vector search) to improve the quality of your results in RAG pipelines and search applications.

​
Endpoint

POST https://YOUR_NEWAPI_BASE_URL/v1/rerank

​
Request parameters

​
model
string
required
The reranking model to use. Common values include rerank-english-v2.0, rerank-multilingual-v2.0, and bge-reranker-v2-m3. Check with your admin for available models.
​
query
string
required
The search query. Documents are ranked by their relevance to this query.
​
documents
string[] | object[]
required
The list of candidate documents to rank. You can pass plain strings or objects with a text field. The order does not matter — the response returns items sorted by relevance score.
​
top_n
integer
If specified, only the top n most relevant documents are returned. If omitted, all documents are returned with their scores.
​
return_documents
boolean
default:"false"
When true, the original document content is included in the response alongside the scores. When false, only the original index and score are returned.

​
Response fields

​
id
string
Unique identifier for the rerank request.
​
results
object[]
Documents sorted in descending order of relevance. The most relevant document is at index 0.
​
meta
object
Additional metadata about the request, such as billed units.

​
Examples

curl -X POST "https://YOUR_NEWAPI_BASE_URL/v1/rerank" \
  -H "Authorization: Bearer sk-your-token" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "rerank-english-v2.0",
    "query": "How do I reset my password?",
    "documents": [
      "To change your username, go to account settings.",
      "You can reset your password by clicking Forgot Password on the login page.",
      "Our refund policy allows returns within 30 days.",
      "To recover your account, use the password reset email sent to your inbox."
    ],
    "top_n": 2,
    "return_documents": true
  }'

​
Example response

{
  "id": "rerank-abc123",
  "results": [
    {
      "index": 1,
      "relevance_score": 0.9823,
      "document": {
        "text": "You can reset your password by clicking Forgot Password on the login page."
      }
    },
    {
      "index": 3,
      "relevance_score": 0.8741,
      "document": {
        "text": "To recover your account, use the password reset email sent to your inbox."
      }
    }
  ],
  "meta": {}
}
For best results in a RAG pipeline, retrieve a broad candidate set first (for example 50–100 documents via vector search), then pass them to the rerank endpoint and take the top 3–5 results to send to the language model.