Rerank¶

POST /rerank ranks candidate documents against a query. It commonly follows vector retrieval so that only the most relevant results are sent to a generation model. Reranking is not standardized by the OpenAI protocol; use the Genesis Use page and the live response as the contract.

Request¶

curl "$GENESIS_BASE_URL/rerank" \
  -H "Authorization: Bearer $GENESIS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "<rerank-model-id>",
    "query": "How do I create a Genesis API Key?",
    "documents": [
      "Create a service account in Credential Management and issue a Genesis API Key.",
      "Create a new table in MatrixOne.",
      "Open the Usage page to inspect model-call statistics."
    ],
    "top_n": 2,
    "return_documents": true
  }'

Parameter	Description
`model`	Reranking model ID
`query`	Text used to judge relevance
`documents`	Array of candidate-document strings
`top_n`	Optional; return only the N highest-ranked entries
`return_documents`	Optional; include the source text in each result

The response normally contains relevance-ordered results. results[].index points to the corresponding item in the request’s documents; results[].relevance_score contains the model score. When source text is enabled, read results[].document.text. The endpoint can also return usage.

Scores are suitable for ordering within the same model and workload. Do not compare scores from different models or adopt a universal relevance threshold without evaluating it against your own data.

Multimodal candidates¶

A multimodal reranking model can represent query and documents as unified content parts that mix text and images. This is not a standard OpenAI shape. Use it only when the model details explicitly list the capability, and copy the current format from the console code generator.

Place reranking in a retrieval pipeline¶

A typical pipeline retrieves a larger candidate set with embeddings, reranks those candidates, and passes only the first few to a chat model. Preserve the mapping between each result index and your document ID. Choose the retrieval count and top_n through offline evaluation rather than sending the entire corpus to Rerank.

For retrieval input handling, see Embeddings. For obtaining a model ID, see Models and Providers.