API / Endpoints

Rerank

POST /v1/rerank — score and order documents by relevance to a query using a Jina reranker model.

Browse docs

POST /v1/rerank accepts a query and a list of documents and returns the documents sorted by relevance, each with a relevance score. Aurora's rerank implementation targets Jina's /v1/rerank endpoint and is the recommended way to add a second-stage reranker on top of a vector retrieval pipeline.

Request

text

POST /v1/rerank
Authorization: Bearer <master or managed key>
Content-Type: application/json
 
{
  "model": "jina/jina-reranker-v2-base-multilingual",
  "query": "How does Aurora handle failover?",
  "documents": [
    "Aurora retries failed requests across configured provider pools.",
    "Pizza is a popular Italian food.",
    "Failover is controlled by the fallback: section of config.yaml."
  ],
  "top_n": 2,
  "return_documents": true
}

Field	Type	Required	Description
`model`	string	yes	`provider/model` ID. Currently `jina/*` rerank models.
`query`	string	yes	The query to rank documents against.
`documents`	string[]	yes	The candidate documents. Strings, not pre-computed embeddings.
`top_n`	integer	no	Return only the top N results. Defaults to all.
`return_documents`	boolean	no	Whether to include the original document text in the response. Defaults to `true`.

Response

text

{
  "id": "rerank-9f3b1a",
  "model": "jina/jina-reranker-v2-base-multilingual",
  "results": [
    {
      "index": 2,
      "relevance_score": 0.91,
      "document": "Failover is controlled by the fallback: section of config.yaml."
    },
    {
      "index": 0,
      "relevance_score": 0.74,
      "document": "Aurora retries failed requests across configured provider pools."
    }
  ],
  "usage": {
    "prompt_tokens": 0,
    "completion_tokens": 0,
    "total_tokens": 0
  }
}

The response shape is the Jina shape and is preserved end-to-end.

Models

Model	Notes
`jina/jina-reranker-v2-base-multilingual`	Multilingual reranker. Default.
`jina/jina-reranker-v2-base-en`	English-only reranker.
`jina/jina-reranker-m0`	Multimodal reranker (text + image).

See the Jina guide for activation and pooling.

RAG recipe

text

from openai import OpenAI
 
client = OpenAI(base_url="http://localhost:8080/v1", api_key="sk-aurora-...")
 
# 1. embed the query
query_vec = client.embeddings.create(
    model="jina/jina-embeddings-v3",
    input="How does Aurora handle failover?",
).data[0].embedding
 
# 2. (your vector store) retrieve top 50 candidate documents
candidates = your_vector_store.search(query_vec, top_k=50)
 
# 3. rerank to the top 5
ranked = client.post("/v1/rerank", cast_to=object, body={
    "model": "jina/jina-reranker-v2-base-multilingual",
    "query": "How does Aurora handle failover?",
    "documents": [c.text for c in candidates],
    "top_n": 5,
})

Gotchas

Model strings — only jina/* rerank models are valid. Other providers' rerank APIs are not yet wired.
Top N — top_n must be <= len(documents). Aurora returns a 400 if it isn't.
Streaming — rerank is non-streaming; the full ranked list comes back in one response.
Workflows — rerank requests respect workflows keyed on provider: jina, so you can disable audit/usage/guardrails for rerank-only traffic.
Caching — rerank is not covered by the response cache (exact or semantic). The input documents are usually large and rarely identical, so caching rarely helps.

Jina guide
Embeddings
Provider Pools — pool Jina across multiple keys for high-throughput rerank

Request

text

POST /v1/rerank
Authorization: Bearer <master or managed key>
Content-Type: application/json
 
{
  "model": "jina/jina-reranker-v2-base-multilingual",
  "query": "How does Aurora handle failover?",
  "documents": [
    "Aurora retries failed requests across configured provider pools.",
    "Pizza is a popular Italian food.",
    "Failover is controlled by the fallback: section of config.yaml."
  ],
  "top_n": 2,
  "return_documents": true
}

Field	Type	Required	Description
`model`	string	yes	`provider/model` ID. Currently `jina/*` rerank models.
`query`	string	yes	The query to rank documents against.
`documents`	string[]	yes	The candidate documents. Strings, not pre-computed embeddings.
`top_n`	integer	no	Return only the top N results. Defaults to all.
`return_documents`	boolean	no	Whether to include the original document text in the response. Defaults to `true`.

Response

text

{
  "id": "rerank-9f3b1a",
  "model": "jina/jina-reranker-v2-base-multilingual",
  "results": [
    {
      "index": 2,
      "relevance_score": 0.91,
      "document": "Failover is controlled by the fallback: section of config.yaml."
    },
    {
      "index": 0,
      "relevance_score": 0.74,
      "document": "Aurora retries failed requests across configured provider pools."
    }
  ],
  "usage": {
    "prompt_tokens": 0,
    "completion_tokens": 0,
    "total_tokens": 0
  }
}

The response shape is the Jina shape and is preserved end-to-end.

Model

Notes

jina/jina-reranker-v2-base-multilingual

Multilingual reranker. Default.

jina/jina-reranker-v2-base-en

English-only reranker.

jina/jina-reranker-m0

Multimodal reranker (text + image).

RAG recipe

text

from openai import OpenAI
 
client = OpenAI(base_url="http://localhost:8080/v1", api_key="sk-aurora-...")
 
# 1. embed the query
query_vec = client.embeddings.create(
    model="jina/jina-embeddings-v3",
    input="How does Aurora handle failover?",
).data[0].embedding
 
# 2. (your vector store) retrieve top 50 candidate documents
candidates = your_vector_store.search(query_vec, top_k=50)
 
# 3. rerank to the top 5
ranked = client.post("/v1/rerank", cast_to=object, body={
    "model": "jina/jina-reranker-v2-base-multilingual",
    "query": "How does Aurora handle failover?",
    "documents": [c.text for c in candidates],
    "top_n": 5,
})

Gotchas

Model strings — only jina/* rerank models are valid. Other providers' rerank APIs are not yet wired.

Top N — top_n must be <= len(documents). Aurora returns a 400 if it isn't.

Streaming — rerank is non-streaming; the full ranked list comes back in one response.

Workflows — rerank requests respect workflows keyed on provider: jina, so you can disable audit/usage/guardrails for rerank-only traffic.

Caching — rerank is not covered by the response cache (exact or semantic). The input documents are usually large and rarely identical, so caching rarely helps.

Rerank

Request

Response

Models

RAG recipe

Gotchas

Related

Rerank

Request

Response

Models

RAG recipe

Gotchas

Related