Skip to content

Order results by relevance

Score candidate documents against a query with a cross-encoder and get them back ranked.

How it works

  1. 01

    Find candidate documents with your existing search or vector query.

  2. 02

    Send the query and the documents to POST /api/v1/rerank.

  3. 03

    Set top_n to keep only the best matches.

Authentication

Send your key as Authorization: Bearer. Reranking needs rerank:write. Cohere clients can call the same endpoint at /api/v2/rerank.

Example

A cross-encoder reads the query against every document, so it ranks more accurately than vector similarity alone. The price grows with the number of candidates, so search broadly and rerank a shortlist.

cURL
curl -X POST "https://my.neuronai.uz/api/v1/rerank" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <your-api-key>" \
  -d '{
    "model": "bge-reranker-v2-m3",
    "query": "ob-havo",
    "documents": ["Bugun havo issiq.", "Docker qollanmasi."],
    "top_n": 5
  }'

API reference

Request fields, responses, prices and code samples for every endpoint, with a form that sends a real request.

Stored locally in your browser only.

Rerank

Cross-encoder reranking for retrieval pipelines. Cohere-compatible — available at both /v1/rerank and /v2/rerank.

POST
/v1/rerank

Bearer

Rerank documents

Scores each document against the query with a cross-encoder and returns them ordered by relevance. Cohere-compatible; the same handler serves `/api/v1/rerank` and `/api/v2/rerank`. Billed per token across the query and all documents.

Pricing
per 1K tokens
Input
0.1 credits
Request body
application/json
FieldDescription
modelRequiredstring

maxLen: 128

queryRequiredstring
top_ninteger | null

min: 1

return_documentsboolean | null
documentsRequiredstring[]
Responses
200
The documents ranked by `relevance_score`, highest first. `index` is a document's position in `documents`, from 0, and `document.text` repeats its text unless `return_documents` is `false`. `id` is this request's ID, the same as `X-Request-Id`. `meta.billed_units` (Cohere's shape) and `usage` (OpenAI's) count the same input tokens, which are what is billed.
application/json
HeaderDescription
X-CostnumberThe price billed, in credits.
X-Request-IdstringIdentifies this request. A JSON body carries it as `request_id` too; quote it to support.
X-RateLimit-LimitintegerThe requests a minute the rate limit on this endpoint allows. Sent once the limit has counted the request, so not when the key itself is refused.
X-RateLimit-RemainingintegerHow many of them are left this minute.
FieldDescription
idRequiredstring
modelRequiredstring
resultsRequiredobject[]
metaRequiredobject
usageRequiredobject
401
The API key is missing or not recognized (`invalid_api_key`), revoked (`api_key_revoked`), disabled (`api_key_disabled`) or expired (`api_key_expired`).
application/json
HeaderX-Request-Id: string
FieldDescription
errorRequiredobject
request_idRequiredstring

The same ID as the `X-Request-Id` header.

format: uuid

402
Not enough balance for the estimated cost (`insufficient_balance`), or that cost would pass this key's monthly spend limit (`spend_limit_exceeded`). Nothing is charged.
application/json
HeaderDescription
X-Request-IdstringIdentifies this request. A JSON body carries it as `request_id` too; quote it to support.
X-RateLimit-LimitintegerThe requests a minute the rate limit on this endpoint allows. Sent once the limit has counted the request, so not when the key itself is refused.
X-RateLimit-RemainingintegerHow many of them are left this minute.
FieldDescription
errorRequiredobject
request_idRequiredstring

The same ID as the `X-Request-Id` header.

format: uuid

403
The key lacks the permission this endpoint needs (`insufficient_permissions`), or the client IP is not in its allowlist (`ip_not_allowed`).
application/json
HeaderDescription
X-Request-IdstringIdentifies this request. A JSON body carries it as `request_id` too; quote it to support.
X-RateLimit-LimitintegerThe requests a minute the rate limit on this endpoint allows. Sent once the limit has counted the request, so not when the key itself is refused.
X-RateLimit-RemainingintegerHow many of them are left this minute.
FieldDescription
errorRequiredobject
request_idRequiredstring

