# Create Benchmark
Source: https://docs.nugen.in/api-reference/benchmarks/create-benchmark

https://api.nugen.in/openapi-public.json post /api/v3/benchmarks/create
Create a new benchmark generation run from documents.


This endpoint starts a benchmark generation run over the documents you name. The generated samplions can be used for model evaluation and testing.


**Request Body:**

- `document_ids`: List of document IDs to generate benchmarks from (required)
- `n_samples`: Number of benchmark samples to generate (required)
- `benchmark_name` (optional): Display name. Defaults to the benchmark id if omitted


**Returns:**

- `benchmark_id`: Unique identifier for tracking generation progress
- `status`: Initial status (always `PROCESSING`)


**Raises:**

- `400`: If no documents provided
- `400`: If document validation fails (missing documents or unauthorized access)


**Example Request:**

```json
POST /api/v3/benchmarks/create
Headers: {"Authorization": "Bearer <api_key>"}

{
  "document_ids": ["document_01k4x9m2p7q3r5s8", "document_01k4x9m2p7q3r5sc", "document_01k4x9m2p7q3r5sd"],
  "n_samples": 10
}
```


**Example Response:**

```json
{
  "benchmark_id": "benchmark_01k4x9m2p7q3r6a1",
  "status": "PROCESSING"
}
```


**Notes:**

- All document IDs are validated before creation to ensure they exist and belong to the user
- Use the returned benchmark_id with `/benchmarks/{id}/status` endpoint to track generation progress
- Once completed, the benchmark will be available for use in model evaluations



# Delete Benchmark
Source: https://docs.nugen.in/api-reference/benchmarks/delete-benchmark

https://api.nugen.in/openapi-public.json delete /api/v3/benchmarks/{benchmark_id}
Delete a benchmark permanently.


This endpoint permanently removes a benchmark and all its associated data. Only the owner of the benchmark can delete it.


**Path Parameters:**

- `benchmark_id`: Unique identifier of the benchmark to delete


**Returns:**

Success response containing:

- `benchmark_id`: The deleted benchmark identifier
- `message`: Confirmation message


**Raises:**

- `404`: If benchmark not found or doesn't belong to the user


**Example Request:**

```json
DELETE /api/v3/benchmarks/benchmark_01k4x9m2p7q3r6a1
Headers: {"Authorization": "Bearer <api_key>"}
```


**Example Response:**

```json
{
  "benchmark_id": "benchmark_01k4x9m2p7q3r6a1",
  "message": "Benchmark successfully deleted"
}
```


**Warning:**

This action is permanent and cannot be undone. All benchmark samples will be permanently deleted.



# Get Benchmark
Source: https://docs.nugen.in/api-reference/benchmarks/get-benchmark

https://api.nugen.in/openapi-public.json get /api/v3/benchmarks/{benchmark_id}
Get one benchmark by ID.

**Returns:**

- `benchmark_id`, `benchmark_name`, `status` (`PROCESSING`, `READY`, `FAILED`)
- `n_samples`, `source` (`generated` or `uploaded`)
- `created_at`, `completed_at`, `updated_at`
- `progress`, `eta_seconds`: not wired up yet, always null



# Get Benchmark Status
Source: https://docs.nugen.in/api-reference/benchmarks/get-benchmark-status

https://api.nugen.in/openapi-public.json get /api/v3/benchmarks/{benchmark_id}/status
Get the status of a benchmark generation run.


This endpoint retrieves the current status of a benchmark generation run. Use this to track the progress of benchmark generation initiated by the create endpoint.


**Path Parameters:**

- `benchmark_id`: Unique identifier returned from the create endpoint


**Returns:**

- `benchmark_id`: unique identifier
- `status`: status (`PROCESSING` while running, `READY` when finished)
- `created_at`, `completed_at`, `updated_at`: timestamps
- `progress`, `eta_seconds`: not wired up yet, always null


**Raises:**

- `404`: If the benchmark or its documents are not found


**Example Request:**

```json
GET /api/v3/benchmarks/benchmark_01k4x9m2p7q3r6a1/status
Headers: {"Authorization": "Bearer <api_key>"}
```


**Example Response:**

```json
{
  "benchmark_id": "benchmark_01k4x9m2p7q3r6a1",
  "status": "READY",
  "created_at": "2024-01-15T10:30:00Z",
  "completed_at": "2024-01-15T10:32:45Z",
  "updated_at": "2024-01-15T10:32:45Z",
  "progress": null,
  "eta_seconds": null
}
```


**Notes:**

- Status remains `PROCESSING` while the generation process is running
- Status changes to `READY` once all samples are generated



# Get Generated Benchmark
Source: https://docs.nugen.in/api-reference/benchmarks/get-generated-benchmark

https://api.nugen.in/openapi-public.json get /api/v3/benchmarks/{benchmark_id}/data
Retrieve complete benchmark data with all samples.


This endpoint returns the full benchmark dataset including all samples, their expected responses, and metadata. Use this to access the complete benchmark content for evaluation or review.


**Path Parameters:**

- `benchmark_id`: Unique benchmark identifier


**Returns:**

- `benchmark_id`: Benchmark identifier
- `document_ids`: List of document IDs (single-element array for uploaded benchmarks, multiple elements for generated benchmarks)
- `samples`: Full list of benchmark samples with their responses

Identity, status, and timestamps are served by `GET /{benchmark_id}`.


**Raises:**

- `404`: If benchmark not found or user doesn't have access


**Example Request:**

```json
GET /api/v3/benchmarks/benchmark_01k4x9m2p7q3r6a1/data
Headers: {"Authorization": "Bearer <api_key>"}
```


**Example Response:**

```json
{
  "benchmark_id": "benchmark_01k4x9m2p7q3r6a1",
  "document_ids": ["document_01k4x9m2p7q3r5se", "document_01k4x9m2p7q3r5sf"],
  "samples": [
    {
      "sample_num": 1,
      "instruction": "What is the main purpose of the product?",
      "response": "To provide real-time collaboration tools for distributed teams."
    },
    {
      "sample_num": 2,
      "instruction": "How does the authentication system work?",
      "response": "Uses OAuth 2.0 with JWT tokens for secure authentication."
    }
  ]
}
```


**Notes:**

- Only returns benchmarks owned by the user
- Contains complete sample data for evaluation
- Use this endpoint when you need the full benchmark content (not just metadata)



# List Benchmarks
Source: https://docs.nugen.in/api-reference/benchmarks/list-benchmarks

https://api.nugen.in/openapi-public.json get /api/v3/benchmarks/list
Retrieve all benchmarks for the user.


This endpoint returns a paginated list of all benchmarks created or uploaded by the user, including both generated and manually uploaded benchmarks.


**Query Parameters:**

- `status` (optional): Filter by benchmark status
- `limit` (optional): Number of benchmarks to return (1-100, default: 10)
- `offset` (optional): Number of benchmarks to skip for pagination (default: 0)


**Returns:**

- `benchmarks`: List of benchmark objects, each containing:
  - `benchmark_id`: Unique benchmark identifier
  - `benchmark_name`: Display name of the benchmark
  - `status`: Benchmark status (`PROCESSING`, `READY`, `UPLOADED`)
  - `created_at`: Timestamp when benchmark was created


**Example Request:**

```json
GET /api/v3/benchmarks/list
Headers: {"Authorization": "Bearer <api_key>"}
```


**Example Response:**

```json
{
  "benchmarks": [
    {
      "benchmark_id": "benchmark_01k4x9m2p7q3r6a1",
      "benchmark_name": "Benchmark_document_01k4x9m2p7q3r5se",
      "status": "READY",
      "created_at": "2024-01-15T10:30:00Z"
    },
    {
      "benchmark_id": "benchmark_01k4x9m2p7q3r6a2",
      "benchmark_name": "Benchmark_document_01k4x9m2p7q3r5sg",
      "status": "uploaded",
      "created_at": "2024-01-16T14:20:00Z"
    }
  ]
}
```



# Upload Benchmark
Source: https://docs.nugen.in/api-reference/benchmarks/upload-benchmark

https://api.nugen.in/openapi-public.json post /api/v3/benchmarks/upload
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 <api_key>"}
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



# Deploy in your own cloud or cluster
Source: https://docs.nugen.in/api-reference/byoc/deploy-in-your-own-cloud-or-cluster

