Volumes

Volume management

List volumes

get

Lists summary information for all Block Storage volumes

Authorizations

X-Auth-TokenstringRequired

OpenStack authentication token

Query parameters

all_tenantsstringOptional

Shows details for all project. Admin only.

sortstringOptional

Comma-separated list of sort keys and optional sort directions

sort_keystringOptional

Sorts by an attribute

sort_dirstring · enumOptional

Sorts by direction (asc or desc)

Possible values:

limitinteger · min: 1Optional

Requests a page size of items

offsetintegerOptional

Used in conjunction with limit to return items starting from the offset position

markerstringOptional

The ID of the last-seen item

with_countbooleanOptional

Whether to show count in response (microversion 3.45+)

created_atstringOptional

Filters results by creation time with comparison operators

updated_atstringOptional

Filters results by update time with comparison operators

consumes_quotabooleanOptional

Filters results by whether resource consumes quota (microversion 3.65+)

Responses

200

application/json

400

Some content in the request was invalid

get

/v3/volumes

GET /v3/v3/volumes HTTP/1.1
Host: example.com
X-Auth-Token: YOUR_API_KEY
Accept: */*

{
  "volumes": [
    {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "name": "text"
    }
  ],
  "volumes_links": [
    {
      "href": "https://example.com",
      "rel": "text",
      "type": "text"
    }
  ],
  "count": 1
}

Create volume

post

Creates a volume

Authorizations

X-Auth-TokenstringRequired

OpenStack authentication token

Body

OS-SCH-HNT:scheduler_hintsobjectOptional

Scheduler hints

Responses

202

Accepted

application/json

post

/v3/volumes

POST /v3/v3/volumes HTTP/1.1
Host: example.com
X-Auth-Token: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 470

{
  "volume": {
    "size": 1,
    "name": "text",
    "description": "text",
    "availability_zone": "text",
    "volume_type": "text",
    "source_volid": "123e4567-e89b-12d3-a456-426614174000",
    "snapshot_id": "123e4567-e89b-12d3-a456-426614174000",
    "backup_id": "123e4567-e89b-12d3-a456-426614174000",
    "imageRef": "123e4567-e89b-12d3-a456-426614174000",
    "metadata": {
      "ANY_ADDITIONAL_PROPERTY": "text"
    },
    "consistencygroup_id": "123e4567-e89b-12d3-a456-426614174000",
    "multiattach": true
  },
  "OS-SCH-HNT:scheduler_hints": {}
}

202

Accepted

{
  "volume": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "name": "text",
    "description": "text",
    "size": 1,
    "status": "text",
    "volume_type": "text",
    "volume_type_id": "123e4567-e89b-12d3-a456-426614174000",
    "availability_zone": "text",
    "bootable": "text",
    "encrypted": true,
    "encryption_key_id": "123e4567-e89b-12d3-a456-426614174000",
    "multiattach": true,
    "attachments": [
      {
        "server_id": "123e4567-e89b-12d3-a456-426614174000",
        "attachment_id": "123e4567-e89b-12d3-a456-426614174000",
        "attached_at": "2025-11-28T20:22:24.128Z",
        "host_name": "text",
        "volume_id": "123e4567-e89b-12d3-a456-426614174000",
        "device": "text",
        "id": "123e4567-e89b-12d3-a456-426614174000"
      }
    ],
    "metadata": {
      "ANY_ADDITIONAL_PROPERTY": "text"
    },
    "created_at": "2025-11-28T20:22:24.128Z",
    "updated_at": "2025-11-28T20:22:24.128Z",
    "user_id": "123e4567-e89b-12d3-a456-426614174000",
    "consistencygroup_id": "123e4567-e89b-12d3-a456-426614174000",
    "group_id": "123e4567-e89b-12d3-a456-426614174000",
    "snapshot_id": "123e4567-e89b-12d3-a456-426614174000",
    "source_volid": "123e4567-e89b-12d3-a456-426614174000",
    "replication_status": "text",
    "migration_status": "text",
    "os-vol-host-attr:host": "text",
    "os-vol-tenant-attr:tenant_id": "123e4567-e89b-12d3-a456-426614174000",
    "os-vol-mig-status-attr:migstat": "text",
    "os-vol-mig-status-attr:name_id": "text",
    "volume_image_metadata": {
      "ANY_ADDITIONAL_PROPERTY": "text"
    },
    "provider_id": "text",
    "service_uuid": "123e4567-e89b-12d3-a456-426614174000",
    "shared_targets": true,
    "cluster_name": "text",
    "consumes_quota": true,
    "links": [
      {
        "href": "https://example.com",
        "rel": "text",
        "type": "text"
      }
    ]
  }
}

List volumes with details

get

Lists all Block Storage volumes with details

Authorizations

X-Auth-TokenstringRequired

OpenStack authentication token

Query parameters

all_tenantsstringOptional

Shows details for all project. Admin only.

sortstringOptional

Comma-separated list of sort keys and optional sort directions

sort_keystringOptional

Sorts by an attribute

sort_dirstring · enumOptional

Sorts by direction (asc or desc)

Possible values:

limitinteger · min: 1Optional

Requests a page size of items

offsetintegerOptional

Used in conjunction with limit to return items starting from the offset position

markerstringOptional

The ID of the last-seen item

with_countbooleanOptional

Whether to show count in response (microversion 3.45+)

created_atstringOptional

Filters results by creation time with comparison operators

updated_atstringOptional

Filters results by update time with comparison operators

consumes_quotabooleanOptional

Filters results by whether resource consumes quota (microversion 3.65+)

Responses

200

application/json

400

Some content in the request was invalid

get

/v3/volumes/detail

GET /v3/v3/volumes/detail HTTP/1.1
Host: example.com
X-Auth-Token: YOUR_API_KEY
Accept: */*

