Rerank API

Rerank documents by relevance to a query. Used for semantic search result ordering.

Base URL

https://api.getkawai.com/v1

Authentication

When authentication is enabled, include your token in the Authorization header:

Authorization: Bearer API_KEY

Reranking

Score and reorder documents by relevance to a query.

POST /rerank

Rerank documents by their relevance to a query. The model must support reranking.

Authentication: Required when auth is enabled. Token must have 'rerank' endpoint access.

Headers

Header	Required	Description
Authorization	Yes	Bearer token for authentication
Content-Type	Yes	Must be application/json

Request Body

Content-Type: application/json

Field	Type	Required	Description
model	string	Yes	Reranker model ID (e.g., 'bge-reranker-v2-m3-Q8_0')
query	string	Yes	The query to rank documents against.
documents	array	Yes	Array of document strings to rank.
top_n	integer	No	Return only the top N results. Defaults to all documents.
return_documents	boolean	No	Include document text in results. Defaults to false.

Response

Returns a list of reranked results with index and relevance_score, sorted by score descending.

Content-Type: application/json

Examples

Rerank documents for a query:

curl -X POST https://api.getkawai.com/v1/rerank \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "bge-reranker-v2-m3-Q8_0",
    "query": "What is machine learning?",
    "documents": [
      "Machine learning is a subset of artificial intelligence.",
      "The weather today is sunny.",
      "Deep learning uses neural networks."
    ],
    "top_n": 2
  }'

---