https://api.nugen.in/openapi-public.json post /api/v3/byoc/clusters
Deploy alignment infrastructure inside your own cloud or cluster. Register your cloud environment or existing Kubernetes cluster.

All alignment training, model storage and inference then run within your
network boundary. No data leaves your environment.

Two paths are supported.

**Managed provisioning.** Provide a clean, isolated cloud subscription or
project. The system provisions a hardened Kubernetes environment from
infrastructure-as-code blueprints, configures GPU scheduling and manages
ongoing operations through secure GitOps pipelines. No access to your
corporate network is required.

**Cluster import.** Point to an existing cluster or namespace. The system
deploys a self-contained serving and training stack configured to your
constraints: storage classes, ingress rules, identity bindings, registry
policies. Updates arrive through private registry syncs, so your security team
controls when changes land.

Once connected, every endpoint in this platform behaves identically whether it
runs on our infrastructure or inside yours. The same alignment workflows, model
management, auto-align and export paths work unchanged. The system manages GPU
node health, autoscaling, deployment lifecycle and performance within your
cluster.


**Request Body:**

- `cluster_name` (required): Name for this environment
- `mode` (required): `managed_provisioning` or `cluster_import`
- `cloud` (required): Provider, region and the stored credential reference
- `cluster_import` (optional): Kubeconfig reference, endpoint, namespace and
  node labels. Required when `mode` is `cluster_import`
- `config` (optional): gpu, networking, storage, iam, registry, operations,
  capabilities, compliance, overflow and notifications


**Returns:**

- `cluster_id`: Identifier of this environment
- `cluster_name`, `status`, `message`


**Raises:**

- `400`: If `mode` is `cluster_import` and no `cluster_import` block is given


**Notes:**

- Egress is restricted and endpoints are private by default; you open them
  explicitly
- Air-gapped registries are a first-class path, and your team controls the
  sync cadence
- Bring your own cloud is an Enterprise Edition capability. The request is
  recorded and our team follows up; raise a support ticket to enable it
- Poll `GET /byoc/clusters/{cluster_id}/status` for provisioning progress and
  cluster health



# Get Cluster Health
Source: https://docs.nugen.in/api-reference/byoc/get-cluster-health

https://api.nugen.in/openapi-public.json get /api/v3/byoc/clusters/{cluster_id}/status
Provisioning progress and health for one environment.


**Path Parameters:**

- `cluster_id`: The environment to check


**Returns:**

- `cluster_id`, `cluster_name`, `mode`
- `status`: Provisioning status
- `message`: What the status means
- `created_at`: When the request was received


**Raises:**

- `404`: If the environment is not found or does not belong to you



# Delete Document
Source: https://docs.nugen.in/api-reference/documents/delete-document

https://api.nugen.in/openapi-public.json delete /api/v3/documents/{document_id}
Permanently delete a document.

This endpoint removes a document from the system. Note that this only deletes
the document record and metadata.

**Args**:
    `document_id`: Document ID to delete (path parameter)

**Returns**:
    `DeleteDocumentResponse`: Deletion confirmation containing:
        - `document_id`: ID of the deleted document
        - `message`: Success confirmation message

**Raises**:
    - `404`: If the document is not found or doesn't belong to the user

**Example**:
    **Request**:
    ```
        DELETE /api/v3/documents/document_01k4x9m2p7q3r5sa
        Headers: {"Authorization": "Bearer <api_key>"}
    ```
    **Response**:
    ```
        {
            "document_id": "document_01k4x9m2p7q3r5sa",
            "message": "Document Deleted Successfully"
        }
    ```



# Get Document
Source: https://docs.nugen.in/api-reference/documents/get-document

https://api.nugen.in/openapi-public.json get /api/v3/documents/{document_id}
Fetch a document's details.

**Args**:
    `document_id`: Document ID (path parameter)

**Raises**:
    - `404`: If the document is not found or doesn't belong to the user



# Get Document Status
Source: https://docs.nugen.in/api-reference/documents/get-document-status

https://api.nugen.in/openapi-public.json get /api/v3/documents/{document_id}/status
Check the upload status of a document.

Use this endpoint to monitor the progress of a document upload after receiving
its document_id from the upload endpoint. The status indicates whether the document
is still being uploaded, has completed successfully, or has failed.

**Args**:
    `document_id`: Document ID returned from the upload endpoint (path parameter)

**Returns**:
    `dict`: Upload status information containing:
        - status: Current upload status ("PROCESSING", "READY", "FAILED")
        - document_id: Document ID once upload is COMPLETED (null if still uploading)
        - created_at, completed_at, updated_at: timestamps
        - progress, eta_seconds: not wired up yet, always null

**Raises**:
    - `404`: If the document is not found or doesn't belong to the user

**Example**:
    **Request**:
        ```GET /api/v3/documents/{document_id}/status
            Headers: {"Authorization": "Bearer <api_key>"}
        ```
    **Response**:
    ```
        {
            "status": "READY",
            "document_id": "document_01k4x9m2p7q3r5sa",
            "created_at": "2024-01-15T10:30:00Z",
            "completed_at": "2024-01-15T10:31:00Z",
            "updated_at": "2024-01-15T10:31:00Z",
            "progress": null,
            "eta_seconds": null
        }
    ```



# List Documents
Source: https://docs.nugen.in/api-reference/documents/list-documents

https://api.nugen.in/openapi-public.json get /api/v3/documents/list
Retrieve all documents and categories for the authenticated user.

This endpoint returns a paginated, lean list row per document. Fetch `GET /documents/{id}` for the full record: filename, type, size, uploader, processing progress.


**Query Parameters:**

- `status` (optional): Filter by document status
- `limit` (optional): Number of documents to return (1-100, default: 10)
- `offset` (optional): Number of documents to skip for pagination (default: 0)


**Returns:**

- `List of document objects, each containing`:
  - `document_id`: Unique document identifier
  - `document_name`: Display name of the document
  - `status`: Processing status (e.g., `READY`, `PROCESSING`, `FAILED`)
  - `created_at`: ISO 8601 timestamp when the document was created
  - `categories`: List of category names assigned to this document

- `categories`: List of category objects, each containing:
  - `name`: Category name
  - `count`: Number of documents in this category


**Example Request:**

```json
GET /api/v3/documents/list
Headers: {"Authorization": "Bearer <api_key>"}
```


**Example Response:**

```json
{
  "documents": [
    {
      "document_id": "document_01k4x9m2p7q3r5s8",
      "document_name": "Quarterly Report",
      "status": "READY",
      "created_at": "2024-01-15T10:30:00Z",
      "categories": ["financial", "2024"]
    },
    {
      "document_id": "document_01k4x9m2p7q3r5sa",
      "document_name": "Meeting Notes",
      "status": "PROCESSING",
      "created_at": "2024-01-16T14:20:00Z",
      "categories": ["meetings"]
    }
  ],
  "categories": [
    {
      "name": "financial",
      "count": 5
    },
    {
      "name": "2024",
      "count": 12
    },
    {
      "name": "meetings",
      "count": 8
    }
  ]
}
```


**Notes:**

- Categories are automatically extracted and organized for easy filtering
- Each category shows the total count of documents tagged with that category



# Upload Documents
Source: https://docs.nugen.in/api-reference/documents/upload-documents

https://api.nugen.in/openapi-public.json post /api/v3/documents/create
Upload multiple documents.

**Request Body (multipart/form-data):**

- `files`: List of files to upload (required)
- `categories` (optional): List of category names to organize documents
- `names` (optional): List of display names, matched to files by position


**Returns:**

- `documents`: One unique document id per uploaded file, for status polling and later use

**Supported File Types:**
- Text-based files only
- Each document needs at least 500 words; training dataset JSONL files are exempt. If any file is shorter, the whole upload is refused with 400 naming each short file

**Editions:**

The developer edition accepts plain text files only. PDF and other formats are available on the enterprise edition, which also accepts cloud storage URIs (`s3://`, `gs://`, `oci://`, `abfss://`) as the data source.

**File Size Limit:**

Maximum 100 MB per file


**Example Request:**

```
POST /api/v3/documents/create
Headers: {"Authorization": "Bearer <api_key>"}
Content-Type: multipart/form-data

Form Data:
  files: [report.txt, analysis.md]
  categories: ["financial", "2024-q1"]
```


