--- title: "Rerank Documents" method: POST path: "/api/v3/inference/reranker" tags: ["Inference"] --- # Rerank Documents `POST /api/v3/inference/reranker` ## Request - Base URL: `https://api.nugen.in` - URL: `https://api.nugen.in/api/v3/inference/reranker` - Auth: HTTP bearer Rerank documents based on semantic relevance to a query. This endpoint computes semantic relevance scores for a list of documents against a query, returning them in descending order of relevance. Supports multiple reranking methods from fast bi-encoders to advanced hybrid approaches. Ideal for improving search results and retrieval-augmented generation (RAG) pipelines. **Request Body:** - `model`: Model ID (required). Use your aligned model id (e.g. `model_01kmqm4nrn9fw6r`); the same aligned id serves chat completions, completions and embeddings too - `query`: Search query or question text (required) - `documents`: Array of document texts or objects to rerank (required) - Can be strings or dictionaries **Returns:** - `results`: Array of reranked documents with relevance scores, each containing: - `index`: Original position in input array - `relevance_score`: Computed relevance score (higher = more relevant) - `document` (optional): Document text or object (if requested) - `meta`: Operation metadata containing: - `method`: Reranking method used - `deployed_model_id`: Model ID that was used - `model_cross` (optional): Cross-encoder model used (if applicable) - `stage1_top_k` (optional): Stage 1 top-k for hybrid methods **Example Request (Fast Method):** ```json POST /api/v3/inference/reranker Headers: {"Authorization": "Bearer "} { "model": "model_01kmqm4nrn9fw6r", "query": "How do I rotate API keys?", "documents": [ "Rotate keys from the admin console; the old key stays valid.", "Python is a popular programming language for web development.", "Expired keys are purged after a ninety day grace.", "The canteen menu changes on Mondays.", "Key rotation requires the security admin role." ], "method": "fast", "top_n": 3 } ``` **Example Response:** ```json { "results": [ { "index": 0, "relevance_score": 0.95, "document": "Rotate keys from the admin console; the old key stays valid." }, { "index": 4, "relevance_score": 0.82, "document": "Key rotation requires the security admin role." }, { "index": 2, "relevance_score": 0.76, "document": "Expired keys are purged after a ninety day grace." } ], "meta": { "method": "fast", "deployed_model_id": "cross-encoder/ms-marco-MiniLM-L-6-v2" } } ``` **Example Request (Hybrid Method):** ```json POST /api/v3/inference/reranker Headers: {"Authorization": "Bearer "} { "model": "model_01kmqm4nrn9fw6r", "query": "How is regional failover tested?", "documents": [ "Failover drills run each quarter against the standby region.", "The stock market is volatile today.", "Rollback restores the previous release build." ], } ``` **Example Response (Hybrid Method):** ```json { "results": [ { "index": 0, "relevance_score": 0.92, "document": "Failover drills run each quarter against the standby region." }, { "index": 2, "relevance_score": 0.88, "document": "Rollback restores the previous release build." } ], "meta": { "deployed_model_id": "model_01kmqm4nrn9fw6r", } } ``` **Use Cases:** - **Search Enhancement**: Improve search result ranking by semantic relevance - **RAG Pipelines**: Select most relevant context chunks for LLM prompts - **Semantic Filtering**: Find documents most related to a specific topic - **Question Answering**: Rank candidate answers by relevance to the question **Notes:** - Documents can be plain strings or structured objects (dictionaries) - Documents are returned in descending order of relevance (most relevant first) - Results are always sorted by relevance_score in descending order (highest first) - Relevance scores typically range from 0.0 to 1.0 ## Request body - RerankRequest: A rerank request: a query and the documents to order by relevance. - `model` string, required: Use your aligned model id (e.g. model_01kmqm4nrn9fw6r). The same aligned id serves chat completions, completions, embeddings and reranking. - `query` string, required: Search query - `documents` union[], required: Documents to rank - union - string - object - `method` 'fast' | 'standard' | 'optimal' | 'best': Rerank method: fast (bi-encoder), standard (cross-encoder), optimal (hybrid bi+cross), best (subspace+attention) - `model_cross` string, nullable: Cross-encoder model by Hugging Face id, e.g. cross-encoder/ms-marco-MiniLM-L-6-v2 (required for standard/optimal methods) - `top_n` integer, nullable: Return top N results - `stage1_top_k` integer: Stage 1 top-k for hybrid methods (optimal/best) - `max_tokens_per_doc` integer: Max tokens per document - `batch_size` integer, nullable: Batch size for processing - `return_documents` boolean: Include documents in response ## Response `200` Return the re-ranked chunks based on similarity - RerankResponse: Documents ordered by relevance to the query, with scores. - `results` RerankResult[], required: Ranked results - `index` integer, required: Document index in input - `relevance_score` number, required: Relevance score - `document` union: Document text (if requested) - string - object - `meta` RerankMeta, required: How a rerank request was run. - `method` 'fast' | 'standard' | 'optimal' | 'best', required: Rerank method used - `deployed_model_id` string, required: Model ID used - `model_cross` string, nullable: Cross-encoder used (if any) - `stage1_top_k` integer, nullable: Stage 1 top-k for hybrid methods ## Other responses - `401`: Invalid API key - `403`: Authorization header missing or not a Bearer token - `422`: Validation Error --- [API](https://skmtc.dev/nugen/apis/nugen-intelligence-api.md) - [All operations](https://skmtc.dev/nugen/apis/nugen-intelligence-api/llms.txt) - [OpenAPI document](https://skmtc.dev/nugen/apis/nugen-intelligence-api/revisions/62baa7960a4a?raw)