Rerank Integration

Rerank is used to reorder a batch of candidate documents by user query, commonly used in RAG, search, knowledge base Q&A, and recommendation scenarios.

Interface Information

Configuration	Value
Endpoint	https://api.corerouter.cloud/v1/rerank
Header	Authorization: Bearer sk-...
Required Fields	model, query, documents
Return Fields	results, each typically contains index, relevance_score, optional document
Model Requirement	Model ID from console that supports Rerank

Minimal Request

export COREROUTER_API_KEY="sk-xxxxxxxxxxxxxxxx"

curl https://api.corerouter.cloud/v1/rerank \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $COREROUTER_API_KEY" \
  -d '{
    "model": "rerank-model-id",
    "query": "How to configure API Key?",
    "documents": [
      "Create API Key in console and send via Authorization Header.",
      "Image generation requires selecting image models.",
      "Base URL typically filled as https://api.corerouter.cloud/v1."
    ],
    "top_n": 2,
    "return_documents": true
  }'

Field Description

Field	Required	Description
model	Yes	Rerank model ID from console.
query	Yes	User query or search question.
documents	Yes	Candidate document array, can be strings or document objects supported by model/channel.
top_n	No	Only return top N results.
return_documents	No	Whether to return original documents in results.
max_chunk_per_doc	No	Long document chunking parameter; effectiveness depends on channel.
overlap_tokens	No	Token overlap count for long document chunking; effectiveness depends on channel.

Return Example

{
  "results": [
    {
      "index": 0,
      "relevance_score": 0.93,
      "document": "Create API Key in console and send via Authorization Header."
    },
    {
      "index": 2,
      "relevance_score": 0.81,
      "document": "Base URL typically filled as https://api.corerouter.cloud/v1."
    }
  ],
  "usage": {
    "prompt_tokens": 123,
    "total_tokens": 123
  }
}

Recommended RAG Flow

1. Use Embeddings to recall 20 to 100 candidate documents from vector database.
2. Use Rerank to reorder candidates by user question.
3. Take top 3 to 10 as context for Chat Completions or Responses.
4. Retain citation sources in final answer for user verification.

Common Issues

• query is empty: Request body missing query or value is empty.
• documents is empty: Request body missing documents or array is empty.
• model not found: Don't use chat model IDs; use models that support Rerank.
• Scores appear unstable: Check if candidate documents are too long, contain irrelevant content, and Embeddings recall quality.