---
title: "Create volume"
method: POST
path: "/api/v1/volumes"
tags: ["Volumes"]
---

# Create volume

`POST /api/v1/volumes`

Create a new block storage volume. Volumes are created asynchronously — the response returns immediately with `pending` status.

Optionally attach the volume to an existing VM at create time by passing `vm_id`. Volume and VM must be in the same region.

## Filesystem

For Linux VMs, set `filesystem_type` to choose how the volume is formatted:

- `ext4` (default), `xfs`, `btrfs` — Linux filesystems
- Omit for Windows VMs — they always use NTFS

Filesystem is only applied if the volume is attached to a VM that mounts it via cloud-init or the contextualization script.

## Headers

- `X-Project-ID` string, uuid, required

## Request body

- CreateVolumeRequest
  - `name` string, required — Volume display name
  - `size` integer, required — Volume size in GB
  - `volume_type` 'nvme', required — Storage class
  - `filesystem_type` 'ext4' | 'xfs' | 'btrfs' — Filesystem to format the volume with on first attach. Linux only — Windows VMs use NTFS automatically. Defaults to `ext4`.
  - `vm_id` string, uuid — Optional. Attach the volume to this VM at create time. VM must be in the same region.
  - `region` 'us-east' — Region. Defaults to the project's default region.

## Response `202`

Volume creation accepted

- object
  - `success` boolean
  - `data` Volume
    - `id` integer, required — Volume ID. Use this in `/volumes/{id}` for get, delete, attach, detach, resize.
    - `account_id` string, uuid — Account that owns the volume
    - `project_id` string, uuid — Project the volume belongs to
    - `product_vm` string, uuid — UUID of the VM the volume is currently attached to. Empty when detached.
    - `name` string, required — Volume display name
    - `volume_type` 'nvme', required — Storage class
    - `size` integer, required — Volume size in GB
    - `status` 'creating' | 'available' | 'attached' | 'deleting' | 'failed', required — Volume lifecycle status: - `creating` — being provisioned on the hypervisor - `available` — ready, not attached to any VM - `attached` — attached to a VM (see `product_vm`) - `deleting` — being torn down - `failed` — creation or attach failed
    - `price_per_hour` string — Hourly billing rate in USD
    - `region` 'us-east'
    - `created_at` string, date-time
    - `updated_at` string, date-time

## Other responses

- `400` — Invalid request parameters
- `401` — Authentication required
- `402` — Account balance is insufficient for this operation. Top up the balance and retry.
- `403` — Billing validation failed. The account is not in good standing. Check the `reason` field: - `banned` — account suspended - `failed` — last payment failed; top up the account balance - `no_billing_customer` — billing not set up

---

[API](https://skmtc.dev/rafftechnologies/apis/raff-api.md) · [All operations](https://skmtc.dev/rafftechnologies/apis/raff-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/rafftechnologies/raff-api/revisions/2f4df56be77c/schema)