**Example Response:**

```json
{"document_ids": ["01KKBB7NPTMXM12", "01KKBB7NPTJDK43"]}
```


**Processing:**

Uploads are processed asynchronously. Poll `GET /api/v3/documents/{id}/status` until READY before using a document id elsewhere. Requires organisation membership.



# Create Evaluation
Source: https://docs.nugen.in/api-reference/evaluations/create-evaluation

https://api.nugen.in/openapi-public.json post /api/v3/evaluations/create
Create a new model evaluation using an existing benchmark.

This endpoint initiates a model evaluation using a benchmark from your library. Supports both single model evaluation and comparison mode where two models are evaluated side-by-side.

**Request Body:**

- `model_id`: Primary model to evaluate (required). An aligned model that is not deployed is deployed for the evaluation and undeployed when it ends; one already deployed stays deployed. If it needs a deployment while all 10 deployment slots of your organisation are in use, the request is refused with 400.
- `benchmark_id`: ID of the benchmark to use for evaluation (required)
- `baseline_model_id` (optional): Baseline model ID for comparison mode
- `custom_metrics` (optional): Custom evaluation metrics configuration
- `evaluation_name` (optional): Display name. Defaults to the evaluation id if omitted

**Returns:**

- `evaluation_id`: Unique identifier for tracking the evaluation
- `model_id`: The primary model being evaluated
- `status`: Initial status (always `PROCESSING`)
- `benchmark_id`: The benchmark being used
- `created_at`: Timestamp when evaluation was created
- `message`: Confirmation message

**Example Request (Single Model):**

```json
POST /api/v3/evaluations/create
Headers: {"Authorization": "Bearer <api_key>"}

{
  "model_id": "model_01kmqm4nrn9fw6r",
  "benchmark_id": "benchmark_01k4x9m2p7q3r6a1",
  "custom_metrics": ["accuracy", "relevance"]
}
```

**Example Request (Comparison Mode):**

```json
POST /api/v3/evaluations/create
Headers: {"Authorization": "Bearer <api_key>"}

{
  "model_id": "Qwen/Qwen2.5-0.5B-Instruct",
  "baseline_model_id": "model_01kmqm4nrn9fw6r",
  "benchmark_id": "benchmark_01k4x9m2p7q3r6a1"
}
```

**Example Response:**

```json
{
  "evaluation_id": "evaluation_01k4x9m2p7q3r7b1",
  "model_id": "model_01kmqm4nrn9fw6r",
  "status": "PROCESSING",
  "benchmark_id": "benchmark_01k4x9m2p7q3r6a1",
  "created_at": "2024-01-15T10:30:00Z",
  "message": "Evaluation created successfully and queued for execution"
}
```
**Notes:**

- Single model mode: Evaluates one model against the benchmark
- Comparison mode: Provide `baseline_model_id` to compare two models side-by-side
- Evaluation runs asynchronously - use the returned `evaluation_id` to check status
- Use `/evaluations/{evaluation_id}/status` to track progress



# Delete Evaluation
Source: https://docs.nugen.in/api-reference/evaluations/delete-evaluation

https://api.nugen.in/openapi-public.json delete /api/v3/evaluations/{evaluation_id}
Delete an evaluation permanently.
This endpoint permanently removes an evaluation and all its associated data. 

**Path Parameters:**

- `evaluation_id`: Unique identifier of the evaluation to delete

**Returns:**

Success response containing:

- `id`: The deleted evaluation identifier
- `message`: Confirmation message

**Raises:**

- `404`: If evaluation not found or doesn't belong to the authenticated user

**Example Request:**

```json
DELETE /api/v3/evaluations/evaluation_01k4x9m2p7q3r7b1
Headers: {"Authorization": "Bearer <api_key>"}
```

**Example Response:**

```json
{
  "evaluation_id": "evaluation_01k4x9m2p7q3r7b1",
  "message": "Successfully deleted evaluation"
}
```
**Warning:**

This action is permanent and cannot be undone. All evaluation results, metrics, and associated data will be permanently deleted.



# Get Evaluation
Source: https://docs.nugen.in/api-reference/evaluations/get-evaluation

https://api.nugen.in/openapi-public.json get /api/v3/evaluations/{evaluation_id}
Get one evaluation by ID.

**Returns:**

- `evaluation_id`, `status` (`QUEUED`, `PROCESSING`, `READY`, `FAILED`)
- `model_id`, `benchmark_id`, `progress`
- `n_samples_completed`, `n_samples`, `avg_time_per_sample`, `eta_seconds`
- `created_at`, `completed_at`, `updated_at`



# Get Evaluation Results
Source: https://docs.nugen.in/api-reference/evaluations/get-evaluation-results

https://api.nugen.in/openapi-public.json get /api/v3/evaluations/{evaluation_id}/results
Retrieve the complete results of a finished evaluation.

This endpoint returns detailed evaluation metrics and scores for a completed evaluation. Works for both single model evaluations and comparison mode evaluations.

**Path Parameters:**

- `evaluation_id`: Unique evaluation identifier

**Returns:**

- `evaluation_id`: The evaluation identifier
- `raw_responses_count`: Number of raw responses generated during evaluation
- `method` (optional): Evaluation method (`eval` for single model, `eval-compare` for comparison)
- `metrics` (optional): Evaluation metrics and scores (single model only)
- `baseline_model_id` (optional): Baseline model ID (comparison mode only)
- `model` (optional): Aligned model results (comparison mode only)
- `baseline` (optional): Baseline model results (comparison mode only)
- `comparison` (optional): Comparison results between models (comparison mode only)

Identity, status, and timestamps are served by `GET /{evaluation_id}`.

**Raises:**

- `404`: If evaluation not found or doesn't belong to the authenticated user
- `400`: If evaluation is not yet completed, or FAILED with no results

**Example Request:**

```json
GET /api/v3/evaluations/evaluation_01k4x9m2p7q3r7b1/results
Headers: {"Authorization": "Bearer <api_key>"}
```

**Example Response (Single Model):**

```json
{
  "evaluation_id": "evaluation_01k4x9m2p7q3r7b1",
  "method": "eval",
  "raw_responses_count": 10,
  "metrics": {
    "accuracy": 0.92,
    "relevance": 0.88,
    "average_score": 0.90,
    "n_samples": 10,
    "correct_answers": 9
  }
}
```

**Example Response (Comparison Mode):**

```json
{
  "evaluation_id": "evaluation_01k4x9m2p7q3r7b1",
  "baseline_model_id": "model_01kmqm4nrn9fw6r",
  "method": "eval-compare",
  "raw_responses_count": 20,
  "model": {
    "model_id": "model_01kmqm4nrn9fw6r",
    "average_score": 0.92,
    "n_samples": 10
  },
  "baseline": {
    "model_id": "Qwen/Qwen2.5-0.5B-Instruct",
    "average_score": 0.85,
    "n_samples": 10
  },
  "comparison": {
    "winner": "Qwen/Qwen2.5-0.5B-Instruct",
    "score_difference": 0.07,
    "statistical_significance": true
  }
}
```



# Get Evaluation Status
Source: https://docs.nugen.in/api-reference/evaluations/get-evaluation-status

https://api.nugen.in/openapi-public.json get /api/v3/evaluations/{evaluation_id}/status
Get the current status of an evaluation.

This endpoint retrieves the status of a running or completed evaluation. Use this to determine when results are ready; fetch the full record once from `GET /evaluations/{evaluation_id}`.

**Path Parameters:**

- `evaluation_id`: Unique evaluation identifier

**Returns:**

- `evaluation_id`: The evaluation identifier
- `status`: Current status (`QUEUED`, `PROCESSING`, `READY`, `FAILED`)
- `created_at`, `completed_at`, `updated_at`: timestamps
- `progress`, `eta_seconds`: not wired up yet, always null
- `status_message`: what the evaluation is waiting for, e.g. a free deployment slot
- `error`: why the evaluation failed, set only when status is `FAILED`

**Raises:**

- `404`: If evaluation not found or doesn't belong to the authenticated user

**Example Request:**

```json
GET /api/v3/evaluations/evaluation_01k4x9m2p7q3r7b1/status
Headers: {"Authorization": "Bearer <api_key>"}
```

**Example Response:**

