Rerank¶

Rerank a list of documents by relevance to a query. Useful for improving search results, RAG pipelines, and information retrieval.

Endpoint¶

POST /v1/rerank

Request Body¶

Parameter	Type	Required	Description
`model`	string	✅	Rerank model ID
`query`	string	✅	The search query to rank against
`documents`	array	✅	List of text documents to rerank
`top_n`	integer		Return only the top N results. Default: all
`return_documents`	boolean		Include document text in response. Default: false

Example¶

cURL

curl https://ai.moducompia.com/v1/rerank \
  -H "Authorization: Bearer sk-YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "rerank-v3",
    "query": "How to deploy a Docker container?",
    "documents": [
      "Docker is a platform for containerization.",
      "To deploy a container, use docker compose up.",
      "Python is a programming language.",
      "Kubernetes orchestrates Docker containers at scale."
    ],
    "top_n": 3,
    "return_documents": true
  }'

Response¶

{
  "results": [
    {
      "index": 1,
      "relevance_score": 0.95,
      "document": {"text": "To deploy a container, use docker compose up."}
    },
    {
      "index": 3,
      "relevance_score": 0.82,
      "document": {"text": "Kubernetes orchestrates Docker containers at scale."}
    },
    {
      "index": 0,
      "relevance_score": 0.61,
      "document": {"text": "Docker is a platform for containerization."}
    }
  ]
}

Results are sorted by relevance_score (highest first). The index field refers to the position in the original documents array.