{
  "volumes": [
    {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "name": "text",
      "description": "text",
      "size": 1,
      "status": "text",
      "volume_type": "text",
      "volume_type_id": "123e4567-e89b-12d3-a456-426614174000",
      "availability_zone": "text",
      "bootable": "text",
      "encrypted": true,
      "encryption_key_id": "123e4567-e89b-12d3-a456-426614174000",
      "multiattach": true,
      "attachments": [
        {
          "server_id": "123e4567-e89b-12d3-a456-426614174000",
          "attachment_id": "123e4567-e89b-12d3-a456-426614174000",
          "attached_at": "2025-11-28T20:22:24.128Z",
          "host_name": "text",
          "volume_id": "123e4567-e89b-12d3-a456-426614174000",
          "device": "text",
          "id": "123e4567-e89b-12d3-a456-426614174000"
        }
      ],
      "metadata": {
        "ANY_ADDITIONAL_PROPERTY": "text"
      },
      "created_at": "2025-11-28T20:22:24.128Z",
      "updated_at": "2025-11-28T20:22:24.128Z",
      "user_id": "123e4567-e89b-12d3-a456-426614174000",
      "consistencygroup_id": "123e4567-e89b-12d3-a456-426614174000",
      "group_id": "123e4567-e89b-12d3-a456-426614174000",
      "snapshot_id": "123e4567-e89b-12d3-a456-426614174000",
      "source_volid": "123e4567-e89b-12d3-a456-426614174000",
      "replication_status": "text",
      "migration_status": "text",
      "os-vol-host-attr:host": "text",
      "os-vol-tenant-attr:tenant_id": "123e4567-e89b-12d3-a456-426614174000",
      "os-vol-mig-status-attr:migstat": "text",
      "os-vol-mig-status-attr:name_id": "text",
      "volume_image_metadata": {
        "ANY_ADDITIONAL_PROPERTY": "text"
      },
      "provider_id": "text",
      "service_uuid": "123e4567-e89b-12d3-a456-426614174000",
      "shared_targets": true,
      "cluster_name": "text",
      "consumes_quota": true,
      "links": [
        {
          "href": "https://example.com",
          "rel": "text",
          "type": "text"
        }
      ]
    }
  ],
  "volumes_links": [
    {
      "href": "https://example.com",
      "rel": "text",
      "type": "text"
    }
  ],
  "count": 1
}

