API Reference
Reranker API
Send a query and candidate chunks, get a scored list back. Requests are simple; responses are deterministic, ordered by relevance, and ready for production pipelines.
Base URL
https://reranker.petromind.ai/api
Set via NEXT_PUBLIC_API_BASE_URL.
Authentication
Send X-API-Key for /rerank. Use JWT for /rerank/front.
Key format: rnk-sk-api-<64 chars>
Suffix uses letters, digits, and symbols (-,_).
Model tiers
light is default and fast. high uses the larger model for best quality.
Send mode to choose the tier.
Limits
API defaults to 50/day. Frontend defaults to 20/day.
Admins can override per user.
Quickstart
3-step integration
1) Pick the endpoint: /rerank (API key) or /rerank/front (JWT).
2) Send query + chunks. Add mode or top_k when needed.
3) Read results sorted by score (desc).
Minimal payload
{
"query": "What is water flooding?",
"chunks": [
{ "id": "c1", "text": "Water flooding is ..." }
]
}Minimal response
{
"results": [
{ "id": "c1", "score": 0.9231, "text": "Water flooding is ..." }
]
}Endpoint
POST /rerank
Server-side use with X-API-Key.
Endpoint
POST /rerank/front
Frontend-only, uses JWT bearer token.
Endpoint
GET /health
Public probe for uptime checks.
Auth flow (dashboard)
POST /auth/register - create account
POST /auth/verify-email - confirm code
POST /auth/login - start session
POST /auth/refresh - refresh access token
POST /auth/logout - revoke refresh token
Password helpers
POST /auth/resend-verification
POST /auth/forgot-password
POST /auth/reset-password
POST /auth/change-password
Request payload
POST /rerank
X-API-Key: <YOUR_API_KEY>
Content-Type: application/json
{
"query": "What is water flooding?",
"mode": "high",
"top_k": 5,
"chunks": [
{
"id": "c1",
"text": "Water flooding is ...",
"metadata": {
"source": "manual",
"page": 12
}
},
{
"id": "c2",
"text": "Gas injection is ...",
"metadata": {
"source": "notes",
"section": "EOR"
}
}
]
}Send mode only. The server maps it to the configured model. metadata is optional and returned as-is.
Request fields
query: user prompt (required)
chunks: array of objects (required)
chunks[].id: stable chunk id
chunks[].text: chunk content
chunks[].metadata: JSON object (optional)
top_k: 1-100 (optional)
mode: light | high (optional)
Response payload
{
"results": [
{ "id": "c1", "score": 0.9231, "text": "Water flooding is ..." },
{ "id": "c2", "score": 0.5328, "text": "Gas injection is ..." }
]
}Response fields
results: ordered by score desc
results[].id: original chunk id
results[].score: float relevance score
results[].text: original text
results[].metadata: original metadata
cURL
curl -X POST "https://reranker.petromind.ai/api/rerank" -H "X-API-Key: <YOUR_API_KEY>" -H "Content-Type: application/json" -d '{
"query": "What is water flooding?",
"top_k": 5,
"mode": "light",
"chunks": [
{"id": "c1", "text": "Water flooding is ..."},
{"id": "c2", "text": "Gas injection is ..."}
]
}'Python
import requests
url = "https://reranker.petromind.ai/api/rerank"
headers = {"X-API-Key": "<YOUR_API_KEY>"}
payload = {
"query": "What is water flooding?",
"chunks": [
{"id": "c1", "text": "Water flooding is ..."},
{"id": "c2", "text": "Gas injection is ..."}
],
"top_k": 5,
"mode": "light"
}
response = requests.post(url, json=payload, headers=headers, timeout=30)
print(response.json())
Node.js
import fetch from "node-fetch";
const url = "https://reranker.petromind.ai/api/rerank";
const payload = {
query: "What is water flooding?",
chunks: [
{ id: "c1", text: "Water flooding is ..." },
{ id: "c2", text: "Gas injection is ..." }
],
top_k: 5,
mode: "light"
};
const response = await fetch(url, {
method: "POST",
headers: {
"Content-Type": "application/json",
"X-API-Key": "<YOUR_API_KEY>"
},
body: JSON.stringify(payload)
});
await response.json();
Frontend usage
The dashboard uses JWT auth with /rerank/front. Include Authorization: Bearer <token>.
Same payload shape and mode options as the API key endpoint.
Use the playground to avoid burning production quota while iterating.
Frontend request
POST /rerank/front
Authorization: Bearer <token>
Content-Type: application/json
{
"query": "What is water flooding?",
"chunks": [
{ "id": "c1", "text": "Water flooding is ..." }
],
"mode": "light"
}Errors
400 invalid payload (missing query/chunks).
401 missing or invalid API key / token.
403 email verification required (auth endpoints).
429 daily quota exceeded.