# Model Fine-Tuning API

The Model Fine-Tuning API manages training jobs, reusable tuning configurations, checkpoints,
lineage, deployment, and export.

It is available only when the Node runtime provides the required stores, queues, and Python
fine-tuning service.

## Base Path

```text
/v1/projects/:projectId/fine-tuning
```

Reads require `workspace:read` or `project:data:read`. Mutations require `models:manage`,
`project:data:write`, or `project:models:manage` according to the operation.

## Jobs

```text
GET  /v1/projects/:projectId/fine-tuning/jobs
POST /v1/projects/:projectId/fine-tuning/jobs
GET  /v1/projects/:projectId/fine-tuning/jobs/:jobId
POST /v1/projects/:projectId/fine-tuning/jobs/:jobId/cancel
```

A job requires a known base model and a non-empty `chat/v1` Dataset. Creation freezes the selected
Examples into an immutable manifest and dispatches asynchronous training.

Supported values currently include:

```text
engine: transformers
method: sft | dpo | orpo | kto
adapter: lora | qlora | full
output format: safetensors | gguf
GGUF quantization: q4_0 | q4_k_m | q4_k_s | q5_0 | q5_k_m | q6_k | q8_0 | f16 | bf16 | f32
Compressed quantization: fp8 | fp8_dynamic | fp8_static | int8
```

## Checkpoints And Lineage

```text
GET  /v1/projects/:projectId/fine-tuning/checkpoints
GET  /v1/projects/:projectId/fine-tuning/checkpoints/:checkpointId
POST /v1/projects/:projectId/fine-tuning/checkpoints/:checkpointId/deploy
GET  /v1/projects/:projectId/fine-tuning/lineage/:rootModelId
```

Deployment requires a checkpoint with a registered inference profile and an available model
runtime. The response is returned only after the service reaches `running`, fails, or times out.

## Reusable Configurations

```text
GET    /v1/projects/:projectId/fine-tuning/tuning-configs
POST   /v1/projects/:projectId/fine-tuning/tuning-configs
GET    /v1/projects/:projectId/fine-tuning/tuning-configs/:configId
PATCH  /v1/projects/:projectId/fine-tuning/tuning-configs/:configId
DELETE /v1/projects/:projectId/fine-tuning/tuning-configs/:configId
```

Configurations bind a base model, Dataset, training settings, output settings, automatic trigger,
and optional automatic deployment policy.

## Export

```text
POST /v1/projects/:projectId/fine-tuning/export
```

Exports accept a checkpoint or Hugging Face model and publish to Hugging Face Hub. Supported export
formats are `gguf`, `merged-16bit`, and `lora-adapter`. GGUF exports also require a quantization
method.

See [Model fine-tuning](../ai-models/fine-tuning.md), [Datasets](../datasets/index.md), and
[Models API](./models.md).