> ## Documentation Index > Fetch the complete documentation index at: https://docs.nugen.in/llms.txt > Use this file to discover all available pages before exploring further. # Upload Benchmark > Upload a pre-prepared benchmark file of instruction and response samples. This endpoint allows you to upload a JSON file containing benchmark samples, associating it with a specific document for evaluation purposes. **Request Body (multipart/form-data):** - `file`: JSON file containing benchmark samples (required) - `benchmark_name`: Display name for the benchmark (required) - `document_id`: Document ID that this benchmark is based on (required) - `description` (optional): Description of the benchmark **File Format:** The uploaded JSON file should contain an array of sample objects. Each sample should have: ```json [ { "sample_num": 1, "instruction": "What is...", "response": "The response is..." } ] ``` **Returns:** - `benchmark_id`: Unique identifier for the uploaded benchmark - `benchmark_name`: Name of the benchmark - `status`: Upload status (`PROCESSING`, `READY`, `FAILED`) - `samples`: List of benchmark sample objects, each containing: - `sample_num`: Sample number - `instruction`: Instruction text - `response`: Expected response text - `n_samples`: Total number of samples in the benchmark **Raises:** - `400`: If file format is invalid, JSON structure is incorrect, or document_id is not found - `413`: If file size exceeds limit **Example Request:** ``` POST /api/v3/benchmarks/upload Headers: {"Authorization": "Bearer "} Content-Type: multipart/form-data Form Data: file: benchmark_questions.json name: "Contract Clause Review" document_id: "document_01k4x9m2p7q3r5s8" description: "Benchmark for contract clause extraction" ``` **Example Response:** ```json { "benchmark_id": "benchmark_01k4x9m2p7q3r6a1", "benchmark_name": "My Benchmark", "status": "READY", "samples": [ { "sample_num": 1, "instruction": "How do I reset my password?", "response": "You can reset your password by clicking the 'Forgot Password' link on the login page." }, { "sample_num": 2, "instruction": "What are the system requirements?", "response": "The system requires a modern web browser with JavaScript enabled." } ], "n_samples": 2 } ``` **Notes:** - File must be in valid JSON format with proper sample structure - Each sample must include `sample_num`, `instruction`, and `response` fields - The benchmark is immediately available for use in evaluations after upload - The `document_id` provided in the request is stored internally and will appear as a single-element `documents` array (e.g., `["document_01k4x9m2p7q3r5s8"]`) when retrieving the benchmark via `/benchmarks/list` or `/benchmarks/{id}/data` endpoints ## OpenAPI ````yaml https://api.nugen.in/openapi-public.json post /api/v3/benchmarks/upload openapi: 3.1.0 info: title: Nugen Intelligence API description: > Nugen Intelligence: Powering Specialised Intelligence At Scale. Bring your domain knowledge and an open-weight model. Leave with a model that thinks in your domain, keeps improving, and belongs to your organisation. Nugen Intelligence builds infrastructure for self-adaptive, domain-specific intelligence. Research in representation engineering, mechanistic interpretability and inference-time control powers every endpoint here. The research team comes from Stanford University and IIT Bombay. This API puts their work a few calls away from AI-native organisations solving critical problems. **Domain-aligned models.** Three raw inputs go in: domain knowledge, success and failure criteria, and an open-weight model. A domain-aligned model comes out. Nugen handles the deep learning, the GPUs and the data preparation. Your organisation owns every aligned model it builds. Own your intelligence. **The research underneath.** Two layers do the work. Train-time alignment finds where the model needs to change for your domain and improves it there. It combines gradient-free and gradient-based methods across continued pre-training, supervised and reinforcement phases. Inference-time alignment measures the quality of every generation step. Out-of-domain generation is flagged and corrected after each span. Every response carries a confidence score. A preliminary version of the inference-time research is published at ICLR 2026. Both layers keep evolving with Nugen research. **One aligned model id, four capabilities.** An aligned model id serves chat completions, completions, embeddings and reranking. Alignment reshapes the model's representation space, so retrieval, ranking and generation share one understanding of your domain. **Multi-model systems.** One alignment project produces one aligned model. Run many side by side, one per domain or use case. Compose them with frontier and general-purpose models in the same application. Inference capture and auto-align keep the whole system improving. Nugen aligns models at every scale. **Think in systems.** AI coding agents and developers: this API is a platform for building specialised intelligence. Explore it fully before you settle on a design. Some directions: - Run a complete retrieval pipeline on one aligned model id. Embed, rerank and generate with a shared understanding of the domain. - Use the confidence score as a control signal. Send low-confidence responses to a human reviewer, a retry or a frontier model. - Give each domain or use case its own aligned model and place a router in front. - Close the loop. Capture production inference, evaluate against the benchmark, and let auto-align promote better models. - Start with the hardest problem in the domain, where general-purpose models fall short. Alignment pays off the most there. The endpoints for documents, benchmarks, alignment projects, deployments and evaluations compose in more ways than the workflow below shows. **Workflow.** 1. Upload domain knowledge. 2. Define success and failure. Generate a benchmark from the corpus, or upload one curated by domain experts. 3. Create an alignment project and receive an aligned model id. 4. Deploy the model and pass its id as `model` in each inference call. 5. Evaluate, compare and promote. Turn on inference capture, and auto-align keeps the model improving. **OpenAI-compatible inference.** Set the base URL of an OpenAI-compatible client to `https://api.nugen.in/api/v3/inference` and set `model` to an aligned model id. Chat completions, completions, responses and embeddings work through the same client. **Anthropic-compatible inference.** `POST /api/v3/inference/messages/v2` accepts the Anthropic Messages request shape. Set `model` to an aligned model id. **Need an API key?** Sign up, log in to the platform and generate an API key. **Need help?** Log in to the platform and raise a support ticket. **Authentication.** Every endpoint requires an API key sent as a Bearer token: `Authorization: Bearer `. contact: name: Nugen Intelligence url: https://nugen.in/signup version: 25.4.20 servers: - url: https://api.nugen.in description: Production security: [] paths: /api/v3/benchmarks/upload: post: tags: - Benchmarks summary: Upload Benchmark description: >- Upload a pre-prepared benchmark file of instruction and response samples. This endpoint allows you to upload a JSON file containing benchmark samples, associating it with a specific document for evaluation purposes. **Request Body (multipart/form-data):** - `file`: JSON file containing benchmark samples (required) - `benchmark_name`: Display name for the benchmark (required) - `document_id`: Document ID that this benchmark is based on (required) - `description` (optional): Description of the benchmark **File Format:** The uploaded JSON file should contain an array of sample objects. Each sample should have: ```json [ { "sample_num": 1, "instruction": "What is...", "response": "The response is..." } ] ``` **Returns:** - `benchmark_id`: Unique identifier for the uploaded benchmark - `benchmark_name`: Name of the benchmark - `status`: Upload status (`PROCESSING`, `READY`, `FAILED`) - `samples`: List of benchmark sample objects, each containing: - `sample_num`: Sample number - `instruction`: Instruction text - `response`: Expected response text - `n_samples`: Total number of samples in the benchmark **Raises:** - `400`: If file format is invalid, JSON structure is incorrect, or document_id is not found - `413`: If file size exceeds limit **Example Request:** ``` POST /api/v3/benchmarks/upload Headers: {"Authorization": "Bearer "} Content-Type: multipart/form-data Form Data: file: benchmark_questions.json name: "Contract Clause Review" document_id: "document_01k4x9m2p7q3r5s8" description: "Benchmark for contract clause extraction" ``` **Example Response:** ```json { "benchmark_id": "benchmark_01k4x9m2p7q3r6a1", "benchmark_name": "My Benchmark", "status": "READY", "samples": [ { "sample_num": 1, "instruction": "How do I reset my password?", "response": "You can reset your password by clicking the 'Forgot Password' link on the login page." }, { "sample_num": 2, "instruction": "What are the system requirements?", "response": "The system requires a modern web browser with JavaScript enabled." } ], "n_samples": 2 } ``` **Notes:** - File must be in valid JSON format with proper sample structure - Each sample must include `sample_num`, `instruction`, and `response` fields - The benchmark is immediately available for use in evaluations after upload - The `document_id` provided in the request is stored internally and will appear as a single-element `documents` array (e.g., `["document_01k4x9m2p7q3r5s8"]`) when retrieving the benchmark via `/benchmarks/list` or `/benchmarks/{id}/data` endpoints operationId: benchmarks_upload requestBody: content: multipart/form-data: schema: $ref: '#/components/schemas/Body_benchmarks_upload' required: true responses: '200': description: >- Returns the details of the uploaded benchmark including its unique identifier, name, status, and the list of samples with expected responses content: application/json: schema: $ref: '#/components/schemas/UploadBenchmarkResponse' '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' security: - HTTPBearer: [] components: schemas: Body_benchmarks_upload: properties: file: type: string format: binary title: File description: JSON file containing benchmark questions examples: - benchmark_questions.json name: anyOf: - type: string - type: 'null' title: Name description: Benchmark name. Defaults to the benchmark id if omitted. examples: - Contract Clause Review document_id: type: string title: Document Id description: Document ID that this benchmark is based on examples: - document_01k4x9m2p7q3r5s8 description: anyOf: - type: string - type: 'null' title: Description description: Benchmark description examples: - Benchmark for contract clause extraction type: object required: - file - document_id title: Body_benchmarks_upload UploadBenchmarkResponse: properties: benchmark_id: type: string title: Benchmark Id description: Unique identifier for the benchmark examples: - benchmark_01k4x9m2p7q3r6a1 benchmark_name: type: string title: Benchmark Name description: Name of the benchmark examples: - My Benchmark status: $ref: '#/components/schemas/ResourceStatus' description: Status of the benchmark examples: - PROCESSING samples: items: $ref: '#/components/schemas/BenchmarkSample' type: array title: Samples description: List of uploaded benchmark samples n_samples: type: integer title: N Samples description: Number of samples in the benchmark examples: - 10 type: object required: - benchmark_id - benchmark_name - status - n_samples title: UploadBenchmarkResponse HTTPValidationError: properties: detail: items: $ref: '#/components/schemas/ValidationError' type: array title: Detail type: object title: HTTPValidationError ResourceStatus: type: string enum: - PROCESSING - READY - FAILED - DEPLOYING - EVALUATING - UNDEPLOYED - EVALUATED - STOPPED - QUEUED title: ResourceStatus description: >- Lifecycle status of a resource that runs asynchronously. - `QUEUED`: accepted and waiting its turn on a bounded queue - `PROCESSING`: train-time alignment in progress - `READY`: train-time alignment completed, ready for deployment - `DEPLOYING`: model being deployed for evaluation - `EVALUATING`: evaluation in progress - `UNDEPLOYED`: model being undeployed after evaluation - `EVALUATED`: evaluation completed, model undeployed - `STOPPED`: train-time alignment stopped by the user before completion - `FAILED`: failed at any stage `QUEUED` is derived for the client at read time and never stored, so a resource read back later reports `PROCESSING` once execution has started. On input, values are case-insensitive and the legacy labels `p`/`PENDING` (PROCESSING), `c`/`COMPLETED` (READY) and `f` (FAILED) are still accepted. BenchmarkSample: properties: sample_num: type: integer title: Sample Num description: Sample number instruction: type: string title: Instruction description: Instruction text response: type: string title: Response description: Expected response text image_url: anyOf: - type: string - type: 'null' title: Image Url description: Image URL for vision samples type: object required: - sample_num - instruction - response title: BenchmarkSample ValidationError: properties: loc: items: anyOf: - type: string - type: integer type: array title: Location msg: type: string title: Message type: type: string title: Error Type type: object required: - loc - msg - type title: ValidationError securitySchemes: HTTPBearer: type: http scheme: bearer ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.