# Rerank documents

`POST /v1/rerank`

Reranks a list of documents by relevance to the query

## Authorizations

Bearer authentication — send `Authorization: Bearer <token>`.

## Request Body (application/json) — required

```json
{
  "type": "object",
  "required": [
    "model",
    "query",
    "documents"
  ],
  "properties": {
    "model": {
      "type": "string",
      "example": "rerank-english-v2.0"
    },
    "query": {
      "type": "string",
      "description": "Query text"
    },
    "documents": {
      "type": "array",
      "items": {
        "oneOf": [
          {
            "type": "string"
          },
          {
            "type": "object",
            "properties": {}
          }
        ]
      },
      "description": "Documents to rerank"
    },
    "top_n": {
      "type": "integer",
      "description": "Return the top N results"
    },
    "return_documents": {
      "type": "boolean",
      "default": false
    }
  }
}
```

## Responses

### 200 — Documents reranked

```json
{
  "type": "object",
  "properties": {
    "id": {
      "type": "string"
    },
    "results": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "index": {
            "type": "integer"
          },
          "relevance_score": {
            "type": "number"
          },
          "document": {
            "type": "object",
            "properties": {}
          }
        }
      }
    },
    "meta": {
      "type": "object",
      "properties": {}
    }
  }
}
```