The same ID as the `X-Request-Id` header.

format: uuid

404
`model` is not a rerank model this API serves: `model_not_found`.
application/json
HeaderDescription
X-Request-IdstringIdentifies this request. A JSON body carries it as `request_id` too; quote it to support.
X-RateLimit-LimitintegerThe requests a minute the rate limit on this endpoint allows. Sent once the limit has counted the request, so not when the key itself is refused.
X-RateLimit-RemainingintegerHow many of them are left this minute.
FieldDescription
errorRequiredobject
request_idRequiredstring

The same ID as the `X-Request-Id` header.

format: uuid

422
The request failed validation (`invalid_request`: `error.param` names the first invalid field and `error.fields` maps each one to its message), there are more documents than allowed (`too_many_documents`), the query and one document together are over the tokens the model takes (`input_too_large`), or the model refused the input (`upstream_rejected_input`), which fails again unchanged. Nothing is charged.
application/json
HeaderDescription
X-Request-IdstringIdentifies this request. A JSON body carries it as `request_id` too; quote it to support.
X-RateLimit-LimitintegerThe requests a minute the rate limit on this endpoint allows. Sent once the limit has counted the request, so not when the key itself is refused.
X-RateLimit-RemainingintegerHow many of them are left this minute.
FieldDescription
errorRequiredobject
request_idRequiredstring

The same ID as the `X-Request-Id` header.

format: uuid

429
The rerank model is at capacity: `upstream_rate_limited`. Nothing is charged. Too many requests: the per-minute rate limit is used up (`rate_limit_exceeded`), or this key or its organization already has as many requests in flight as it may (`concurrency_limit_exceeded`). Wait `Retry-After` seconds, then retry.
application/json
HeaderDescription
X-Request-IdstringIdentifies this request. A JSON body carries it as `request_id` too; quote it to support.
Retry-AfterintegerSeconds to wait before retrying.
X-RateLimit-LimitintegerThe requests a minute the rate limit on this endpoint allows. Sent once the limit has counted the request, so not when the key itself is refused.
X-RateLimit-RemainingintegerHow many of them are left this minute.
X-RateLimit-ResetintegerWhen the rate limit lets requests through again, as a Unix time in seconds. Sent with a 429 for `rate_limit_exceeded`.
FieldDescription
errorRequiredobject
request_idRequiredstring

The same ID as the `X-Request-Id` header.

format: uuid

502
The rerank model failed or could not be reached: `upstream_error`. Nothing is charged.
application/json
HeaderDescription
X-Request-IdstringIdentifies this request. A JSON body carries it as `request_id` too; quote it to support.
X-RateLimit-LimitintegerThe requests a minute the rate limit on this endpoint allows. Sent once the limit has counted the request, so not when the key itself is refused.
X-RateLimit-RemainingintegerHow many of them are left this minute.
FieldDescription
errorRequiredobject
request_idRequiredstring

The same ID as the `X-Request-Id` header.

format: uuid

default
Any other error, in the same envelope. For example `server_error` (500) when something fails unexpectedly, `service_unavailable` (503) while the API is down for maintenance, or `input_too_large` (413) when the request body is larger than the server accepts.
application/json
HeaderDescription
X-Request-IdstringIdentifies this request. A JSON body carries it as `request_id` too; quote it to support.
Retry-AfterintegerSeconds to wait before retrying. Sent with a 503 during maintenance, when a retry time was set.
X-RateLimit-LimitintegerThe requests a minute the rate limit on this endpoint allows. Sent once the limit has counted the request, so not when the key itself is refused.
X-RateLimit-RemainingintegerHow many of them are left this minute.
FieldDescription
errorRequiredobject
request_idRequiredstring

The same ID as the `X-Request-Id` header.

format: uuid

Examples
cURL
curl -X POST "https://my.neuronai.uz/api/v1/rerank" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <your-api-key>" \
  -d '{
    "model": "bge-reranker-v2-m3",
    "query": "ob-havo",
    "documents": ["Bugun havo issiq.", "Docker qollanmasi."],
    "top_n": 5
  }'

Try it

Set your API key in the bar above to send authenticated requests.

application/json