Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/jundot/omlx/llms.txt

Use this file to discover all available pages before exploring further.

The /v1/rerank endpoint scores a list of candidate documents against a query and returns them sorted by relevance. It is compatible with Cohere’s and Jina’s rerank API format. oMLX automatically detects reranker model families — ModernBERT and XLM-RoBERTa rerankers are supported — and handles scoring with the appropriate engine. Reranking is particularly useful as a second-stage retrieval step after an initial vector similarity search.

​
Supported models

FamilyExamples
ModernBERTmodernbert-reranker, jina-reranker-v2-base-multilingual
XLM-RoBERTabge-reranker-v2-m3, bge-reranker-large

​
Request

POST /v1/rerank

​
Parameters

​
model
string
required
The reranker model name or alias to use. Must match a reranker model discovered in your model directory.
​
query
string | object
required
The search query to compare each document against.
  • Pass a string for text-only rerankers.
  • Pass an object with text and/or image (URL, base64 data URI, or local path) for multimodal rerankers such as Qwen3-VL-Reranker.
​
documents
string[] | object[]
required
The documents to rerank. Can be:
  • A list of strings (plain text documents).
  • A list of objects, each with a text field and an optional image field for multimodal rerankers.
​
top_n
number
Number of top results to return. If not specified, all documents are returned sorted by score.
​
return_documents
boolean
default:"true"
Whether to include the original document text in the response. Set to false to return only scores and indices.
​
max_chunks_per_doc
number
Maximum number of chunks per document for long documents. Reserved for future use; not implemented in the current release.

​
Examples

curl http://localhost:8000/v1/rerank \
  -H "Content-Type: application/json" \
  -d '{
    "model": "bge-reranker-v2-m3",
    "query": "What is the capital of France?",
    "documents": [
      "Paris is the capital and largest city of France.",
      "The Eiffel Tower is a famous landmark in Paris.",
      "Berlin is the capital of Germany.",
      "France is a country in Western Europe."
    ],
    "top_n": 2
  }'

​
Response

​
id
string
Unique identifier for the rerank request, prefixed with rerank-.
​
results
object[]
Reranked document list, sorted by relevance_score descending. If top_n was specified, only the top N results are included.
​
model
string
The reranker model used.
​
usage
object

​
Example response

{
  "id": "rerank-a1b2c3d4",
  "results": [
    {
      "index": 0,
      "relevance_score": 0.9821,
      "document": {
        "text": "Paris is the capital and largest city of France."
      }
    },
    {
      "index": 1,
      "relevance_score": 0.7134,
      "document": {
        "text": "The Eiffel Tower is a famous landmark in Paris."
      }
    }
  ],
  "model": "bge-reranker-v2-m3",
  "usage": {
    "total_tokens": 128
  }
}

Build docs developers (and LLMs) love

Get started for freeTalk to us