Amux AI

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/embeddings endpoint 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.

POSThttps://gateway.amux.ai/v1/rerank

Authorization

header
AuthorizationstringRequired

Bearer <your Amux AI key> Amux AI API key created in the console.

Content-TypestringRequiredDefault "application/json"

Must be application/json.

Request

application/json
modelstringRequired

Canonical model ID or alias (for example jina/jina-reranker-v3.5 or jina-reranker-v3.5).

querystring | objectRequired

Search query text (jina-reranker-m0 also accepts an image object { image } as a visual query).

documentsarray<string | object>Required

Non-empty array of candidate documents to score and reorder (strings or { text }; multimodal models such as jina-reranker-m0 also accept { image }).

top_ninteger

Maximum number of top-ranked results to return. Defaults to all documents.

return_documentsbooleanDefault true

Whether to include the original document content in each result item. Set to false to return only indices and relevance scores.

max_doc_lengthinteger

Maximum 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 false

Whether to include document embeddings alongside relevance scores (v3 / v3.5 only).

Response

200response

Documents ranked successfully in descending order of relevance.

400response

Invalid request body, missing query or documents, or model does not support the rerank endpoint.

402response

Insufficient workspace balance.

Protocol overview

  • Synchronous, non-streaming: Rerank endpoints do not support streaming; passing stream: true returns a 400 error.
  • Descending relevance and bandwidth control: results are sorted from highest to lowest relevance_score along with each item's original index in documents. Set return_documents: false in 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/completions or /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
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
  }
}