curl --request POST \
--url https://{host}/v2/workspaces/slug:llm-gateway/webhooks/v1/rerank \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"query": "<string>",
"documents": [
"<string>"
]
}
'const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({query: '<string>', documents: ['<string>']})
};
fetch('https://{host}/v2/workspaces/slug:llm-gateway/webhooks/v1/rerank', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));import requests
url = "https://{host}/v2/workspaces/slug:llm-gateway/webhooks/v1/rerank"
payload = {
"query": "<string>",
"documents": ["<string>"]
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text){
"id": "<string>",
"results": [
{
"index": 123,
"relevance_score": 123
}
],
"meta": {
"model": "<string>",
"backend": "llm-as-reranker",
"billed_units": {
"input_tokens": 123,
"output_tokens": 123
}
}
}{
"error": "<string>",
"message": "<string>",
"code": "<string>",
"details": {},
"status": 123,
"retryAfter": 123,
"provider": "<string>",
"model": "<string>",
"provider_error_type": "<string>"
}{
"error": "<string>",
"message": "<string>",
"code": "<string>",
"details": {},
"status": 123,
"retryAfter": 123,
"provider": "<string>",
"model": "<string>",
"provider_error_type": "<string>"
}{
"error": "<string>",
"message": "<string>",
"code": "<string>",
"details": {},
"status": 123,
"retryAfter": 123,
"provider": "<string>",
"model": "<string>",
"provider_error_type": "<string>"
}{
"error": "<string>",
"message": "<string>",
"code": "<string>",
"details": {},
"status": 123,
"retryAfter": 123,
"provider": "<string>",
"model": "<string>",
"provider_error_type": "<string>"
}{
"error": "<string>",
"message": "<string>",
"code": "<string>",
"details": {},
"status": 123,
"retryAfter": 123,
"provider": "<string>",
"model": "<string>",
"provider_error_type": "<string>"
}Rerank documents by relevance
Reranks a set of candidate documents by their relevance to a query,
following the de-facto standard rerank contract (compatible with
Cohere v2 / Jina / Voyage): a request of { model, query, documents }
returns { results: [{ index, relevance_score }] } sorted by
relevance_score descending, where index is the position of the
document in the input documents array.
Backend. LLM-as-reranker: relevance is scored via chat completions
(deterministic, temperature: 0, JSON output), then sorted server-side
so the ordering never relies on the model’s own output order. The
request/response contract deliberately matches native rerankers, so the
backend can later be swapped to a native cross-encoder without changing
callers. Use model: "mock" for a deterministic, LLM-free response in
CI / load tests.
Limits. All documents are scored in a single prompt (no batching);
documents is capped at 200 items and max_tokens_per_doc is advisory.
Suited to a post-retrieval rerank window rather than large corpora.
Rate limiting. 100 requests per 60 seconds per consumer
(auth.user_id or session.id).
Governance. Reuses the chat-completions permission and the
organization governance overlay, so calls may be rejected with
403 MODEL_NOT_ALLOWED or 429 quota errors.
curl --request POST \
--url https://{host}/v2/workspaces/slug:llm-gateway/webhooks/v1/rerank \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"query": "<string>",
"documents": [
"<string>"
]
}
'const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({query: '<string>', documents: ['<string>']})
};
fetch('https://{host}/v2/workspaces/slug:llm-gateway/webhooks/v1/rerank', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));import requests
url = "https://{host}/v2/workspaces/slug:llm-gateway/webhooks/v1/rerank"
payload = {
"query": "<string>",
"documents": ["<string>"]
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text){
"id": "<string>",
"results": [
{
"index": 123,
"relevance_score": 123
}
],
"meta": {
"model": "<string>",
"backend": "llm-as-reranker",
"billed_units": {
"input_tokens": 123,
"output_tokens": 123
}
}
}{
"error": "<string>",
"message": "<string>",
"code": "<string>",
"details": {},
"status": 123,
"retryAfter": 123,
"provider": "<string>",
"model": "<string>",
"provider_error_type": "<string>"
}{
"error": "<string>",
"message": "<string>",
"code": "<string>",
"details": {},
"status": 123,
"retryAfter": 123,
"provider": "<string>",
"model": "<string>",
"provider_error_type": "<string>"
}{
"error": "<string>",
"message": "<string>",
"code": "<string>",
"details": {},
"status": 123,
"retryAfter": 123,
"provider": "<string>",
"model": "<string>",
"provider_error_type": "<string>"
}{
"error": "<string>",
"message": "<string>",
"code": "<string>",
"details": {},
"status": 123,
"retryAfter": 123,
"provider": "<string>",
"model": "<string>",
"provider_error_type": "<string>"
}{
"error": "<string>",
"message": "<string>",
"code": "<string>",
"details": {},
"status": 123,
"retryAfter": 123,
"provider": "<string>",
"model": "<string>",
"provider_error_type": "<string>"
}Authorizations
User-bound credential carrying an identity: either a session JWT
or a user access token (at:*) generated from the user settings UI.
Send as Authorization: Bearer <token>.
Org API keys (iak_*) are not accepted here - they carry
no user identity. Use the x-prismeai-api-key header instead
(see OrgApiKeyAuth).
Body
The search query to rank the documents against.
8192Candidate passages to rerank.
2008192Reranker model id. Defaults to the gateway's configured completions
default. Use "mock" for a deterministic, LLM-free response.
256Limit the number of returned results. Defaults to all documents; a value of 0 or less is ignored (returns all).
Accepted for contract compatibility with native rerankers. Currently advisory (not enforced).
Prisme.ai extension. Caller-supplied analytics context.
Response
Successful rerank response (results sorted by relevance_score descending).
Unique identifier for this rerank request.
Was this page helpful?