Rerank documents
Provide a query and 1–1000 documents.
On this page
https://api.shareai.now/api/v1/rerankRerank documents
- Base URL
https://api.shareai.now- Authentication
- Bearer API key or approved OAuth access token
- Required scope
inferenceormonetization_gateway
Provide a query and 1–1000 documents. Each document is text, a {"text":"..."} object or a model-supported {"image":"https://..."} object. top_n must be at least 1 and no greater than the document count. Match results to the original document indices.
Before you start#
Set SHAREAI_API_KEY on your server and replace the model placeholder with a currently enabled model. Never expose the API key in browser code. The model, account, credential and provider must all permit this operation. Optional settings below require model support; the API safety bounds are not a promise that every model supports every value.
Send a request#
cURL
curl --fail-with-body --request POST "https://api.shareai.now/api/v1/rerank" \
-H "Authorization: Bearer $SHAREAI_API_KEY" \
-H "Content-Type: application/json" \
--data '{
"model": "YOUR_ENABLED_RERANK_MODEL",
"query": "A cat",
"documents": [
{
"text": "A cat on a windowsill."
},
{
"text": "A map of Berlin."
}
],
"top_n": 1
}'Python
import json
import os
import urllib.request
payload = {'model': 'YOUR_ENABLED_RERANK_MODEL',
'query': 'A cat',
'documents': [{'text': 'A cat on a windowsill.'},
{'text': 'A map of Berlin.'}],
'top_n': 1}
headers = {'Content-Type': 'application/json'}
headers["Authorization"] = "Bearer " + os.environ["SHAREAI_API_KEY"]
request = urllib.request.Request('https://api.shareai.now/api/v1/rerank', data=json.dumps(payload).encode(), headers=headers, method="POST")
with urllib.request.urlopen(request, timeout=180) as response:
result = json.load(response)
print(result)TypeScript
const response = await fetch("https://api.shareai.now/api/v1/rerank", {
method: "POST",
headers: { Authorization: `Bearer ${process.env.SHAREAI_API_KEY}`, ...{"Content-Type": "application/json"} },
body: JSON.stringify({
"model": "YOUR_ENABLED_RERANK_MODEL",
"query": "A cat",
"documents": [
{
"text": "A cat on a windowsill."
},
{
"text": "A map of Berlin."
}
],
"top_n": 1
}),
});
if (!response.ok) throw new Error(await response.text());
const result = await response.json();
console.log(result);Request fields#
| Field | Type | Meaning and limits |
|---|---|---|
model required | string | Exact enabled public model identifier. Must declare this operation and be allowed by your credential. |
query required | string | Nonempty relevance query. |
documents required | array | 1–1000 nonempty text strings or single-key text/image objects. Image values must be HTTPS URLs or supported image data URLs, with model image-input support. |
top_n | integer | Optional result count from 1 to the number of documents. Returned indices refer to the original document array. |
return_documents | boolean | Optional provider-supported inclusion of original documents in the result. |
provider | object | Optional provider routing preferences. Use provider.only for accepted provider tags, not a prefix in the model ID. Account and credential restrictions still apply. |
Read the result#
Success returns HTTP 200 with JSON. Provide a query and 1–1000 documents. Each document is text, a {"text":"..."} object or a model-supported {"image":"https://..."} object. top_n must be at least 1 and no greater than the document count. Match results to the original document indices.
Billing units#
Rerank rates can use input tokens, scored documents, requests or a provider-reported search quantity. No universal search-to-token conversion is assumed. A provider that cannot report a priced dimension is unavailable for that tariff.
Choose the exact enabled model identifier from Console. Its declared operation and input/output capabilities must match this endpoint; a text chat model cannot be substituted for another operation. Your credential, provider and account restrictions still apply.
Pricing and usage#
Rates are published in EUR AI credits for the selected model, provider, units and variants. Only the dimensions in its active tariff are charged. An estimate reserves credits before execution; final charges use measured usage. Prices can depend on resolution, output format or a usage band. Check Console Usage for the final ShareAI debit. Upstream cost fields and media bytes are not converted into invented token counts.
Access and errors#
Use inference for approved network-cost inference or monetization_gateway for an approved Builder markup and accepted billing terms. Identity-only access does not authorize spending. Validation, model authorization, insufficient credits, rate limits and execution failures return a structured error. After a timeout or uncertain submission, inspect Usage or the video job before creating another potentially paid request.
Last updated November 3, 2026