Show volumes summary

get

Display volumes summary with total number and size (microversion 3.12+)

Authorizations

X-Auth-TokenstringRequired

OpenStack authentication token

Query parameters

all_tenantsstringOptional

Shows details for all project. Admin only.

Responses

200

application/json

get

/v3/volumes/summary

GET /v3/v3/volumes/summary HTTP/1.1
Host: example.com
X-Auth-Token: YOUR_API_KEY
Accept: */*

200

{
  "volume-summary": {
    "total_size": 1,
    "total_count": 1,
    "metadata": {
      "ANY_ADDITIONAL_PROPERTY": [
        "text"
      ]
    }
  }
}

Show volume details

get

Shows details for a volume

Authorizations

X-Auth-TokenstringRequired

OpenStack authentication token

Path parameters

volume_idstring · uuidRequired

The UUID of the volume

Responses

200

application/json

get

/v3/volumes/{volume_id}

GET /v3/v3/volumes/{volume_id} HTTP/1.1
Host: example.com
X-Auth-Token: YOUR_API_KEY
Accept: */*

200

{
  "volume": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "name": "text",
    "description": "text",
    "size": 1,
    "status": "text",
    "volume_type": "text",
    "volume_type_id": "123e4567-e89b-12d3-a456-426614174000",
    "availability_zone": "text",
    "bootable": "text",
    "encrypted": true,
    "encryption_key_id": "123e4567-e89b-12d3-a456-426614174000",
    "multiattach": true,
    "attachments": [
      {
        "server_id": "123e4567-e89b-12d3-a456-426614174000",
        "attachment_id": "123e4567-e89b-12d3-a456-426614174000",
        "attached_at": "2025-11-28T20:22:24.128Z",
        "host_name": "text",
        "volume_id": "123e4567-e89b-12d3-a456-426614174000",
        "device": "text",
        "id": "123e4567-e89b-12d3-a456-426614174000"
      }
    ],
    "metadata": {
      "ANY_ADDITIONAL_PROPERTY": "text"
    },
    "created_at": "2025-11-28T20:22:24.128Z",
    "updated_at": "2025-11-28T20:22:24.128Z",
    "user_id": "123e4567-e89b-12d3-a456-426614174000",
    "consistencygroup_id": "123e4567-e89b-12d3-a456-426614174000",
    "group_id": "123e4567-e89b-12d3-a456-426614174000",
    "snapshot_id": "123e4567-e89b-12d3-a456-426614174000",
    "source_volid": "123e4567-e89b-12d3-a456-426614174000",
    "replication_status": "text",
    "migration_status": "text",
    "os-vol-host-attr:host": "text",
    "os-vol-tenant-attr:tenant_id": "123e4567-e89b-12d3-a456-426614174000",
    "os-vol-mig-status-attr:migstat": "text",
    "os-vol-mig-status-attr:name_id": "text",
    "volume_image_metadata": {
      "ANY_ADDITIONAL_PROPERTY": "text"
    },
    "provider_id": "text",
    "service_uuid": "123e4567-e89b-12d3-a456-426614174000",
    "shared_targets": true,
    "cluster_name": "text",
    "consumes_quota": true,
    "links": [
      {
        "href": "https://example.com",
        "rel": "text",
        "type": "text"
      }
    ]
  }
}

Update volume

put

Updates a volume

Authorizations

X-Auth-TokenstringRequired

OpenStack authentication token

Path parameters

volume_idstring · uuidRequired

The UUID of the volume

Body

Responses

200

application/json

put

/v3/volumes/{volume_id}

PUT /v3/v3/volumes/{volume_id} HTTP/1.1
Host: example.com
X-Auth-Token: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 93

