Rerank documents¶

Rerank candidate documents against a query and return relevance scores and original positions.

POST https://token.moi.matrixorigin.cn/v1/rerank

Before you begin¶

Prepare a personal access token or service account API key for Genesis. See Access credentials for credential selection and permissions.
Use List callable models to select a model that supports Rerank.

Request body¶

Replace $GENESIS_ACCESS_TOKEN and $MODEL_ID with your credential and the selected model ID.

Request example

curl -X POST \
  "https://token.moi.matrixorigin.cn/v1/rerank" \
  -H "Authorization: Bearer $GENESIS_ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
  "model": "'"$MODEL_ID"'",
  "query": "database",
  "documents": [
    "database transaction",
    "weather forecast"
  ],
  "top_n": 1,
  "return_documents": true
}'

Parameters

The fields below cover text queries and text candidates. Image or video reranking requires corresponding model capabilities and input configuration.

Parameter	Type	Required	Description
`model`	string	Yes	Selected model ID from `data[].id` in the model list.
`query`	string or object	Yes	Nonempty query text used to assess relevance. Object fields are listed below.
`query.content`	string or array of object	Required for an object query	Text or text blocks for an object input.
`query.content[].type`	string	Required for a text block	Use `text` for a text block.
`query.content[].text`	string	Required for a text block	Nonempty text content.
`documents`	array of string or array of object	Yes	Nonempty candidates; preserve their original order to identify returned results.
`documents[].content`	string or array of object	Required for an object document	Text or text blocks for an object input.
`documents[].content[].type`	string	Required for a text block	Use `text` for a text block.
`documents[].content[].text`	string	Required for a text block	Nonempty text content.
`top_n`	integer	No	Number of highest-ranked results to return; must be positive.
`return_documents`	boolean	No	Set to `true` to include candidate content in results.

Successful response¶

A successful request returns candidate results ordered by relevance.

Response example

{
  "id": "rerank-example",
  "model": "MODEL_ID",
  "results": [
    {
      "index": 0,
      "relevance_score": 0.98,
      "document": {
        "text": "database transaction"
      }
    }
  ],
  "usage": {
    "prompt_tokens": 5,
    "completion_tokens": 0,
    "total_tokens": 5
  }
}

Fields

Field	Type	Description
`id`	string	Rerank request identifier.
`model`	string	Model that processed the request.
`results`	array of object	Results ordered by relevance.
`results[].index`	integer	Zero-based position in the original `documents`.
`results[].relevance_score`	number	Relevance score assigned by the model.
`results[].document`	string or object	Included when candidate content is requested; text object fields are listed below.
`results[].document.text`	string	Candidate text.
`usage`	object	Token usage returned by the model.
`usage.prompt_tokens`	integer	Input tokens.
`usage.completion_tokens`	integer	Generated tokens.
`usage.total_tokens`	integer	Total input and generated tokens.

Error response¶

A missing model ID returns HTTP 400. Supply the model ID before sending the request again.

Response example

{
  "error": {
    "message": "missing required parameter: model",
    "type": "invalid_request",
    "code": "invalid_request"
  }
}

Fields

Field	Type	Description
`error`	object	Error details.
`error.message`	string	Error description; the example indicates a missing model ID.
`error.type`	string	Error type; may be omitted by a model service.
`error.code`	string or null	Error code; may be omitted by a model service.

Last updated on Oct 19, 2026