Overview The Xloud Block Storage API provides programmatic management of persistent storage volumes, volume snapshots, volume backups, volume types, and QoS specifications. Volumes attach to compute instances as block devices — independent of instance lifecycle.
Prerequisites
A valid project-scoped token from the Identity API
Base URL: https://api.<your-domain>/volume/v3
All operations are project-scoped unless using admin credentials
Key Endpoints Resource Method Endpoint Description List volumes GET /volumesList volumes in the current project Volume detail GET /volumes/detailList volumes with full metadata Get volume GET /volumes/{id}Get a specific volume Create volume POST /volumesCreate a new volume Extend volume POST /volumes/{id}/actionExtend volume size Delete volume DELETE /volumes/{id}Delete a volume Attach volume POST /volumes/{id}/actionReserve for attachment List snapshots GET /snapshotsList volume snapshots Create snapshot POST /snapshotsCreate a volume snapshot Delete snapshot DELETE /snapshots/{id}Delete a snapshot List backups GET /backupsList volume backups Create backup POST /backupsCreate a volume backup Restore backup POST /backups/{id}/restoreRestore backup to a volume Volume types GET /typesList available volume types QoS specs GET /qos-specsList QoS specifications (admin) Quotas GET /os-quota-sets/{project_id}Show project storage quotas
Create a Volume Display name for the volume.
Volume size in gigabytes.
Volume type name or ID. Determines the storage backend and QoS policy.
Target availability zone. Must match the compute availability zone to attach.
Clone from an existing volume by providing its ID.
Create from a snapshot by providing the snapshot ID.
Key-value metadata pairs for custom tagging.
curl -X POST https://api. < your-domai n > /volume/v3/volumes \ -H "X-Auth-Token: $OS_TOKEN " \ -H "Content-Type: application/json" \ -d '{ "volume": { "name": "db-data-01", "size": 200, "volume_type": "ssd-standard", "availability_zone": "nova", "metadata": { "environment": "production", "service": "mysql" } } }'
{ "volume" : { "id" : "c3d4e5f6-a7b8-9012-c3d4-e5f6a7b89012" , "name" : "db-data-01" , "status" : "creating" , "size" : 200 , "volume_type" : "ssd-standard" , "availability_zone" : "nova" , "metadata" : { "environment" : "production" }, "created_at" : "2026-03-18T10:00:00.000000" , "bootable" : "false" , "encrypted" : false } }
Volume Operations
Volumes are attached to instances via the Compute API. The Storage API provides the os-reserve and os-attach actions for low-level attachment management. Attach volume via Compute API (recommended)
curl -X POST https://api. < your-domai n > /compute/v2.1/servers/{server_id}/os-volume_attachments \ -H "X-Auth-Token: $OS_TOKEN " \ -H "Content-Type: application/json" \ -d '{ "volumeAttachment": { "volumeId": "<volume-id>", "device": "/dev/vdb" } }'
Detach volume from instance
curl -X DELETE \ "https://api.<your-domain>/compute/v2.1/servers/{server_id}/os-volume_attachments/{volume_id}" \ -H "X-Auth-Token: $OS_TOKEN "
Always detach a volume from the guest OS before issuing the API detach call to prevent filesystem corruption.
curl -X POST https://api. < your-domai n > /volume/v3/volumes/{id}/action \ -H "X-Auth-Token: $OS_TOKEN " \ -H "Content-Type: application/json" \ -d '{ "os-extend": { "new_size": 400 } }'
Extending a volume only expands the block device. After extension, resize the filesystem from inside the guest OS (e.g., resize2fs for ext4, xfs_growfs for XFS).
Change volume type (live migration)
curl -X POST https://api. < your-domai n > /volume/v3/volumes/{id}/action \ -H "X-Auth-Token: $OS_TOKEN " \ -H "Content-Type: application/json" \ -d '{ "os-retype": { "new_type": "archive-hdd", "migration_policy": "on-demand" } }'
Set migration_policy to on-demand to migrate data immediately, or never to only change the type metadata without data migration. curl -X POST https://api. < your-domai n > /volume/v3/volumes \ -H "X-Auth-Token: $OS_TOKEN " \ -H "Content-Type: application/json" \ -d '{ "volume": { "name": "db-data-01-clone", "size": 200, "source_volid": "<source-volume-id>" } }'
Snapshots curl -X POST https://api. < your-domai n > /volume/v3/snapshots \ -H "X-Auth-Token: $OS_TOKEN " \ -H "Content-Type: application/json" \ -d '{ "snapshot": { "name": "db-data-01-snap-20260318", "volume_id": "<volume-id>", "force": false, "metadata": { "backup_type": "daily" } } }'
Create volume from snapshot
curl -X POST https://api. < your-domai n > /volume/v3/volumes \ -H "X-Auth-Token: $OS_TOKEN " \ -H "Content-Type: application/json" \ -d '{ "volume": { "name": "db-data-restored", "snapshot_id": "<snapshot-id>", "size": 200 } }'
Set force: true in the snapshot request to snapshot a volume that is currently attached to a running instance. Ensure the filesystem is quiesced (via sync or application-level flush) before forcing a snapshot.
Backups Backups are stored in Xloud Object Storage and are independent of volume availability.
curl -X POST https://api. < your-domai n > /volume/v3/backups \ -H "X-Auth-Token: $OS_TOKEN " \ -H "Content-Type: application/json" \ -d '{ "backup": { "name": "db-data-01-backup-20260318", "volume_id": "<volume-id>", "incremental": false, "container": "volume-backups" } }'
Create incremental backup (faster, less storage)
curl -X POST https://api. < your-domai n > /volume/v3/backups \ -H "X-Auth-Token: $OS_TOKEN " \ -H "Content-Type: application/json" \ -d '{ "backup": { "name": "db-data-01-incr-20260318", "volume_id": "<volume-id>", "incremental": true } }'
Restore backup to a new volume
curl -X POST https://api. < your-domai n > /volume/v3/backups/{backup_id}/restore \ -H "X-Auth-Token: $OS_TOKEN " \ -H "Content-Type: application/json" \ -d '{ "restore": { "name": "db-data-01-restored" } }'
Volume Status Reference Status Description creatingVolume is being provisioned availableReady to attach in-useCurrently attached to an instance deletingDeletion in progress extendingSize extension in progress retypingVolume type change in progress backing-upBackup in progress restoring-backupBackup restore in progress errorAn error occurred — check volume events error_deletingDeletion failed
Next Steps Compute API Attach volumes to compute instances via the Compute API
Networking API Configure networks for your storage-backed instances
Storage QoS Configure IOPS and throughput limits for volume types
Automation Automate backup workflows with scripts and scheduling