{
  "volume": {
    "name": "text",
    "description": "text",
    "metadata": {
      "ANY_ADDITIONAL_PROPERTY": "text"
    }
  }
}

200

{
  "volume": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "name": "text",
    "description": "text",
    "size": 1,
    "status": "text",
    "volume_type": "text",
    "volume_type_id": "123e4567-e89b-12d3-a456-426614174000",
    "availability_zone": "text",
    "bootable": "text",
    "encrypted": true,
    "encryption_key_id": "123e4567-e89b-12d3-a456-426614174000",
    "multiattach": true,
    "attachments": [
      {
        "server_id": "123e4567-e89b-12d3-a456-426614174000",
        "attachment_id": "123e4567-e89b-12d3-a456-426614174000",
        "attached_at": "2025-11-28T20:22:24.128Z",
        "host_name": "text",
        "volume_id": "123e4567-e89b-12d3-a456-426614174000",
        "device": "text",
        "id": "123e4567-e89b-12d3-a456-426614174000"
      }
    ],
    "metadata": {
      "ANY_ADDITIONAL_PROPERTY": "text"
    },
    "created_at": "2025-11-28T20:22:24.128Z",
    "updated_at": "2025-11-28T20:22:24.128Z",
    "user_id": "123e4567-e89b-12d3-a456-426614174000",
    "consistencygroup_id": "123e4567-e89b-12d3-a456-426614174000",
    "group_id": "123e4567-e89b-12d3-a456-426614174000",
    "snapshot_id": "123e4567-e89b-12d3-a456-426614174000",
    "source_volid": "123e4567-e89b-12d3-a456-426614174000",
    "replication_status": "text",
    "migration_status": "text",
    "os-vol-host-attr:host": "text",
    "os-vol-tenant-attr:tenant_id": "123e4567-e89b-12d3-a456-426614174000",
    "os-vol-mig-status-attr:migstat": "text",
    "os-vol-mig-status-attr:name_id": "text",
    "volume_image_metadata": {
      "ANY_ADDITIONAL_PROPERTY": "text"
    },
    "provider_id": "text",
    "service_uuid": "123e4567-e89b-12d3-a456-426614174000",
    "shared_targets": true,
    "cluster_name": "text",
    "consumes_quota": true,
    "links": [
      {
        "href": "https://example.com",
        "rel": "text",
        "type": "text"
      }
    ]
  }
}

Delete volume

delete

Deletes a volume

Authorizations

X-Auth-TokenstringRequired

OpenStack authentication token

Path parameters

volume_idstring · uuidRequired

The UUID of the volume

Query parameters

cascadebooleanOptional

Remove any snapshots along with the volume

Default: false

forcebooleanOptional

Force delete even if volume is in deleting or error_deleting state (microversion 3.23+)

Default: false

Responses

202

Request is accepted, but processing may take some time

delete

/v3/volumes/{volume_id}

DELETE /v3/v3/volumes/{volume_id} HTTP/1.1
Host: example.com
X-Auth-Token: YOUR_API_KEY
Accept: */*

202

Request is accepted, but processing may take some time

No content

Perform volume action

post

Performs various actions on a volume

Authorizations

X-Auth-TokenstringRequired

OpenStack authentication token

Path parameters

volume_idstring · uuidRequired

The UUID of the volume

Body

one ofOptional

Responses

200

OK (for show operations)

application/json

Responseobject

202

Request is accepted, but processing may take some time

400

Some content in the request was invalid

403

Policy does not allow current user to do this operation

404

The requested resource could not be found

409

This resource has an action in progress that would conflict with this request

post

/v3/volumes/{volume_id}/action

POST /v3/v3/volumes/{volume_id}/action HTTP/1.1
Host: example.com
X-Auth-Token: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 28

{
  "os-extend": {
    "new_size": 1
  }
}

{}

Show volume metadata

get

Shows metadata for a volume

Authorizations

X-Auth-TokenstringRequired

OpenStack authentication token

Path parameters

volume_idstring · uuidRequired

The UUID of the volume

Responses

200

application/json

get

/v3/volumes/{volume_id}/metadata

GET /v3/v3/volumes/{volume_id}/metadata HTTP/1.1
Host: example.com
X-Auth-Token: YOUR_API_KEY
Accept: */*

