> ## Documentation Index
> Fetch the complete documentation index at: https://docs.valarhq.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# LoRA adapters

> Register PEFT-trained LoRA adapters and run them on supported base models

LoRA adapters let you customize a supported base model with your own PEFT-trained weights. You upload the adapter, register it against one or more eligible base models, and Valar validates it before it becomes usable.

<Note>
  LoRA is rolling out in phases. Today you can upload, register, and manage adapters, and Valar validates them per base model. Running a registered adapter at request time is coming soon, and this page will be updated with the request syntax when it ships.
</Note>

## Entitlement

LoRA is enabled per organization. If your org is not entitled, the LoRA and file-upload endpoints return `403` with `lora entitlement required`. Contact your Valar representative to turn it on.

## Supported base models

An adapter can only target a base model that Valar has marked LoRA-eligible. Each eligible model declares a maximum adapter rank and the attention and MLP modules a LoRA may target.

| Base model               | Max rank | Target modules                                                              |
| ------------------------ | -------- | --------------------------------------------------------------------------- |
| `zai-org/GLM-5.2`        | 32       | `q_proj`, `k_proj`, `v_proj`, `o_proj`, `gate_proj`, `up_proj`, `down_proj` |
| `Qwen/Qwen3.5-397B-A17B` | 32       | same                                                                        |
| `Qwen/Qwen3.6-35B-A3B`   | 32       | same                                                                        |
| `MiniMaxAI/MiniMax-M3`   | 32       | same                                                                        |

The eligible set can change over time. Call [`GET /v1/models`](/api-reference/models-api/list-supported-models) to confirm what your key can reach, and register only against models from the list above.

## Adapter requirements

Train with [PEFT](https://huggingface.co/docs/peft) and export the two standard adapter files:

* `adapter_config.json` with `peft_type` set to `"LORA"`, `task_type` set to `"CAUSAL_LM"`, `base_model_name_or_path` matching the base model you register against, an adapter rank `r` no greater than the base model's max rank, and `target_modules` within the base model's allowed set.
* `adapter_model.safetensors` with the adapter weights.

Each file may be up to 5 GiB. The config file name must end in `.json` and the weights file name must end in `.safetensors`.

## Register an adapter

<Steps>
  <Step title="Upload the adapter files">
    Upload both files to Valar with `purpose` set to `lora`. The Files endpoint is OpenAI-compatible, so the OpenAI SDK works directly.

    ```python theme={"system"}
    from openai import OpenAI

    client = OpenAI(base_url="https://api.valarhq.ai/v1", api_key="YOUR_VALAR_KEY")

    with open("adapter_config.json", "rb") as f:
        cfg = client.files.create(file=f, purpose="lora")
    with open("adapter_model.safetensors", "rb") as f:
        wts = client.files.create(file=f, purpose="lora")
    ```

    Each upload returns a file object with an `id` you pass to the next step.
  </Step>

  <Step title="Create the LoRA">
    Register the adapter against one or more supported base models. `name` must be 2 to 64 characters, lowercase alphanumeric or dashes, start and end with an alphanumeric character, and be unique within your organization.

    ```bash theme={"system"}
    curl https://api.valarhq.ai/v1/loras \
      -H "Authorization: Bearer YOUR_VALAR_KEY" \
      -H "Content-Type: application/json" \
      -d '{
        "name": "support-tone-v1",
        "supported_models": ["zai-org/GLM-5.2"],
        "config_file_id": "file-abc123",
        "weights_file_id": "file-def456",
        "display_name": "Support tone v1",
        "description": "House support voice, trained on resolved tickets"
      }'
    ```

    The response is a LoRA object created in the `verifying` status:

    ```json theme={"system"}
    {
      "id": "lora-9f2c1a7b",
      "object": "lora",
      "name": "support-tone-v1",
      "display_name": "Support tone v1",
      "description": "House support voice, trained on resolved tickets",
      "supported_models": ["zai-org/GLM-5.2"],
      "config_file_id": "file-abc123",
      "weights_file_id": "file-def456",
      "status": "verifying",
      "created_at": 1731000000,
      "updated_at": 1731000000
    }
    ```
  </Step>
</Steps>

## Validation and status

Every adapter is reviewed before it can be used. A LoRA moves through three states:

| Status      | Meaning                                                 |
| ----------- | ------------------------------------------------------- |
| `verifying` | Registered and awaiting validation.                     |
| `deployed`  | Validated and ready.                                    |
| `failed`    | Validation failed. `status_details` carries the reason. |

## Manage adapters

List every adapter in your organization, fetch one by name or id, or delete one.

```bash theme={"system"}
# List
curl https://api.valarhq.ai/v1/loras -H "Authorization: Bearer YOUR_VALAR_KEY"

# Fetch by name or by id
curl https://api.valarhq.ai/v1/loras/support-tone-v1 -H "Authorization: Bearer YOUR_VALAR_KEY"

# Delete
curl -X DELETE https://api.valarhq.ai/v1/loras/support-tone-v1 -H "Authorization: Bearer YOUR_VALAR_KEY"
```

`GET /v1/loras` returns `{ "object": "list", "data": [ ... ] }`. A delete returns `{ "id": "...", "object": "lora.deleted", "deleted": true }`.

## Using a LoRA (coming soon)

Once an adapter is `deployed`, you will be able to run it by referencing it on a request to a supported base model. This is not yet available. When it ships, this section will document the exact request field and any completion-window constraints.