curl https://kymaapi.com/v1/rerank \
-H "Authorization: Bearer kyma-your-api-key" \
-H "Content-Type: application/json" \
-d '{
"model": "qwen3-reranker-8b",
"query": "How do I rotate an API key?",
"documents": [
"Create a new key, update your clients, then revoke the old one.",
"Our office is closed on public holidays.",
"Keys can be revoked from the dashboard at any time."
]
}'
Endpoints
Rerank documents
Score a list of documents against a query, so only the best few reach your model.
POST
/
v1
/
rerank
curl https://kymaapi.com/v1/rerank \
-H "Authorization: Bearer kyma-your-api-key" \
-H "Content-Type: application/json" \
-d '{
"model": "qwen3-reranker-8b",
"query": "How do I rotate an API key?",
"documents": [
"Create a new key, update your clients, then revoke the old one.",
"Our office is closed on public holidays.",
"Keys can be revoked from the dashboard at any time."
]
}'
Reranking sits between retrieval and generation: embeddings decide what to fetch, a reranker decides which of those results are worth sending to a chat model. The reranking models are listed at
Other fields in the body are forwarded to the model as sent.
GET /v1/models?type=reranking, with prices.
Request body
string
required
A reranking model id, for example
qwen3-reranker-8b. A model of any other type returns 400 pointing to GET /v1/models?type=reranking.string
required
The text to rank the documents against. Must not be empty.
array
required
A non-empty array of strings to rank.
Response
The body is the model’s ranking of your documents, returned as the model produced it with two changes:model is the Kyma id you called, and usage.cost is added. usage.prompt_tokens covers the query and every document.
Responses are not streamed.
Billing
Input tokens only, at the model’s input rate: the query plus every document. Sending a hundred documents costs a hundred documents.usage.cost is the price of the call in USD, to 8 decimal places.
Response headers
| Header | When |
|---|---|
X-Kyma-Model | Always. The model id your request resolved to |
X-Kyma-Alias | When you sent an alias; names it |
Errors
The body is{"error": {"message": "...", "type": "..."}}.
| Code | type | Means | What to do |
|---|---|---|---|
400 | invalid_request | Invalid JSON, query or documents missing or not strings, or a model that is not a reranker | Fix the request |
other 4xx | invalid_request | The model rejected the request; the status is the one it returned (a 401, 402 or 403 from the model is a problem on our side and comes back as 503) | Check query and documents |
401 | auth_required / invalid_credentials | Key missing, or unknown or revoked | Check the Authorization header |
404 | model_not_found | Kyma does not serve that id | Fix the model id |
405 | invalid_request | Method other than POST | Use POST |
413 | invalid_request | Body over 25 MB | Split the batch |
502 | server_error | The answer could not be read | Retry |
503 | server_error | Reranking is unavailable on our side right now | Retry shortly |
curl https://kymaapi.com/v1/rerank \
-H "Authorization: Bearer kyma-your-api-key" \
-H "Content-Type: application/json" \
-d '{
"model": "qwen3-reranker-8b",
"query": "How do I rotate an API key?",
"documents": [
"Create a new key, update your clients, then revoke the old one.",
"Our office is closed on public holidays.",
"Keys can be revoked from the dashboard at any time."
]
}'