200

{
  "metadata": {
    "ANY_ADDITIONAL_PROPERTY": "text"
  }
}

Create or update volume metadata

post

Creates or replaces metadata for a volume

Authorizations

X-Auth-TokenstringRequired

OpenStack authentication token

Path parameters

volume_idstring · uuidRequired

The UUID of the volume

Body

Responses

200

application/json

post

/v3/volumes/{volume_id}/metadata

POST /v3/v3/volumes/{volume_id}/metadata HTTP/1.1
Host: example.com
X-Auth-Token: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 47

{
  "metadata": {
    "ANY_ADDITIONAL_PROPERTY": "text"
  }
}

200

{
  "metadata": {
    "ANY_ADDITIONAL_PROPERTY": "text"
  }
}

Replace volume metadata

put

Replaces all the volume's metadata with the provided key-value pairs

Authorizations

X-Auth-TokenstringRequired

OpenStack authentication token

Path parameters

volume_idstring · uuidRequired

The UUID of the volume

Body

Responses

200

application/json

put

/v3/volumes/{volume_id}/metadata

PUT /v3/v3/volumes/{volume_id}/metadata HTTP/1.1
Host: example.com
X-Auth-Token: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 47

{
  "metadata": {
    "ANY_ADDITIONAL_PROPERTY": "text"
  }
}

200

{
  "metadata": {
    "ANY_ADDITIONAL_PROPERTY": "text"
  }
}

Show volume metadata item

get

Shows metadata for a volume for a specific key

Authorizations

X-Auth-TokenstringRequired

OpenStack authentication token

Path parameters

volume_idstring · uuidRequired

The UUID of the volume

keystringRequired

The metadata key name

Responses

200

application/json

get

/v3/volumes/{volume_id}/metadata/{key}

GET /v3/v3/volumes/{volume_id}/metadata/{key} HTTP/1.1
Host: example.com
X-Auth-Token: YOUR_API_KEY
Accept: */*

200

{
  "meta": {
    "ANY_ADDITIONAL_PROPERTY": "text"
  }
}

Update volume metadata item

put

Update metadata for a volume for a specific key

Authorizations

X-Auth-TokenstringRequired

OpenStack authentication token

Path parameters

volume_idstring · uuidRequired

The UUID of the volume

keystringRequired

The metadata key name

Body

Responses

200

application/json

put

/v3/volumes/{volume_id}/metadata/{key}

PUT /v3/v3/volumes/{volume_id}/metadata/{key} HTTP/1.1
Host: example.com
X-Auth-Token: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 43

{
  "meta": {
    "ANY_ADDITIONAL_PROPERTY": "text"
  }
}

200

{
  "meta": {
    "ANY_ADDITIONAL_PROPERTY": "text"
  }
}

Delete volume metadata item

delete

Deletes metadata for a volume

Authorizations

X-Auth-TokenstringRequired

OpenStack authentication token

Path parameters

volume_idstring · uuidRequired

The UUID of the volume

keystringRequired

The metadata key name

Responses

200

No content

delete

/v3/volumes/{volume_id}/metadata/{key}

DELETE /v3/v3/volumes/{volume_id}/metadata/{key} HTTP/1.1
Host: example.com
X-Auth-Token: YOUR_API_KEY
Accept: */*

200

No content

PreviousDefault Types NextSnapshots

Last updated 4 hours ago

Was this helpful?

Good evening

List volumes

Create volume

List volumes with details

Show volumes summary

Show volume details

Update volume

Delete volume

Perform volume action

Show volume metadata

Create or update volume metadata

Replace volume metadata

Show volume metadata item

Update volume metadata item

Delete volume metadata item