```json
{
  "evaluation_id": "evaluation_01k4x9m2p7q3r7b1",
  "status": "READY",
  "created_at": "2024-02-24T10:00:00Z",
  "completed_at": "2024-02-24T10:05:00Z",
  "updated_at": "2024-02-24T10:05:00Z",
  "progress": null,
  "eta_seconds": null
}
```

**Notes:**

- Once status is `READY`, use `/evaluations/{evaluation_id}/results` to get full results
- Status `FAILED` indicates an error occurred during evaluation



# List User Evaluations
Source: https://docs.nugen.in/api-reference/evaluations/list-user-evaluations

https://api.nugen.in/openapi-public.json get /api/v3/evaluations/list
Retrieve all evaluations for the authenticated user.

This endpoint returns a paginated list of lean evaluation rows. Fetch `GET /evaluations/{evaluation_id}` for the full record and `/results` for scores.

**Query Parameters:**

- `status` (optional): Filter by evaluation status (`QUEUED`, `PROCESSING`, `READY`, `FAILED`)
- `model_id` (optional): Filter by specific model ID
- `limit` (optional): Number of evaluations to return (1-100, default: 10)
- `offset` (optional): Number of evaluations to skip for pagination (default: 0)

**Returns:**

- `user_id`: The authenticated user's ID
- `evaluations`: List of `evaluation_id`, `evaluation_name`, `status`, `created_at`
- `total`: Total number of evaluations matching the filters
- `limit`: Requested page size
- `offset`: Current pagination offset

**Example Request:**

```json
GET /api/v3/evaluations/list?status=READY&limit=5&offset=0
Headers: {"Authorization": "Bearer <api_key>"}
```

**Example Response:**

```json
{
  "user_id": "01KKBERWEEM634BQW9BK6Y0Y",
  "evaluations": [
    {
      "evaluation_id": "eval_01KKJHBNFY9STH1C9",
      "evaluation_name": "Clause Review v2 Eval",
      "status": "READY",
      "created_at": "2026-03-10T10:43:12.826791",
      "alignment_id": "alignment_01k4x9m2p7q3r8c1"
    }
  ],
  "total": 1,
  "limit": 10,
  "offset": 0
}
```



# Generate Chat Completions
Source: https://docs.nugen.in/api-reference/inference/generate-chat-completions

https://api.nugen.in/openapi-public.json post /api/v3/inference/chat/completions
Generate conversational responses with streaming support and multimodal capabilities.


This endpoint generates chat completions using language models, supporting both text-only conversations and vision inputs. Includes support for function calling, streaming responses, and automatic conversation tracking.


**Request Body:**

- `model`: Model ID (required). Use your aligned model id (e.g. `model_01kmqm4nrn9fw6r`); base text models (e.g. `model_01kmqm4nrn9fw6r`) also work if you have not aligned a model yet. For reserved capacity pass `ptm_id:model_id`
- `messages`: Array of message objects (required, minimum 1), each containing:
  - `role`: Message role (`system`, `user`, or `assistant`)
  - `content`: Text string OR array of content objects (for multimodal)
    - Text: `{"type": "text", "text": "your message"}`
    - Image URL: `{"type": "image_url", "image_url": {"url": "https://..."}}`
    - Image Base64: `{"type": "image_url", "image_url": {"url": "data:image/jpeg;base64,..."}}`
  - `name` (optional): Author name (a-z, A-Z, 0-9, underscores, max 64 chars)
- `max_tokens` (optional): Maximum tokens to generate in completion
- `prompt_truncate_len` (optional): Size to truncate chat prompts (default: 1500)
- `temperature` (optional): Sampling temperature between 0 and 2 (default: 1)
- `stream` (optional): Enable streaming responses (default: `false`)
  > **Tip:** For prompts where you expect a long output (e.g., `max_tokens > 500`), prefer `stream: true` over `stream: false` to avoid HTTP 504 gateway timeouts on slow or large responses.
- `tools` (optional): List of tools/functions available to the model
- `tool_choice` (optional): Tool selection mode (`auto`, `none`, or specific tool)
- `top_p` (optional): Nucleus sampling parameter
- `top_k` (optional): Top-k sampling parameter
- `n` (optional): Number of completions to generate (default: 1)
- `reasoning` (optional): Reasoning configuration object with:
  - `effort`: Reasoning effort level (`xhigh`, `high`, `medium`, `low`, `minimal`, `none`)
  - `max_tokens`: Token limit for reasoning
  - `exclude`: Set true to exclude reasoning tokens from response
  - `enabled`: Enable reasoning with default parameters


**Optional Headers:**

- `X-Session-ID`: Session identifier for multi-turn conversation tracking


**Returns:**

**Non-streaming mode** -
- `id`: Unique identifier for the response
- `object`: Object type (always `chat.completion`)
- `created`: Unix timestamp when completion was created
- `model`: Model used for chat completion
- `choices`: List of completion choices, each containing:
  - `index`: Index of the choice
  - `message`: Response message with:
    - `role`: Role of the author (always `assistant`)
    - `content`: Generated response text
    - `tool_calls` (optional): Tool calls made by the model (for function calling)
  - `finish_reason`: Reason model stopped (`stop` for natural stop, `length` if max tokens reached)
- `usage`: Token usage statistics:
  - `prompt_tokens`: Number of tokens in the prompt
  - `completion_tokens`: Number of tokens generated
  - `total_tokens`: Total tokens used (prompt + completion)
- `confidence_score` (optional): Confidence score, 0-100, on aligned models; null on base models

**Streaming mode** - `ChatCompletionChunk` stream with:
- `id`: Unique identifier
- `created`: Timestamp
- `model`: Model ID
- `choices`: List of chunk choices with:
  - `index`: Choice index
  - `delta`: Delta content with `role` and `content`
  - `finish_reason`: Reason for stopping (only in final chunk)
- `usage` (optional): Only present in final chunk


**Example Request (Text Chat):**

```json
POST /api/v3/inference/chat/completions
Headers: {"Authorization": "Bearer <api_key>"}

{
  "model": "model_01kmqm4nrn9fw6r",
  "messages": [
    {
      "role": "system",
      "content": "You are a helpful assistant."
    },
    {
      "role": "user",
      "content": "What is the capital of France?"
    }
  ],
  "max_tokens": 500,
  "temperature": 0.7
}
```


**Example Response (Text Chat):**

```json
{
  "id": "nugen-abc123",
  "object": "chat.completion",
  "created": 1704123600.0,
  "model": "model_01kmqm4nrn9fw6r",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "The capital of France is Paris."
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 20,
    "completion_tokens": 8,
    "total_tokens": 28
  },
  "confidence_score": 89.5454
}
```


**Example Request (Using Domain-Aligned Model):**

```json
POST /api/v3/inference/chat/completions
Headers: {"Authorization": "Bearer <api_key>"}

{
  "model": "model_01kmqm4nrn9fw6r",
  "messages": [
    {
      "role": "user",
      "content": "How do I return a product?"
    }
  ],
  "max_tokens": 500,
  "temperature": 0.7
}
```


**Example Response (Domain-Aligned Model):**

```json
{
  "id": "nugen-abc456",
  "object": "chat.completion",
  "created": 1704123700.0,
  "model": "model_01kmqm4nrn9fw6r",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "To return a product, please visit our returns portal within 30 days of purchase with your order number and receipt."
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 15,
    "completion_tokens": 25,
    "total_tokens": 40
  },
  "confidence_score": 95.8
}
```

**How to get your aligned model ID:**
1. Create an alignment project using `POST /api/v3/alignment-projects/create`
2. Poll `GET /api/v3/alignment-projects/{id}/status` until status is `COMPLETED`
3. Use the `model_id` field from the response (e.g., `"model_01kmqm4nrn9fw6r"`)
4. Deploy the model using `POST /api/v3/models/{model_id}/deployment` (optional - for evaluation/production use)
5. Use the `model_id` in the `model` parameter for inference requests


**Example Request (Vision - Image URL):**

```json
POST /api/v3/inference/chat/completions
Headers: {"Authorization": "Bearer <api_key>"}

{
  "model": "model_01kmqm4nrn9fw6r",
  "messages": [
    {
      "role": "user",
      "content": [
        {
          "type": "text",
          "text": "Describe what you see in this image."
        },
        {
          "type": "image_url",
          "image_url": {
            "url": "https://example.com/image.jpg"
          }
        }
      ]
    }
  ],
  "max_tokens": 1000
}
```


