# Rerank documents

```{raw} html
<div class="mo-api-page-show-toc" aria-hidden="true"></div>
```

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

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

## Before you begin

1. Prepare a personal access token or service account API key for Genesis. See [Access credentials](../../../../guides/billing/credentials.md#choose-credential-type) for credential selection and permissions.
2. Use [List callable models](../models.md) to select a model that supports Rerank.

## Request body

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

:::::::{div} mo-api-tabs
::::::{tab-set}
:::::{tab-item} Request example

```bash
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
}'
```

:::::
:::::{tab-item} Parameters

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

::::{div} mo-api-parameter-table

| 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.

:::::::{div} mo-api-tabs mo-api-response-tabs
::::::{tab-set}
:::::{tab-item} Response example

```json
{
  "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
  }
}
```

:::::
:::::{tab-item} 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.

:::::::{div} mo-api-tabs mo-api-response-tabs
::::::{tab-set}
:::::{tab-item} Response example

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

:::::
:::::{tab-item} 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. |

:::::
::::::
:::::::