---
title: "Create Alignment"
method: POST
path: "/api/v3/alignment-projects/create"
tags: ["Alignment Projects"]
---

# Create Alignment

`POST /api/v3/alignment-projects/create`

## Request

- Base URL: `https://api.nugen.in`
- URL: `https://api.nugen.in/api/v3/alignment-projects/create`
- Auth: HTTP bearer

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.
- `description` (optional): Description of the alignment project


**More control:**

This endpoint plans the alignment for you. If you want a say in how it runs, send your best estimates to `POST /api/v3/alignment-projects/{alignment_id}/auto-align`: a target score, a compute budget, and any settings you already have a view on, such as the policy objective (PPO, CISPO or DRO), the advantage estimator, the reward source, the reference-policy KL target or the rollout group size. Rough estimates are enough to start. Anything you leave out, the system plans for you.


**Importing models:**

The examples use small Qwen models, and the same call works for almost any open language model on Hugging Face, including families such as Llama, Qwen, Phi, Mistral and DeepSeek, and new releases as they appear. `GET /api/v3/models/base` lists the base models you can align right now. To use another one, import it once with `POST /api/v3/models/base/import`, then pass its Hugging Face id as `base_model_id`. 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 `QUEUED`)


**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": "QUEUED"
}
```


**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.

## Request body

- AlignmentProjectCreateRequest: Create an alignment project that fine-tunes a base model on your documents.
  - `alignment_name` string, required: Name of the domain alignment project
  - `base_model_id` string, required: Hugging Face id of the base model to align. Any model listed by GET /api/v3/models/base, or imported with POST /api/v3/models/base/import, can be used.
  - `workflow_id` string, nullable: This id is to orchestrate the entire flow
  - `benchmark_id` string, nullable: Benchmark ID for evaluation (created via /benchmarks/create or /benchmarks/upload)
  - `document_ids` string[], required: List of document IDs to train the alignment on
  - `description` string, nullable: Optional project description

## Response `200`

Returns a unique identifier for the initiated domain alignment workflow along with the initial workflow status. This endpoint starts an asynchronous alignment run over a base model to your domain corpus using provided documents and optional benchmark evaluation, allowing users to track progress and retrieve results once completed.

- AlignmentProjectCreateResponse: Response schema for alignment project creation endpoint
  - `alignment_id` string, required: Created alignment project identifier
  - `status` 'QUEUED' | 'PROCESSING' | 'READY' | 'FAILED' | 'STOPPED': Lifecycle status of a resource that runs asynchronously. Stored as is and returned as is, with no translation in between. - `QUEUED`: accepted and waiting for its workflow to start - `PROCESSING`: running - `READY`: finished successfully - `FAILED`: failed at any stage - `STOPPED`: stopped by the user before completion
  - `message` string, nullable: Additional context about the response

## 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)