Rerank Documents
Last updated November 22, 2026
Synchronous document reranking endpoint compatible with Jina AI and standard RAG frameworks.
Synchronous document reranking endpoint compatible with Jina AI and standard /v1/rerank integrations (such as Dify, RAGFlow, LangChain, and LlamaIndex). Point your client base URL to Amux AI and authenticate with Authorization: Bearer <key>.
Looking for Jina Embeddings? Jina AI embedding models share the standard OpenAI-compatible
POST /v1/embeddingsendpoint under OpenAI compatible: see Create Embeddings, or browse model-specific guides under Embeddings / Jina AI (such as Jina Embeddings v5 Text Small and Jina Embeddings v5 Omni Small).
This page documents the shared POST /v1/rerank protocol schema. For model-specific context limits, listwise defaults (max_doc_length, return_embeddings), and multimodal image-text reranking formats, see the per-model guides under the Rerank section: Jina Reranker v3.5, Jina Reranker m0, and Jina Reranker v3.
https://gateway.amux.ai/v1/rerankAuthorization
headerAuthorizationstringRequiredBearer <your Amux AI key> Amux AI API key created in the console.
Content-TypestringRequiredDefault "application/json"Must be application/json.
Request
application/jsonmodelstringRequiredCanonical model ID or alias (for example jina/jina-reranker-v3.5 or jina-reranker-v3.5).
querystring | objectRequiredSearch query text (jina-reranker-m0 also accepts an image object { image } as a visual query).
documentsarray<string | object>RequiredNon-empty array of candidate documents to score and reorder (strings or { text }; multimodal models such as jina-reranker-m0 also accept { image }).
top_nintegerMaximum number of top-ranked results to return. Defaults to all documents.
return_documentsbooleanDefault trueWhether to include the original document content in each result item. Set to false to return only indices and relevance scores.
max_doc_lengthintegerMaximum tokens per document (1–8192; v3 / v3.5 only; defaults to 2048 on v3 and 8192 on v3.5; not supported on m0).
return_embeddingsbooleanDefault falseWhether to include document embeddings alongside relevance scores (v3 / v3.5 only).
Response
200responseDocuments ranked successfully in descending order of relevance.
400responseInvalid request body, missing query or documents, or model does not support the rerank endpoint.
402responseInsufficient workspace balance.
Protocol overview
- Synchronous, non-streaming: Rerank endpoints do not support streaming; passing
stream: truereturns a400error. - Descending relevance and bandwidth control:
resultsare sorted from highest to lowestrelevance_scorealong with each item's originalindexindocuments. Setreturn_documents: falsein production pipelines to omit echoed document bodies and reduce response payload size. - Input-token billing: Requests are billed based on the total input tokens (
usage.total_tokens) across the query and all candidate documents, with no output token charges. - Endpoint isolation: Rerank models cannot be invoked through
/v1/chat/completionsor/v1/embeddings.
Error handling
Errors follow the standard OpenAI error schema. Upstream validation failures return 400 invalid_request with field-level messages. See Errors and retries for full error definitions and retry behavior.
curl https://gateway.amux.ai/v1/rerank \
-H "Authorization: Bearer $AMUX_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "jina/jina-reranker-v3.5",
"query": "Organic skincare products for sensitive skin",
"top_n": 2,
"documents": [
"Organic skincare for sensitive skin with aloe vera and chamomile.",
"New makeup trends focus on bold colors and innovative techniques."
]
}'{
"model": "jina/jina-reranker-v3.5",
"results": [
{
"index": 0,
"relevance_score": 0.9421,
"document": {
"text": "Organic skincare for sensitive skin with aloe vera and chamomile."
}
}
],
"usage": {
"total_tokens": 42
}
}