> ## Documentation Index
> Fetch the complete documentation index at: https://aisa.one/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Rerank Documents

> Reorder documents by relevance to a query using Jina rerank, served via the OpenAI-compatible AIsa relay.

Rerank a list of documents against a `query` using `jina-reranker-v3`. Provide a non-empty `query` and a non-empty `documents` array; results come back ordered by `relevance_score`. Use the optional `top_n` to return only the most relevant documents. This pairs naturally with embeddings-based retrieval: embed and shortlist candidates, then rerank for final ordering.

Served via the AIsa relay path `/v1/rerank` — OpenAI-compatible. Billing is token-based at **\$0.050 per 1M tokens**; the `usage.total_tokens` field reports the tokens billed for each request.

<CodeGroup>
  ```bash curl theme={null}
  curl https://api.aisa.one/v1/rerank \
    -H "Authorization: Bearer $AISA_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "model": "jina-reranker-v3",
      "query": "What is the capital of France?",
      "documents": [
        "Paris is the capital of France.",
        "Berlin is the capital of Germany.",
        "The Eiffel Tower is in Paris."
      ],
      "top_n": 2
    }'
  ```

  ```python Python theme={null}
  import requests

  resp = requests.post(
      "https://api.aisa.one/v1/rerank",
      headers={"Authorization": "Bearer sk-aisa-..."},
      json={
          "model": "jina-reranker-v3",
          "query": "What is the capital of France?",
          "documents": [
              "Paris is the capital of France.",
              "Berlin is the capital of Germany.",
              "The Eiffel Tower is in Paris.",
          ],
          "top_n": 2,
      },
  )
  print(resp.json()["results"])
  ```
</CodeGroup>


## OpenAPI

````yaml openapi/jina.json POST /rerank
openapi: 3.0.3
info:
  title: Jina Embeddings & Rerank API
  version: 1.0.0
  description: >-
    Jina embeddings and reranking served via the AIsa relay (OpenAI-compatible)
    path. Includes text embeddings (jina-embeddings-v3 and
    jina-embeddings-v5-text-small, both 1024-dim) and document reranking
    (jina-reranker-v3). Billing is token-based at $0.050 per 1M tokens for both
    endpoints.
servers:
  - url: https://api.aisa.one/v1
security:
  - BearerAuth: []
tags:
  - name: Embeddings & Rerank
paths:
  /rerank:
    post:
      summary: Rerank documents
      description: >-
        Rerank a list of documents against a query using jina-reranker-v3,
        returning documents ordered by relevance score. Served via the AIsa
        relay path /v1/rerank. Billing is token-based at $0.050 per 1M tokens.
      operationId: createRerank
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - model
                - query
                - documents
              properties:
                model:
                  type: string
                  description: Rerank model name.
                  example: jina-reranker-v3
                query:
                  type: string
                  description: Non-empty query string to rank documents against.
                  example: What is the capital of France?
                documents:
                  type: array
                  description: Non-empty array of document strings to rerank.
                  minItems: 1
                  items:
                    type: string
                  example:
                    - Paris is the capital of France.
                    - Berlin is the capital of Germany.
                    - The Eiffel Tower is in Paris.
                top_n:
                  type: integer
                  description: Optional. Return only the top N most relevant documents.
                  example: 2
            example:
              model: jina-reranker-v3
              query: What is the capital of France?
              documents:
                - Paris is the capital of France.
                - Berlin is the capital of Germany.
                - The Eiffel Tower is in Paris.
              top_n: 2
      responses:
        '200':
          description: Reranked results ordered by relevance.
          content:
            application/json:
              schema:
                type: object
                properties:
                  model:
                    type: string
                    example: jina-reranker-v3
                  results:
                    type: array
                    items:
                      type: object
                      properties:
                        index:
                          type: integer
                          description: Index of the document in the original request array.
                          example: 0
                        relevance_score:
                          type: number
                          format: float
                          example: 0.98
                        document:
                          type: object
                          properties:
                            text:
                              type: string
                              example: Paris is the capital of France.
                  usage:
                    type: object
                    properties:
                      total_tokens:
                        type: integer
                        example: 27
              example:
                model: jina-reranker-v3
                results:
                  - index: 0
                    relevance_score: 0.98
                    document:
                      text: Paris is the capital of France.
                  - index: 2
                    relevance_score: 0.71
                    document:
                      text: The Eiffel Tower is in Paris.
                usage:
                  total_tokens: 27
components:
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: API Key

````