**Example Request (Vision - Base64 Image):**

```json
POST /api/v3/inference/chat/completions
Headers: {"Authorization": "Bearer <api_key>"}

{
  "model": "model_01kmqm4nrn9fw6r",
  "messages": [
    {
      "role": "user",
      "content": [
        {
          "type": "text",
          "text": "What's in this image?"
        },
        {
          "type": "image_url",
          "image_url": {
            "url": "data:image/jpeg;base64,/9j/4AAQSkZJRgABAQEAYABgAAD..."
          }
        }
      ]
    }
  ]
}
```


**Example Request (Function Calling):**

```json
POST /api/v3/inference/chat/completions
Headers: {"Authorization": "Bearer <api_key>"}

{
  "model": "model_01kmqm4nrn9fw6r",
  "messages": [
    {"role": "user", "content": "What is the status of INC-4821?"}
  ],
  "tools": [
    {
      "type": "function",
      "function": {
        "name": "get_incident",
        "description": "Get incident status",
        "parameters": {
          "type": "object",
          "properties": {
            "incident_id": {"type": "string"}
          }
        }
      }
    }
  ],
  "tool_choice": "auto"
}
```


**Example Request (Streaming):**

```json
POST /api/v3/inference/chat/completions
Headers: {"Authorization": "Bearer <api_key>"}

{
  "model": "model_01kmqm4nrn9fw6r",
  "messages": [{"role": "user", "content": "Tell me a story"}],
  "stream": true
}
```


**Example Response (Streaming):**

```
data: {"id":"nugen-abc123","created":1704123600.0,"model":"model_01kmqm4nrn9fw6r","choices":[{"index":0,"delta":{"role":"assistant","content":"Once"},"finish_reason":null}]}

data: {"id":"nugen-abc123","created":1704123600.0,"model":"model_01kmqm4nrn9fw6r","choices":[{"index":0,"delta":{"content":" upon"},"finish_reason":null}]}

data: {"id":"nugen-abc123","created":1704123600.0,"model":"model_01kmqm4nrn9fw6r","choices":[{"index":0,"delta":{"content":" a time"},"finish_reason":"stop"}],"usage":{"prompt_tokens":10,"completion_tokens":5,"total_tokens":15}}

data: [DONE]
```


**Provisioned throughput:**

Reserve inference capacity for production workloads. Pass your provisioned id in `model` as `ptm_id:model_id` in place of the plain `model_id`. The request and response surface is identical, so your application code stays as it is once capacity is reserved. Available for aligned models on the Enterprise Edition.

**Notes:**

- Supports both text-only and vision/multimodal inputs depending on the model
- **Using Domain-Aligned Models**: Pass the `model_id` from your completed alignment project as the `model` parameter. Get your aligned model IDs from `GET /api/v3/alignment-projects/{id}/status` or `GET /api/v3/models/aligned`
- Function calling enables models to invoke external tools via `tools` and `tool_choice` parameters
- `confidence_score` (0-100) comes from inference-time alignment: uncertainty is quantified across the generation trajectory, flagging any drift from your domain. Available on aligned models only; always null for base models. In streaming mode, confidence arrives as its own `{"object": "confidence", ...}` events interleaved with content chunks, one per generated span, rather than a single value on the final chunk
- For streaming, usage statistics are included only in the final chunk
- Conversations are automatically saved to S3 if enabled in user settings
- Include `X-Session-ID` header for multi-turn conversation tracking
- Use `prompt_truncate_len` to control context window usage for long conversations
- The `reasoning` parameter enables advanced reasoning capabilities for supported models



# Generate Embeddings
Source: https://docs.nugen.in/api-reference/inference/generate-embeddings

https://api.nugen.in/openapi-public.json post /api/v3/inference/embeddings
Generate dense vector embeddings for input text.


This endpoint creates numerical vector representations (embeddings) of text using specified embedding models. Embeddings are useful for semantic search, clustering, similarity comparisons, and RAG applications.


**Request Body:**

- `model`: Model ID (required). Use your aligned model id (e.g. `model_01kmqm4nrn9fw6r`)
- `input`: Text or list of texts to embed (required) - Single string or array of strings. Cannot be empty and must not exceed max input tokens for the model
- `dimensions` (optional): Number of dimensions for output embeddings (only applicable for Resizable Matryoshka Embedding models)


**Returns:**

- `id`: Unique identifier for the response
- `object`: Object type (always `embedding`)
- `data`: List of embedding objects, each containing:
  - `object`: Object type (always `embedding`)
  - `embedding`: Vector of floats representing the text (length depends on the model)
  - `index`: Position in the input array
- `model`: Model ID used for generation
- `created`: Unix timestamp (seconds) when response was generated
- `usage`: Token usage statistics containing:
  - `total_tokens`: Total number of tokens used by the request


**Example Request (Single Text):**

```json
POST /api/v3/inference/embeddings
Headers: {"Authorization": "Bearer <api_key>"}

{
  "model": "text-embedding-xyz",
  "input": "The quick brown fox jumps over the lazy dog"
}
```


**Example Request (Multiple Texts):**

```json
POST /api/v3/inference/embeddings
Headers: {"Authorization": "Bearer <api_key>"}

{
  "model": "model_01kmqm4nrn9fw6r",
  "input": [
    "First document for semantic search",
    "Second document for clustering",
    "Third document for similarity comparison"
  ]
}
```


**Example Request (With Dimensions):**

```json
POST /api/v3/inference/embeddings
Headers: {"Authorization": "Bearer <api_key>"}

{
  "model": "model_01kmqm4nrn9fw6r",
  "input": "Sample text to embed",
  "dimensions": 512
}
```


**Example Response:**

```json
{
  "id": "embed-abc123xyz",
  "object": "embedding",
  "data": [
    {
      "object": "embedding",
      "embedding": [0.00658765, -0.008665467, -0.007653789, 0.0023, -0.0091, 0.0125],
      "index": 0
    }
  ],
  "model": "text-embedding-ada-002",
  "created": 1705329600.0,
  "usage": {
    "total_tokens": 10
  }
}
```


**Notes:**

- Input must not exceed the maximum input tokens supported by the model
- Input cannot be an empty string
- For batch processing, pass multiple texts as an array to the `input` field
- The embedding vector length varies by model - check model documentation for specifics
- Use `dimensions` parameter only with Matryoshka embedding models that support resizing



# Inference Settings
Source: https://docs.nugen.in/api-reference/inference/inference-settings

https://api.nugen.in/openapi-public.json get /api/v3/inference/capture
Read the capture settings for your organisation.
Whether Nugen keeps the instructions you send and the responses your aligned models return.

**By default, the capture is off for every organisation until you turn it on**, and it covers aligned models only. Base model traffic is never kept, and a base model id is rejected by this endpoint.

Kept pairs become training data for `POST /api/v3/alignment-projects/{alignment_id}/auto-align`, so a model that gets used improves from that use. Turning capture off stops collection from the next request onwards and leaves already kept pairs in place.

**Returns:**

- `enabled`: your organisation's default
- `models`: aligned models that differ from that default, keyed by model id



# OpenAI-compatible Responses
Source: https://docs.nugen.in/api-reference/inference/openai-compatible-responses

https://api.nugen.in/openapi-public.json post /api/v3/inference/responses
OpenAI `responses.create` compatible endpoint.

Accepts the same shape as `openai.responses.create` and returns a `Response` object.


**Request Body:**

- `model`: Model ID (required)
- `input`: User input a plain string or array of `{"role": ..., "content": ...}` dicts
- `instructions` (optional): System-level instructions
- `max_output_tokens` (optional): Maximum tokens to generate
- `temperature` (optional): Sampling temperature 0–2 (default: 1.0)
- `top_p` (optional): Nucleus sampling parameter
- `stream` (optional): Stream partial output as SSE (default: false)

**Example Request:**

```json
POST /api/v3/inference/responses
Headers: {"Authorization": "Bearer <api_key>"}

{
  "model": "Qwen/Qwen2.5-0.5B-Instruct",
  "input": "What is the capital of France?",
  "instructions": "You are a helpful assistant.",
  "max_output_tokens": 200
}
```

**Example Response:**

