# Rerank

Rerank candidate content by query intent and return ranked results.

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

## Before you call

Prepare [credentials](../../../../guides/genesis/api-keys.md#choose-a-credential-type) with Genesis access, a model ID that supports Rerank, and a mapping between candidate content and business IDs.

## Request body

Replace `$GENESIS_ACCESS_TOKEN` with an access token or service-account API key, and `$MODEL_ID` with the model ID to call.

:::::::{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": "What is retrieval-augmented generation?",
    "documents": [
      "RAG augments model answers by retrieving an external knowledge base.",
      "Deep learning is a branch of machine learning.",
      "A vector database can store and retrieve high-dimensional vectors."
    ],
    "top_n": 2,
    "return_documents": true
  }'
```

:::::
:::::{tab-item} Parameter description

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `model` | string | Yes | Rerank model ID to call. |
| `query` | string | Yes | Query text used to determine candidate relevance. |
| `documents` | array of string | Yes | Text candidates to rerank. |
| `top_n` | integer | No | Number of highest-relevance results to return. |
| `return_documents` | boolean | No | Whether to return original candidate content in the results. |

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

## Successful response

The service returns reranked candidate content.

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

```json
{
  "id": "<REQUEST_ID>",
  "model": "<MODEL_ID>",
  "results": [
    { "index": 0, "relevance_score": 0.987, "document": "RAG augments model answers by retrieving an external knowledge base." }
  ]
}
```

:::::
:::::{tab-item} Field description

::::{tab-set}
:::{tab-item} Common fields

| Field | Type | Description |
| --- | --- | --- |
| `id` | string | Identifier for this rerank request. |
| `model` | string | Model ID that processed the request. |
| `results` | array of object | Result list ordered by relevance. |

:::
:::{tab-item} Result item

The following table expands each item in the example `results` array.

| Field | Type | Description |
| --- | --- | --- |
| `index` | integer | Index in the original `documents` array. |
| `relevance_score` | number | Relevance score assigned by the current model; compare it only within the same model and business context. |
| `document` | string or object | Original candidate content returned when `return_documents` is `true`. |

:::
:::{tab-item} Document object

The following table expands the `results[].document` object.

| Field | Type | Description |
| --- | --- | --- |
| `text` | string | Text candidate content when `document` is an object. |

:::
::::

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

## Error response

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

```json
{
  "error": {
    "message": "<human-readable error message>",
    "type": "<error type; may be omitted>",
    "code": "<error code; may be omitted>"
  }
}
```

:::::
:::::{tab-item} Field description

::::{tab-set}
:::{tab-item} Common fields

| Field | Type | Description |
| --- | --- | --- |
| `error` | object | Error object. |

:::
:::{tab-item} Error object

The following table expands the example `error` object.

| Field | Type | Description |
| --- | --- | --- |
| `message` | string | Human-readable error message. |
| `type` | string | Error category; it may be omitted. |
| `code` | string or null | Error code; it may be omitted. |

:::
::::

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