POST /v1/rerank reorders candidate documents by relevance to a query. A common RAG pipeline retrieves a broad set with vector search, then uses a reranker to select the most relevant context.
Request
curl https://api.nbility.ai/v1/rerank \
-H "Authorization: Bearer $NBILITY_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "YOUR_RERANK_MODEL",
"query": "How should an API key be protected?",
"documents": [
"Commit the key to a Git repository.",
"Read the key from a server-side environment variable and rotate it regularly.",
"Embed a long-lived key in browser code."
],
"top_n": 2,
"return_documents": true
}'
Fields
| Field | Type | Required | Description |
|---|---|---|---|
model | string | yes | Reranking model ID |
query | string | yes | Query used to judge relevance |
documents | array | yes | Candidate strings or document objects supported by the selected model |
top_n | integer | no | Return only the highest-scoring N results |
return_documents | boolean | no | Include document content in results |
max_chunk_per_doc | integer | no | Maximum chunks per document, supported by some channels only |
overlap_tokens | integer | no | Token overlap between chunks, supported by some channels only |
A typical response:
{
"results": [
{
"index": 1,
"relevance_score": 0.98,
"document": {"text": "Read the key from a server-side environment variable and rotate it regularly."}
}
],
"usage": {"total_tokens": 42}
}
index points back to the original documents array. Scores from different models are not directly comparable, and a score should not automatically be treated as a probability. Tune top_n or a threshold on your own evaluation set.
RAG guidance
- Keep enough candidates during vector retrieval, then rerank down to what fits in the model context.
- Split long documents semantically and retain document and chunk IDs in application metadata.
- Bound batch size, text length, and spend so a single request cannot grow without control.