```json
{
  "id": "resp_abc123",
  "object": "response",
  "created_at": 1704123600,
  "model": "Qwen/Qwen2.5-0.5B-Instruct",
  "output": [
    {
      "type": "message",
      "role": "assistant",
      "content": [{"type": "output_text", "text": "The capital of France is Paris."}]
    }
  ],
  "usage": {"input_tokens": 18, "output_tokens": 9, "total_tokens": 27}
}
```



# Rerank Documents
Source: https://docs.nugen.in/api-reference/inference/rerank-documents

https://api.nugen.in/openapi-public.json post /api/v3/inference/reranker
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 <api_key>"}

{
  "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 <api_key>"}

{
  "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



# Create Alignment
Source: https://docs.nugen.in/api-reference/model-alignment/create-alignment

https://api.nugen.in/openapi-public.json post /api/v3/alignment-projects/create
Create a new domain alignment workflow.


This endpoint initiates a domain alignment workflow that aligns a base model to your domain corpus using provided documents.


**Request Body:**

- `alignment_name`: Name of the domain alignment project
- `base_model_id`: Base model to use for alignment (e.g., `Qwen/Qwen2.5-0.5B-Instruct`)
- `document_ids`: List of document IDs the synthetic training dataset is generated from. Documents are snapshotted when the project is created; later edits to documents never change an existing alignment
- `workflow_id` (optional): Custom workflow identifier
- `benchmark_id` (optional, recommended): When passed, your aligned model is evaluated automatically against this benchmark. Skip it to evaluate later with `POST /evaluations/create`, or not at all. The evaluation needs a free deployment slot; if all 10 of your organisation's are in use it waits up to 3 hours, `message` in this response warns when that is already the case, and the status endpoint shows it as `evaluation_message`
- `description` (optional): Description of the alignment project


**Advanced control:**

This endpoint plans the alignment for you. To steer it with your own estimates, use `POST /alignment-projects/{alignment_id}/auto-align`: set a target score and compute budget, and optionally a `config` covering reinforcement learning or supervised (SFT) settings such as loss, LoRA rank, learning rate, gradient clipping, batch size, steps and sampling.


**Importing models:**

Any Hugging Face model can be imported by passing `"base_model_id": "hf://<model-name>"`. For security reasons, models that require custom code execution are unsupported by default; raise a support ticket to discuss your case.


**Returns:**

- `alignment_id`: Unique alignment identifier for tracking workflow progress
- `status`: Initial workflow status (always `PROCESSING`)


**Raises:**

- `400`: If the base model does not support alignment
- `404`: If document IDs are not found or don't belong to user
- `409`: If your organisation already has 10 alignment projects; delete one first


**Example Request:**

```json
POST /api/v3/alignment-projects/create
Headers: {"Authorization": "Bearer <api_key>"}

{
  "alignment_name": "Contract Risk Domain Alignment",
  "base_model_id": "Qwen/Qwen2.5-0.5B-Instruct",
  "document_ids": ["document_01k4x9m2p7q3r5se", "document_01k4x9m2p7q3r5sf", "document_01k4x9m2p7q3r5sg"],
  "benchmark_id": "benchmark_01k4x9m2p7q3r6a1",
  "description": "Alignment for master services agreements and addenda"
}
```


**Example Response:**

```json
{
  "alignment_id":"alignment_01k4x9m2p7q3r8c1",
  "status": "PROCESSING"
}
```


**Notes:**

- Use `/alignment-projects/{id}/status` to track workflow progress
- If `benchmark_id` is provided, an evaluation is created once train-time alignment finishes. The alignment is READY at that point; follow the evaluation at `GET /evaluations/{evaluation_id}`
- Only models that support alignment can be used.



# Delete Alignment
Source: https://docs.nugen.in/api-reference/model-alignment/delete-alignment

https://api.nugen.in/openapi-public.json delete /api/v3/alignment-projects/{alignment_id}
Delete an alignment project permanently.


This endpoint permanently removes an alignment project and its associated data from the system. The aligned model must be undeployed before deletion is allowed.


**Path Parameters:**

- `alignment_id`: Unique identifier of the alignment project to delete


**Returns:**

Success response containing:

- `alignment_id`: ID of the deleted alignment project
- `message`: Confirmation message


**Raises:**

- `400`: If the aligned model is still deployed (must undeploy first)
- `404`: If alignment project not found or doesn't belong to user


**Example Request:**

```json
DELETE /api/v3/alignment/alignment_01k4x9m2p7q3r8c1
Headers: {"Authorization": "Bearer <api_key>"}
```


**Example Response:**

```json
{
  "alignment_id": "alignment_01k4x9m2p7q3r8c1",
  "message": "Alignment project successfully deleted"
}
```


**Warning:**

This action is permanent and cannot be undone. All alignment data, train-time alignment artifacts, and project metadata will be permanently deleted.


**Important:**

Before deleting an alignment project, ensure the associated aligned model is undeployed. Use the undeploy endpoint first if the model is currently deployed.



# Get Alignment Project
Source: https://docs.nugen.in/api-reference/model-alignment/get-alignment-project

https://api.nugen.in/openapi-public.json get /api/v3/alignment-projects/{alignment_id}
Retrieve detailed information about a specific alignment project.


This endpoint fetches comprehensive details about an alignment project including metadata, associated documents, train-time alignment progress, status, performance metrics, and evaluation information.


**Path Parameters:**

- `alignment_id`: Unique identifier of the alignment project


**Returns:**

- `alignment_id`: Alignment project identifier
- `alignment_name`: Project name
- `base_model_id`: Base model identifier used for alignment
- `status`: Project status (`PENDING`, `COMPLETED`, `FAILED`)
- `queue_position`, `stop_requested_at`, `early_deployable`: run qualifiers, same as the status endpoint
- `created_at`: ISO timestamp when project was created
- `completed_at` (optional): ISO timestamp when project completed
- `updated_at`: Last update timestamp
- `eta_seconds` (optional): not wired up yet, always null
- `document_ids`: List of document IDs the synthetic training dataset was generated from
- `document_count`: Number of documents used
- `creator`: Username or ID of the project creator
- `performance_metrics` (optional): Train-time alignment metrics (loss, accuracy, etc.)
- `progress` (optional): Train-time alignment progress percentage (0-100)
- `estimated_completion` (optional): Estimated completion time
- `error` (optional): Error message if project failed
- `degraded` (optional): True when the run reached READY but a stage failed on the way
- `stage_failures` (optional): Stage failures on the way, if any
- `evaluation_id` (optional): Auto-evaluation ID if triggered
- `model_id` (optional): Deployed model ID for evaluation


**Raises:**

- `404`: If alignment project not found or doesn't belong to user


**Example Request:**

```json
GET /api/v3/alignment/alignment_01k4x9m2p7q3r8c1
Headers: {"Authorization": "Bearer <api_key>"}
```


**Example Response (Completed):**

```json
{
  "alignment_id":"alignment_01k4x9m2p7q3r8c1",
  "alignment_name": "Contract Risk Domain Alignment",
  "base_model_id": "Qwen/Qwen2.5-0.5B-Instruct",
  "status": "READY",
  "created_at": "2024-01-15T10:30:00Z",
  "completed_at": "2024-01-15T14:45:00Z",
  "document_ids": ["document_01k4x9m2p7q3r5s8", "document_01k4x9m2p7q3r5sc", "document_01k4x9m2p7q3r5sd"],
  "document_count": 3,
  "creator": "user-123",
  "performance_metrics": {
    "final_loss": 0.15,
    "accuracy": 0.92,
    "perplexity": 2.3
  },
  "evaluation_id": "evaluation_01k4x9m2p7q3r7b1",
  "model_id": "alignment_01k4x9m2p7q3r8c1-deployed"
}
```


**Example Response (In Progress):**

```json
{
  "alignment_id":"alignment_01k4x9m2p7q3r8c2",
  "alignment_name": "Technical Documentation Alignment",
  "base_model_id": "Qwen/Qwen2.5-0.5B-Instruct",
  "status": "PROCESSING",
  "created_at": "2024-01-16T09:00:00Z",
  "document_ids": ["document_01k4x9m2p7q3r5sh", "document_01k4x9m2p7q3r5sj"],
  "document_count": 2,
  "creator": "user-123",
  "progress": 45,
  "estimated_completion": "2024-01-16T11:30:00Z"
}
```


**Notes:**

- Returns full project details including train-time alignment progress and performance
- `model_id` is only available for projects that have been deployed for evaluation
- `evaluation_id` is the evaluation created from `benchmark_id`, present once train-time alignment finishes
- `performance_metrics` are populated after train-time alignment completes
- `progress` and `estimated_completion` are available during train-time alignment
- `error` field contains failure details if status is `FAILED`



# Get Alignment Status
Source: https://docs.nugen.in/api-reference/model-alignment/get-alignment-status

https://api.nugen.in/openapi-public.json get /api/v3/alignment-projects/{alignment_id}/status
The polled status of one alignment project.

Returns the state and its qualifiers only. Configuration, documents,
metrics, and failure qualifiers (degraded, stage_failures, error) never
change while a run executes or live on the detail route instead, so they
are not re-sent on every poll.



# List Alignment Projects
Source: https://docs.nugen.in/api-reference/model-alignment/list-alignment-projects

https://api.nugen.in/openapi-public.json get /api/v3/alignment-projects/list
List the caller's alignment projects as summary rows.

A list view renders an identifier, a name, a state and a timestamp, so that
is what this returns. The full record, documents, metrics and evaluation
details live on `GET /alignment-projects/{id}`.

**Query Parameters:**

- `status` (optional): Filter by alignment project status
- `limit` (optional): Number of alignment projects to return (1-100, default: 10)

Each row carries `model_id`, the aligned model the project produced, once it is READY.
- `offset` (optional): Number of alignment projects to skip for pagination (default: 0)



# Start Auto-Align
Source: https://docs.nugen.in/api-reference/model-alignment/start-auto-align

https://api.nugen.in/openapi-public.json post /api/v3/alignment-projects/{alignment_id}/auto-align
Submit a target alignment score and let the system plan the run.

The system analyses your data, base model and prior train-time alignment history to build a
multi-phase alignment plan.

Phases are sequenced and executed continuously. The system may apply
gradient-free representation adjustments, supervised learning, reward-guided
optimisation, or a combination, re-planning when the score trajectory demands
it. Checkpoints are evaluated between phases, and the system revisits earlier
phases if regressions surface.

Every parameter defaults to `auto`. You can override any of them to constrain
the search, and the system performs best when given room to explore.


**Path Parameters:**

- `alignment_id`: The alignment project to auto-align. Its base model, data and
  prior train-time alignment history warm-start the planning.


**Request Body:**

- `target_score` (required): Target quality on a 0-99 scale
- `benchmark_id` (optional): Benchmark that measures the achieved score against
  the target. Defaults to the benchmark already on the project
- `method`, `representations`, `sequencing` (optional): Constrain which
  optimisation families run and in what order
- `max_compute_hours` (optional): Upper bound on GPU hours across all phases
- `notify_on_phase_transition` (optional): Notify on each phase change
- `config` (optional): Take control of any part of the run, for reinforcement
  learning or supervised (SFT) settings: loss, optimizer, LoRA adapter, reward,
  advantage, reference policy, environment, dataset, sampling, training,
  checkpointing, evaluation, rendering and logging. Pass only what you want to
  pin; anything omitted stays auto and redundant settings are discarded. Every
  field is listed in the `AutoAlignConfig` schema, with a full example


**Returns:**

- `auto_align_id`: Identifier of this request
- `alignment_id`: The project it targets
- `status`, `message`


**Raises:**

- `404`: If the alignment project is not found or does not belong to you


**Notes:**

- Auto-alignment is an Enterprise Edition capability. The request is recorded
  and our team follows up; raise a support ticket to enable it
- Once enabled, poll `GET /alignment-projects/{alignment_id}/status` for
  progress, phase transitions and intermediate scores



# Stop Alignment
Source: https://docs.nugen.in/api-reference/model-alignment/stop-alignment

https://api.nugen.in/openapi-public.json post /api/v3/alignment-projects/{alignment_id}/stop
Stop an in-progress train-time alignment.

**Path Parameters:**
- `alignment_id`: Alignment project identifier

**Returns:**
- `alignment_id`: ID of the stopped alignment project
- `status`: New status

**Raises:**
- `400`: If the alignment is already in a terminal state or has not started train-time alignment yet
- `404`: If the alignment project is not found or does not belong to the user
- `502`: If the train GPU server rejected the stop request
- `503`: If the train GPU server is unreachable



# Deploy Aligned Model
Source: https://docs.nugen.in/api-reference/models/deploy-aligned-model

https://api.nugen.in/openapi-public.json post /api/v3/models/{model_id}/deployment
Deploy an aligned model for inference use.


This endpoint deploys a domain-aligned model, making it available for inference.


**Path Parameters:**

- `model_id`: Unique identifier of the aligned model to deploy


**Returns:**

- `model_id`: The aligned model being deployed


**Raises:**

- `400`: If the model is already deployed, or all 10 deployment slots of your organisation are in use; undeploy a model first
- `404`: If the model or its alignment project is not found
- `409`: If the model is still in train-time alignment; pass `early=true` to deploy its newest checkpoint


**Example Request:**

```json
POST /api/v3/models/{model_id}/deployment
Headers: {"Authorization": "Bearer <api_key>"}
```


**Example Response:**

```json
{"model_id": "model_01kmqm4nrn9fw6r"}
```


**Notes:**

- Deployment is asynchronous and may take 5-15 minutes to complete
- Poll `GET /api/v3/models/{model_id}/deployment/status`; on `FAILED` the failure reason is in `result.error`
- Once deployed, the model will be available at its inference endpoint
- Model must be in `UNDEPLOYED` state before deployment



# Export to Hugging Face
Source: https://docs.nugen.in/api-reference/models/export-to-hugging-face

https://api.nugen.in/openapi-public.json post /api/v3/models/{model_id}/export-hf
Export the aligned model's weights to the given Hugging Face repository.

**Path Parameters:**

- `model_id`: Unique identifier of the aligned model

**Request Body:**

- `hf_repo` (optional): Target repository, e.g. `org/model-name`. Defaults to the
  token's own namespace plus the model id.
- `visibility`: `private` or `public`
- `token`: Hugging Face access token

Runs in the background. Poll `GET /models/{model_id}/export-hf/status`
for progress.



# Get Deployment Status
Source: https://docs.nugen.in/api-reference/models/get-deployment-status

https://api.nugen.in/openapi-public.json get /api/v3/models/{model_id}/deployment/status
Check the deployment status of an aligned model.


This endpoint retrieves the current deployment status of a model, including progress and completion information.


**Path Parameters:**

- `model_id`: Unique identifier of the model to check deployment status for


**Returns:**

- `model_id`: The model identifier
- `status`: Deployment status
  - `UNDEPLOYED`: not serving, and deployable
  - `DEPLOYING`: a deploy is in flight
  - `DEPLOYED`: serving inference
  - `UNDEPLOYING`: an undeploy is in flight
- `error`: why the last attempt failed, null when it succeeded
- `created_at`, `completed_at`, `updated_at`: timestamps
- `progress`, `eta_seconds`: not wired up yet, always null

A failed attempt settles back to the state it came from, so read `error` alongside `status`: UNDEPLOYED with an error means the deploy failed, DEPLOYED with an error means the undeploy failed.


**Raises:**

- `404`: If model not found or doesn't belong to user


**Example Request:**

```json
GET /api/v3/models/alignment_01k4x9m2p7q3r8c1/deployment/status
Headers: {"Authorization": "Bearer <api_key>"}
```


**Example Response (deploy in flight):**

```json
{
  "model_id": "model_01kmqm4nrn9fw6r",
  "status": "DEPLOYING",
  "error": null,
  "created_at": "2024-02-24T10:00:00Z",
  "completed_at": null,
  "updated_at": "2024-02-24T10:00:00Z",
  "progress": null,
  "eta_seconds": null
}
```


**Example Response (serving):**

```json
{
  "model_id": "model_01kmqm4nrn9fw6r",
  "status": "DEPLOYED",
  "error": null,
  "created_at": "2024-02-24T10:00:00Z",
  "completed_at": "2024-02-24T10:05:00Z",
  "updated_at": "2024-02-24T10:05:00Z",
  "progress": null,
  "eta_seconds": null
}
```


**Example Response (deploy failed):**

```json
{
  "model_id": "model_01kmqm4nrn9fw6r",
  "status": "UNDEPLOYED",
  "error": "provider rejected the adapter",
  "created_at": "2024-02-24T10:00:00Z",
  "completed_at": "2024-02-24T10:02:30Z",
  "updated_at": "2024-02-24T10:02:30Z",
  "progress": null,
  "eta_seconds": null
}
```


**Notes:**

- Poll this endpoint to track deployment progress
- Only `DEPLOYED` serves inference; every other status returns 400 from the inference endpoints
- A deploy that fails settles at `UNDEPLOYED` and an undeploy that fails settles at `DEPLOYED`, both with the reason in `error`



# Get Model
Source: https://docs.nugen.in/api-reference/models/get-model

https://api.nugen.in/openapi-public.json get /api/v3/models/{model_id}
Get one aligned model by ID.

**Returns:**

- `model_id`, `model_name`, `base_model_id`, `base_model_name`, `alignment_id`
- `deployment_status` (`READY`, `DEPLOYING`, `DEPLOYED`, `UNDEPLOYING`, `FAILED`), derived from the live deployment
- `error`: why the last deploy or undeploy failed, null when it succeeded
- `progress`, `eta_seconds`: not wired up yet, always null
- `performance_metrics`, `evaluation_data`: from the model's latest evaluation, if any
- `usage_count`, `downloadable`: not wired up yet, always 0 and false
- `inference_capture_enabled`
- `created_at`, `updated_at`



# Import from Hugging Face
Source: https://docs.nugen.in/api-reference/models/import-from-hugging-face

https://api.nugen.in/openapi-public.json post /api/v3/models/base/import
Import a base model from Hugging Face or a cloud storage bucket.

**Request Body:**

- `source_type`: `huggingface`, `s3`, `gs`, `oci` or `abfss`
- `source_uri`: Hugging Face repo id or a cloud storage URI
- `base_model_name`: Name to register the imported model under
- `token`: Access token or credential for the source



# List Aligned Models
Source: https://docs.nugen.in/api-reference/models/list-aligned-models

https://api.nugen.in/openapi-public.json get /api/v3/models/aligned
Retrieve all domain-aligned models for the authenticated user.

This endpoint returns a lean list row per aligned model. Fetch `GET /models/{model_id}` for the full record: performance metrics, evaluation data, usage, downloadability and conversation settings.

**Query Parameters:**

- `deployment_status` (optional): `UNDEPLOYED`, `DEPLOYING`, `DEPLOYED` or `UNDEPLOYING`
- `base_model_id` (optional): exact base model id, e.g. `Qwen/Qwen2.5-0.5B-Instruct`
- `limit` (optional): Number of models to return (1-100, default: 10)
- `offset` (optional): Number of models to skip for pagination (default: 0)

**Returns:**
- `domain_aligned_models`: List of aligned model objects, each containing:
  - `model_id`: Unique model identifier (or `alignment-{id}` for un-deployed models)
  - `model_name`: Model name
  - `deployment_status`: `UNDEPLOYED`, `DEPLOYING`, `DEPLOYED` or `UNDEPLOYING`. Only `DEPLOYED` serves inference.
  - `base_model_id`: Base model used for alignment
  - `alignment_id`: The alignment project that produced this model
  - `created_at`: Creation timestamp


**Example Request:**

```json
GET /api/v3/models/aligned
Headers: {"Authorization": "Bearer <api_key>"}
```


**Example Response:**

```json
{
  "domain_aligned_models": [
    {
      "model_id": "model_01kmqm4nrn9fw6r",
      "model_name": "customer_support_model",
      "deployment_status": "DEPLOYED",
      "base_model_id": "Qwen/Qwen2.5-0.5B-Instruct",
      "alignment_id": "alignment_01k4x9m2p7q3r8c1",
      "created_at": "2024-01-15T10:30:00Z"
    }
  ]
}
```


**Notes:**

- Returns both deployed and undeployed aligned models
- Use `/models/base` to see available base models for alignment



# List Base Models
Source: https://docs.nugen.in/api-reference/models/list-base-models

https://api.nugen.in/openapi-public.json get /api/v3/models/base
Retrieve the list of available base models.


This endpoint returns all general-purpose base models available for use in chat completions, embeddings, and domain alignment workflows.


**Query Parameters:**

- `alignment_ready` (optional): `true` or `false`
- `inference_ready` (optional): `true` or `false`
- `type` (optional): `text-generation` or `image-text-to-text`
- `limit` (optional): Number of models to return (1-100, default: 10)
- `offset` (optional): Number of models to skip for pagination (default: 0)


**Returns:**

- `models`: List of base model objects, each containing:
  - `model_id`: Unique model identifier
  - `model_name`: Human-readable model name
  - `parameters`: Model parameter count
  - `alignment_ready`: Whether model can be used as a base for domain alignment
  - `inference_ready`: Whether model is deployed for chat, completions, embeddings or rerank
  - `available_on_request`: Whether this model requires an access request before use
  - `type`: Hugging Face `pipeline_tag`, `text-generation` or `image-text-to-text`. Embedding and reranking base models are not listed; use an aligned model id for both
  - `model_card`: URL of the model card README on Hugging Face


**Example Request:**

```json
GET /api/v3/models/base
Headers: {"Authorization": "Bearer <api_key>"}
```


**Example Response:**

```json
{
  "models": [
    {
      "model_id": "Qwen/Qwen2.5-0.5B-Instruct",
      "model_name": "Qwen/Qwen2.5-0.5B-Instruct",
      "parameters": "0.49B",
      "alignment_ready": true,
      "inference_ready": true,
      "available_on_request": false,
      "type": "text-generation",
      "model_card": "https://huggingface.co/Qwen/Qwen2.5-0.5B-Instruct/blob/main/README.md"
    },
    {
      "model_id": "nomic-ai/nomic-embed-text-v1.5",
      "model_name": "nomic-ai/nomic-embed-text-v1.5",
      "parameters": "0.14B",
      "alignment_ready": false,
      "inference_ready": true,
      "available_on_request": false,
      "type": "embedding",
      "model_card": "https://huggingface.co/nomic-ai/nomic-embed-text-v1.5/blob/main/README.md"
    }
  ]
}
```
**Notes:**

- Base models are general-purpose starting points for domain alignment
- These models can be used directly or as base models for domain alignment
- Use `/models/aligned` to see your custom domain-aligned models
- `alignment_ready` indicates if the model can be used as a base for domain alignment



# Refresh Deployed Model
Source: https://docs.nugen.in/api-reference/models/refresh-deployed-model

https://api.nugen.in/openapi-public.json post /api/v3/models/{model_id}/deployment/refresh
Hot-swap the latest adapter checkpoint into an already-deployed model.

Calls the train GPU server to find the current adapter checkpoint step, then
performs an undeploy + redeploy so the inference server loads the latest weights.
The deployed model ID and inference URL remain unchanged.

**Raises 400 if:**
- Model is not in DEPLOYED state
- No adapter checkpoint is available yet (`adapter_available == false`)
- Train-time alignment failed with a zeroth checkpoint (`status == "failed"` AND `adapter_available == true`)



# Undeploy Model
Source: https://docs.nugen.in/api-reference/models/undeploy-model

https://api.nugen.in/openapi-public.json delete /api/v3/models/{model_id}/deployment
Undeploy a deployed aligned model.


This endpoint undeploys a deployed model, removing it from the inference service.


**Path Parameters:**

- `model_id`: Unique identifier of the model to undeploy


**Returns:**

- `model_id`: Identifier of the model being undeployed
- `message`: Confirmation message


**Raises:**

- `400`: If model is already undeployed
- `404`: If the model or its alignment project is not found


**Example Request:**

```json
DELETE /api/v3/models/alignment_01k4x9m2p7q3r8c1/deployment
Headers: {"Authorization": "Bearer <api_key>"}
```


**Example Response:**

```json
{"model_id": "alignment_01k4x9m2p7q3r8c1", "message": "Undeployment started for alignment_01k4x9m2p7q3r8c1."}
```


**Notes:**

- Poll `GET /api/v3/models/{model_id}/deployment/status` to track undeployment
- Once UNDEPLOYED, the model will no longer be available for inference
- The model can be redeployed later using the deploy endpoint