Storage API Reference

Overview

The OpenStack 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	`/volumes`	List volumes in the current project
Volume detail	GET	`/volumes/detail`	List volumes with full metadata
Get volume	GET	`/volumes/{id}`	Get a specific volume
Create volume	POST	`/volumes`	Create a new volume
Extend volume	POST	`/volumes/{id}/action`	Extend volume size
Delete volume	DELETE	`/volumes/{id}`	Delete a volume
Attach volume	POST	`/volumes/{id}/action`	Reserve for attachment
List snapshots	GET	`/snapshots`	List volume snapshots
Create snapshot	POST	`/snapshots`	Create a volume snapshot
Delete snapshot	DELETE	`/snapshots/{id}`	Delete a snapshot
List backups	GET	`/backups`	List volume backups
Create backup	POST	`/backups`	Create a volume backup
Restore backup	POST	`/backups/{id}/restore`	Restore backup to a volume
Volume types	GET	`/types`	List available volume types
QoS specs	GET	`/qos-specs`	List QoS specifications (admin)
Quotas	GET	`/os-quota-sets/{project_id}`	Show project storage quotas

Create a Volume

string

Display name for the volume.

integer

required

Volume size in gigabytes.

string

Volume type name or ID. Determines the storage backend and QoS policy.

string

Target availability zone. Must match the compute availability zone to attach.

string

Clone from an existing volume by providing its ID.

string

Create from a snapshot by providing the snapshot ID.

object

Key-value metadata pairs for custom tagging.

curl -X POST https://api.<your-domain>/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"
      }
    }
  }'

import requests

volume = {
    "volume": {
        "name": "db-data-01",
        "size": 200,
        "volume_type": "ssd-standard",
        "availability_zone": "nova",
        "metadata": {"environment": "production"}
    }
}
resp = requests.post(
    "https://api.<your-domain>/volume/v3/volumes",
    json=volume,
    headers={"X-Auth-Token": token}
)
print(resp.json()["volume"]["id"])

{
  "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

Attach / Detach
Extend
Retype
Clone

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-domain>/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.

Extend volume to 400 GB

curl -X POST https://api.<your-domain>/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-domain>/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.

Clone an existing volume

curl -X POST https://api.<your-domain>/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

Create a volume snapshot

curl -X POST https://api.<your-domain>/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-domain>/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 Polystack Object Storage and are independent of volume availability.

Create a full backup

curl -X POST https://api.<your-domain>/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-domain>/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-domain>/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
`creating`	Volume is being provisioned
`available`	Ready to attach
`in-use`	Currently attached to an instance
`deleting`	Deletion in progress
`extending`	Size extension in progress
`retyping`	Volume type change in progress
`backing-up`	Backup in progress
`restoring-backup`	Backup restore in progress
`error`	An error occurred — check volume events
`error_deleting`	Deletion 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

Core Services

Other Services

Overview

Key Endpoints

Create a Volume

Volume Operations

Snapshots

Backups

Volume Status Reference

Next Steps

Compute API

Networking API

Storage QoS

​Overview

​Key Endpoints

​Create a Volume

​Volume Operations

​Snapshots

​Backups

​Volume Status Reference

​Next Steps

Compute API

Networking API

Storage QoS

Overview

Key Endpoints

Create a Volume

Volume Operations

Snapshots

Backups

Volume Status Reference

Next Steps