rerank.md

Rerank API

Aether exposes an OpenAI-compatible rerank surface at POST /v1/rerank and can route it to providers configured as openai:rerank or jina:rerank.

Request

POST /v1/rerank
Authorization: Bearer <aether-api-key>
Content-Type: application/json

{
  "model": "bge-reranker-base",
  "query": "What document discusses gateway routing?",
  "documents": [
    "Aether routes public AI requests through the Rust gateway.",
    "This document discusses unrelated content."
  ],
  "top_n": 1,
  "return_documents": true
}

Fields:

Field	Required	Notes
model	Yes	Aether global model name.
query	Yes	Non-empty query string.
documents	Yes	Non-empty array of strings or provider-native document objects.
top_n	No	Positive integer.
return_documents	No	Provider-compatible flag for including matched documents.

Response

Aether forwards the provider JSON response. OpenAI-compatible and Jina-compatible rerank providers commonly return results[]:

{
  "model": "bge-reranker-base",
  "results": [
    {
      "index": 0,
      "relevance_score": 0.98,
      "document": {
        "text": "Aether routes public AI requests through the Rust gateway."
      }
    }
  ],
  "usage": {
    "total_tokens": 32
  }
}

Rerank requests must be JSON and do not support stream or chat messages payloads.