OpenStack API Documentation

Block Storage API v2 (CURRENT)

Manages volumes and snapshots for use with the Block Storage API, also known as cinder services.

API versions

GET

List API versions

Lists information about all Block Storage API versions.

Normal response codes

200, 300

{
    "versions": [
        {
            "status": "CURRENT",
            "updated": "2012-01-04T11:33:21Z",
            "id": "v1.0",
            "links": [
                {
                    "href": "http://23.253.228.211:8776/v1/",
                    "rel": "self"
                }
            ]
        },
        {
            "status": "CURRENT",
            "updated": "2012-11-21T11:33:21Z",
            "id": "v2.0",
            "links": [
                {
                    "href": "http://23.253.228.211:8776/v2/",
                    "rel": "self"
                }
            ]
        }
    ]
}

This operation does not accept a request body.

GET

/v2

Show API version details

Shows details for Block Storage API v2.

Normal response codes

200, 203

{
    "version": {
        "status": "CURRENT",
        "updated": "2012-01-04T11:33:21Z",
        "media-types": [
            {
                "base": "application/xml",
                "type": "application/vnd.openstack.volume+xml;version=1"
            },
            {
                "base": "application/json",
                "type": "application/vnd.openstack.volume+json;version=1"
            }
        ],
        "id": "v1.0",
        "links": [
            {
                "href": "http://23.253.228.211:8776/v2/",
                "rel": "self"
            },
            {
                "href": "http://jorgew.github.com/block-storage-api/content/os-block-storage-1.0.pdf",
                "type": "application/pdf",
                "rel": "describedby"
            },
            {
                "href": "http://docs.rackspacecloud.com/servers/api/v1.1/application.wadl",
                "type": "application/vnd.sun.wadl+xml",
                "rel": "describedby"
            }
        ]
    }
}

This operation does not accept a request body.

API extensions

GET

/v2/{tenant_id}/extensions

List API extensions

Lists Block Storage API extensions.

Normal response codes

200, 300

Request parameters

Parameter	Style	Type	Description
tenant_id	URI	xsd:string	The unique identifier of the tenant or account.

{
    "extensions": [
        {
            "updated": "2013-04-18T00:00:00+00:00",
            "name": "SchedulerHints",
            "links": [],
            "namespace": "http://docs.openstack.org/block-service/ext/scheduler-hints/api/v2",
            "alias": "OS-SCH-HNT",
            "description": "Pass arbitrary key/value pairs to the scheduler."
        },
        {
            "updated": "2011-06-29T00:00:00+00:00",
            "name": "Hosts",
            "links": [],
            "namespace": "http://docs.openstack.org/volume/ext/hosts/api/v1.1",
            "alias": "os-hosts",
            "description": "Admin-only host administration."
        },
        {
            "updated": "2011-11-03T00:00:00+00:00",
            "name": "VolumeTenantAttribute",
            "links": [],
            "namespace": "http://docs.openstack.org/volume/ext/volume_tenant_attribute/api/v1",
            "alias": "os-vol-tenant-attr",
            "description": "Expose the internal project_id as an attribute of a volume."
        },
        {
            "updated": "2011-08-08T00:00:00+00:00",
            "name": "Quotas",
            "links": [],
            "namespace": "http://docs.openstack.org/volume/ext/quotas-sets/api/v1.1",
            "alias": "os-quota-sets",
            "description": "Quota management support."
        },
        {
            "updated": "2011-08-24T00:00:00+00:00",
            "name": "TypesManage",
            "links": [],
            "namespace": "http://docs.openstack.org/volume/ext/types-manage/api/v1",
            "alias": "os-types-manage",
            "description": "Types manage support."
        },
        {
            "updated": "2013-07-10T00:00:00+00:00",
            "name": "VolumeEncryptionMetadata",
            "links": [],
            "namespace": "http://docs.openstack.org/volume/ext/os-volume-encryption-metadata/api/v1",
            "alias": "os-volume-encryption-metadata",
            "description": "Volume encryption metadata retrieval support."
        },
        {
            "updated": "2012-12-12T00:00:00+00:00",
            "name": "Backups",
            "links": [],
            "namespace": "http://docs.openstack.org/volume/ext/backups/api/v1",
            "alias": "backups",
            "description": "Backups support."
        },
        {
            "updated": "2013-07-16T00:00:00+00:00",
            "name": "SnapshotActions",
            "links": [],
            "namespace": "http://docs.openstack.org/volume/ext/snapshot-actions/api/v1.1",
            "alias": "os-snapshot-actions",
            "description": "Enable snapshot manager actions."
        },
        {
            "updated": "2012-05-31T00:00:00+00:00",
            "name": "VolumeActions",
            "links": [],
            "namespace": "http://docs.openstack.org/volume/ext/volume-actions/api/v1.1",
            "alias": "os-volume-actions",
            "description": "Enable volume actions\n    "
        },
        {
            "updated": "2013-10-03T00:00:00+00:00",
            "name": "UsedLimits",
            "links": [],
            "namespace": "http://docs.openstack.org/volume/ext/used-limits/api/v1.1",
            "alias": "os-used-limits",
            "description": "Provide data on limited resources that are being used."
        },
        {
            "updated": "2012-05-31T00:00:00+00:00",
            "name": "VolumeUnmanage",
            "links": [],
            "namespace": "http://docs.openstack.org/volume/ext/volume-unmanage/api/v1.1",
            "alias": "os-volume-unmanage",
            "description": "Enable volume unmanage operation."
        },
        {
            "updated": "2011-11-03T00:00:00+00:00",
            "name": "VolumeHostAttribute",
            "links": [],
            "namespace": "http://docs.openstack.org/volume/ext/volume_host_attribute/api/v1",
            "alias": "os-vol-host-attr",
            "description": "Expose host as an attribute of a volume."
        },
        {
            "updated": "2013-07-01T00:00:00+00:00",
            "name": "VolumeTypeEncryption",
            "links": [],
            "namespace": "http://docs.openstack.org/volume/ext/volume-type-encryption/api/v1",
            "alias": "encryption",
            "description": "Encryption support for volume types."
        },
        {
            "updated": "2013-06-27T00:00:00+00:00",
            "name": "AvailabilityZones",
            "links": [],
            "namespace": "http://docs.openstack.org/volume/ext/os-availability-zone/api/v1",
            "alias": "os-availability-zone",
            "description": "Describe Availability Zones."
        },
        {
            "updated": "2013-08-02T00:00:00+00:00",
            "name": "Qos_specs_manage",
            "links": [],
            "namespace": "http://docs.openstack.org/volume/ext/qos-specs/api/v1",
            "alias": "qos-specs",
            "description": "QoS specs support."
        },
        {
            "updated": "2011-08-24T00:00:00+00:00",
            "name": "TypesExtraSpecs",
            "links": [],
            "namespace": "http://docs.openstack.org/volume/ext/types-extra-specs/api/v1",
            "alias": "os-types-extra-specs",
            "description": "Type extra specs support."
        },
        {
            "updated": "2013-08-08T00:00:00+00:00",
            "name": "VolumeMigStatusAttribute",
            "links": [],
            "namespace": "http://docs.openstack.org/volume/ext/volume_mig_status_attribute/api/v1",
            "alias": "os-vol-mig-status-attr",
            "description": "Expose migration_status as an attribute of a volume."
        },
        {
            "updated": "2012-08-13T00:00:00+00:00",
            "name": "CreateVolumeExtension",
            "links": [],
            "namespace": "http://docs.openstack.org/volume/ext/image-create/api/v1",
            "alias": "os-image-create",
            "description": "Allow creating a volume from an image in the Create Volume v1 API."
        },
        {
            "updated": "2014-01-10T00:00:00-00:00",
            "name": "ExtendedServices",
            "links": [],
            "namespace": "http://docs.openstack.org/volume/ext/extended_services/api/v2",
            "alias": "os-extended-services",
            "description": "Extended services support."
        },
        {
            "updated": "2012-06-19T00:00:00+00:00",
            "name": "ExtendedSnapshotAttributes",
            "links": [],
            "namespace": "http://docs.openstack.org/volume/ext/extended_snapshot_attributes/api/v1",
            "alias": "os-extended-snapshot-attributes",
            "description": "Extended SnapshotAttributes support."
        },
        {
            "updated": "2012-12-07T00:00:00+00:00",
            "name": "VolumeImageMetadata",
            "links": [],
            "namespace": "http://docs.openstack.org/volume/ext/volume_image_metadata/api/v1",
            "alias": "os-vol-image-meta",
            "description": "Show image metadata associated with the volume."
        },
        {
            "updated": "2012-03-12T00:00:00+00:00",
            "name": "QuotaClasses",
            "links": [],
            "namespace": "http://docs.openstack.org/volume/ext/quota-classes-sets/api/v1.1",
            "alias": "os-quota-class-sets",
            "description": "Quota classes management support."
        },
        {
            "updated": "2013-05-29T00:00:00+00:00",
            "name": "VolumeTransfer",
            "links": [],
            "namespace": "http://docs.openstack.org/volume/ext/volume-transfer/api/v1.1",
            "alias": "os-volume-transfer",
            "description": "Volume transfer management support."
        },
        {
            "updated": "2014-02-10T00:00:00+00:00",
            "name": "VolumeManage",
            "links": [],
            "namespace": "http://docs.openstack.org/volume/ext/os-volume-manage/api/v1",
            "alias": "os-volume-manage",
            "description": "Allows existing backend storage to be 'managed' by Cinder."
        },
        {
            "updated": "2012-08-25T00:00:00+00:00",
            "name": "AdminActions",
            "links": [],
            "namespace": "http://docs.openstack.org/volume/ext/admin-actions/api/v1.1",
            "alias": "os-admin-actions",
            "description": "Enable admin actions."
        },
        {
            "updated": "2012-10-28T00:00:00-00:00",
            "name": "Services",
            "links": [],
            "namespace": "http://docs.openstack.org/volume/ext/services/api/v2",
            "alias": "os-services",
            "description": "Services support."
        }
    ]
}

<?xml version='1.0' encoding='UTF-8'?>
<extensions xmlns:atom="http://www.w3.org/2005/Atom"
    xmlns="http://docs.openstack.org/common/api/v1.0">
    <extension alias="OS-SCH-HNT" updated="2013-04-18T00:00:00+00:00"
        namespace="http://docs.openstack.org/block-service/ext/scheduler-hints/api/v2"
        name="SchedulerHints">
        <description>Pass arbitrary key/value pairs to the
            scheduler.</description>
    </extension>
    <extension alias="os-hosts" updated="2011-06-29T00:00:00+00:00"
        namespace="http://docs.openstack.org/volume/ext/hosts/api/v1.1"
        name="Hosts">
        <description>Admin-only host administration.</description>
    </extension>
    <extension alias="os-vol-tenant-attr"
        updated="2011-11-03T00:00:00+00:00"
        namespace="http://docs.openstack.org/volume/ext/volume_tenant_attribute/api/v1"
        name="VolumeTenantAttribute">
        <description>Expose the internal project_id as an attribute of
            a volume.</description>
    </extension>
    <extension alias="os-quota-sets"
        updated="2011-08-08T00:00:00+00:00"
        namespace="http://docs.openstack.org/volume/ext/quotas-sets/api/v1.1"
        name="Quotas">
        <description>Quota management support.</description>
    </extension>
    <extension alias="os-types-manage"
        updated="2011-08-24T00:00:00+00:00"
        namespace="http://docs.openstack.org/volume/ext/types-manage/api/v1"
        name="TypesManage">
        <description>Types manage support.</description>
    </extension>
    <extension alias="os-volume-encryption-metadata"
        updated="2013-07-10T00:00:00+00:00"
        namespace="http://docs.openstack.org/volume/ext/os-volume-encryption-metadata/api/v1"
        name="VolumeEncryptionMetadata">
        <description>Volume encryption metadata retrieval
            support.</description>
    </extension>
    <extension alias="backups" updated="2012-12-12T00:00:00+00:00"
        namespace="http://docs.openstack.org/volume/ext/backups/api/v1"
        name="Backups">
        <description>Backups support.</description>
    </extension>
    <extension alias="os-snapshot-actions"
        updated="2013-07-16T00:00:00+00:00"
        namespace="http://docs.openstack.org/volume/ext/snapshot-actions/api/v1.1"
        name="SnapshotActions">
        <description>Enable snapshot manager actions.</description>
    </extension>
    <extension alias="os-volume-actions"
        updated="2012-05-31T00:00:00+00:00"
        namespace="http://docs.openstack.org/volume/ext/volume-actions/api/v1.1"
        name="VolumeActions">
        <description>Enable volume actions </description>
    </extension>
    <extension alias="os-used-limits"
        updated="2013-10-03T00:00:00+00:00"
        namespace="http://docs.openstack.org/volume/ext/used-limits/api/v1.1"
        name="UsedLimits">
        <description>Provide data on limited resources that are being
            used.</description>
    </extension>
    <extension alias="os-volume-unmanage"
        updated="2012-05-31T00:00:00+00:00"
        namespace="http://docs.openstack.org/volume/ext/volume-unmanage/api/v1.1"
        name="VolumeUnmanage">
        <description>Enable volume unmanage operation.</description>
    </extension>
    <extension alias="os-vol-host-attr"
        updated="2011-11-03T00:00:00+00:00"
        namespace="http://docs.openstack.org/volume/ext/volume_host_attribute/api/v1"
        name="VolumeHostAttribute">
        <description>Expose host as an attribute of a
            volume.</description>
    </extension>
    <extension alias="encryption" updated="2013-07-01T00:00:00+00:00"
        namespace="http://docs.openstack.org/volume/ext/volume-type-encryption/api/v1"
        name="VolumeTypeEncryption">
        <description>Encryption support for volume
            types.</description>
    </extension>
    <extension alias="os-availability-zone"
        updated="2013-06-27T00:00:00+00:00"
        namespace="http://docs.openstack.org/volume/ext/os-availability-zone/api/v1"
        name="AvailabilityZones">
        <description>Describe Availability Zones.</description>
    </extension>
    <extension alias="qos-specs" updated="2013-08-02T00:00:00+00:00"
        namespace="http://docs.openstack.org/volume/ext/qos-specs/api/v1"
        name="Qos_specs_manage">
        <description>QoS specs support.</description>
    </extension>
    <extension alias="os-types-extra-specs"
        updated="2011-08-24T00:00:00+00:00"
        namespace="http://docs.openstack.org/volume/ext/types-extra-specs/api/v1"
        name="TypesExtraSpecs">
        <description>Type extra specs support.</description>
    </extension>
    <extension alias="os-vol-mig-status-attr"
        updated="2013-08-08T00:00:00+00:00"
        namespace="http://docs.openstack.org/volume/ext/volume_mig_status_attribute/api/v1"
        name="VolumeMigStatusAttribute">
        <description>Expose migration_status as an attribute of a
            volume.</description>
    </extension>
    <extension alias="os-image-create"
        updated="2012-08-13T00:00:00+00:00"
        namespace="http://docs.openstack.org/volume/ext/image-create/api/v1"
        name="CreateVolumeExtension">
        <description>Allow creating a volume from an image in the
            Create Volume v1 API.</description>
    </extension>
    <extension alias="os-extended-services"
        updated="2014-01-10T00:00:00-00:00"
        namespace="http://docs.openstack.org/volume/ext/extended_services/api/v2"
        name="ExtendedServices">
        <description>Extended services support.</description>
    </extension>
    <extension alias="os-extended-snapshot-attributes"
        updated="2012-06-19T00:00:00+00:00"
        namespace="http://docs.openstack.org/volume/ext/extended_snapshot_attributes/api/v1"
        name="ExtendedSnapshotAttributes">
        <description>Extended SnapshotAttributes
            support.</description>
    </extension>
    <extension alias="os-vol-image-meta"
        updated="2012-12-07T00:00:00+00:00"
        namespace="http://docs.openstack.org/volume/ext/volume_image_metadata/api/v1"
        name="VolumeImageMetadata">
        <description>Show image metadata associated with the
            volume.</description>
    </extension>
    <extension alias="os-quota-class-sets"
        updated="2012-03-12T00:00:00+00:00"
        namespace="http://docs.openstack.org/volume/ext/quota-classes-sets/api/v1.1"
        name="QuotaClasses">
        <description>Quota classes management support.</description>
    </extension>
    <extension alias="os-volume-transfer"
        updated="2013-05-29T00:00:00+00:00"
        namespace="http://docs.openstack.org/volume/ext/volume-transfer/api/v1.1"
        name="VolumeTransfer">
        <description>Volume transfer management support.</description>
    </extension>
    <extension alias="os-volume-manage"
        updated="2014-02-10T00:00:00+00:00"
        namespace="http://docs.openstack.org/volume/ext/os-volume-manage/api/v1"
        name="VolumeManage">
        <description>Allows existing backend storage to be 'managed'
            by Cinder.</description>
    </extension>
    <extension alias="os-admin-actions"
        updated="2012-08-25T00:00:00+00:00"
        namespace="http://docs.openstack.org/volume/ext/admin-actions/api/v1.1"
        name="AdminActions">
        <description>Enable admin actions.</description>
    </extension>
    <extension alias="os-services" updated="2012-10-28T00:00:00-00:00"
        namespace="http://docs.openstack.org/volume/ext/services/api/v2"
        name="Services">
        <description>Services support.</description>
    </extension>
</extensions>

This operation does not accept a request body.

Volumes

A volume is a detachable block storage device similar to a USB hard drive. You can attach a volume to one instance at a time.

The snapshot_id and source_volid parameters specify the ID of the snapshot or volume from which this volume originates. If the volume was not created from a snapshot or source volume, these values are null.

When you create, list, update, or delete volumes, the possible status values are:

Volume statuses
Status	Description
creating	The volume is being created.
available	The volume is ready to be attached to an instance.
attaching	The volume is attaching to an instance.
in-use	The volume is attached to an instance.
deleting	The volume is being deleted.
error	An error occurred during volume creation.
error_deleting	An error occurred during volume deletion.
backing-up	The volume is being backed up.
restoring-backup	A backup is being restored to the volume.
error_restoring	An error occurred during backup restoration to a volume.
error_extending	An error occurred while attempting to extend a volume.

POST

/v2/{tenant_id}/volumes

Create volume

Creates a volume.

To create a bootable volume, include the ID of the image from which you want to create the volume in the imageRef attribute in the request body.

Preconditions

You must have enough volume storage quota remaining to create a volume of size requested.

Asynchronous Postconditions

With correct permissions, you can see the volume status as available through API calls.
With correct access, you can see the created volume in the storage system that OpenStack Block Storage manages.

Troubleshooting

If volume status remains creating or shows another error status, the request failed. Ensure you meet the preconditions then investigate the storage back end.
Volume is not created in the storage system which OpenStack Block Storage manages.
The storage node needs enough free storage space to match the specified size of the volume creation request.

Normal response codes

202

Request parameters

Parameter	Style	Type	Description
tenant_id	URI	xsd:string	The unique identifier of the tenant or account.
availability_zone (Optional)	plain	xsd:string	The availability zone.
source_volid (Optional)	plain	csapi:uuid	To create a volume from an existing volume, specify the ID of the existing volume. The volume is created with the same size as the source volume.
description (Optional)	plain	xsd:string	The volume description.
snapshot_id (Optional)	plain	csapi:uuid	To create a volume from an existing snapshot, specify the ID of the existing volume snapshot. The volume is created in same availability zone and with same size as the snapshot.
size	plain	xsd:int	The size of the volume, in gibibytes (GiB).
name (Optional)	plain	xsd:string	The volume name.
imageRef (Optional)	plain	csapi:uuid	The ID of the image from which you want to create the volume. Required to create a bootable volume.
volume_type (Optional)	plain	xsd:string	The associated volume type.
metadata (Optional)	plain	xsd:string	One or more metadata key and value pairs to associate with the volume.

Response parameters

Parameter	Style	Type	Description
status	plain	xsd:string	The volume status.
name	plain	xsd:string	The volume name.
attachments	plain	xsd:dict	One or more instance attachments.
availability_zone	plain	xsd:string	The availability zone.
created_at	plain	xsd:datetime	Date and time when the volume was created.
description	plain	xsd:string	The volume description.
volume_type	plain	xsd:string	The associated volume type.
snapshot_id	plain	csapi:uuid	The ID of the source volume snapshot.
source_volid	plain	csapi:uuid	The ID of the source volume.
metadata	plain	xsd:string	One or more metadata key and value pairs to associate with the volume.
id	plain	csapi:uuid	The volume ID.
size	plain	xsd:int	The size of the volume, in gibibytes (GiB).

{
    "volume": {
        "status": "creating",
        "description": null,
        "availability_zone": null,
        "source_volid": null,
        "consistencygroup_id": null,
        "snapshot_id": null,
        "source_replica": null,
        "size": 10,
        "user_id": null,
        "name": null,
        "imageRef": null,
        "attach_status": "detached",
        "volume_type": null,
        "project_id": null,
        "metadata": {}
    }
}

<?xml version="1.0" encoding="UTF-8"?>
<volume
    xmlns="http://docs.openstack.org/openstack-block-storage/2.0/content"
    name="vol-001" description="Another volume."
    size="2"/>

{
    "volume": {
        "status": "creating",
        "user_id": "{user_id}",
        "attachments": [],
        "links": [
            {
                "href": "http://volume.example.com:8776/v2/{tenant_id}/volumes/{volume_id}",
                "rel": "self"
            },
            {
                "href": "http://volume.example.com:8776/{tenant_id}/volumes/{volume_id}",
                "rel": "bookmark"
            }
        ],
        "availability_zone": "nova",
        "bootable": "false",
        "encrypted": false,
        "created_at": "2015-05-17T18:14:34.000000",
        "description": null,
        "os-vol-tenant-attr:tenant_id": "{tenant_id}",
        "os-volume-replication:driver_data": null,
        "volume_type": "lvmdriver-1",
        "name": null,
        "replication_status": "disabled",
        "consistencygroup_id": null,
        "source_volid": null,
        "snapshot_id": null,
        "os-volume-replication:extended_status": null,
        "metadata": {},
        "id": "7449e332-9715-4185-b191-1cfd91d75d48",
        "size": 10
    }
}

<?xml version='1.0' encoding='UTF-8'?>
<volume xmlns:atom="http://www.w3.org/2005/Atom"
    xmlns="http://docs.openstack.org/volume/api/v1" status="creating"
    name="vol-001" availability_zone="nova" bootable="false"
    created_at="2014-02-21 20:18:33.122452"
    description="Another volume." volume_type="None"
    snapshot_id="None" source_volid="None"
    id="83960a54-8dad-4fd8-bc41-33c71e098e04" size="2">
    <attachments/>
    <metadata/>
</volume>

GET

/v2/{tenant_id}/volumes

List volumes

Lists summary information for all Block Storage volumes that the tenant who submits the request can access.

Normal response codes

200

Request parameters

Parameter	Style	Type	Description
tenant_id	URI	xsd:string	The unique identifier of the tenant or account.
sort (Optional)	query	xsd:string	Comma-separated list of sort keys and optional sort directions in the form of <key>[:<direction>]. A valid direction is `asc` (ascending) or `desc` (descending).
limit (Optional)	query	xsd:int	Requests a specified page size of returned items from the query. Returns a number of items up to the specified limit value. Use the `limit` parameter to make an initial limited request and use the ID of the last-seen item from the response as the `marker` parameter value in a subsequent limited request.
marker (Optional)	query	xsd:string	Specifies the ID of the last-seen item. Use the `limit` parameter to make an initial limited request and use the ID of the last-seen item from the response as the `marker` parameter value in a subsequent limited request.

Response parameters

Parameter	Style	Type	Description
status	plain	xsd:string	The volume status.
name	plain	xsd:string	The volume name.
attachments	plain	xsd:dict	One or more instance attachments.
availability_zone	plain	xsd:string	The availability zone.
created_at	plain	xsd:datetime	Date and time when the volume was created.
description	plain	xsd:string	The volume description.
volume_type	plain	xsd:string	The associated volume type.
snapshot_id	plain	csapi:uuid	The ID of the source volume snapshot.
source_volid	plain	csapi:uuid	The ID of the source volume.
metadata	plain	xsd:string	One or more metadata key and value pairs to associate with the volume.
id	plain	csapi:uuid	The volume ID.
size	plain	xsd:int	The size of the volume, in gibibytes (GiB).

{
    "volumes": [
        {
            "id": "45baf976-c20a-4894-a7c3-c94b7376bf55",
            "links": [
                {
                    "href": "http://localhost:8776/v2/0c2eba2c5af04d3f9e9d0d410b371fde/volumes/45baf976-c20a-4894-a7c3-c94b7376bf55",
                    "rel": "self"
                },
                {
                    "href": "http://localhost:8776/0c2eba2c5af04d3f9e9d0d410b371fde/volumes/45baf976-c20a-4894-a7c3-c94b7376bf55",
                    "rel": "bookmark"
                }
            ],
            "name": "vol-004"
        },
        {
            "id": "5aa119a8-d25b-45a7-8d1b-88e127885635",
            "links": [
                {
                    "href": "http://localhost:8776/v2/0c2eba2c5af04d3f9e9d0d410b371fde/volumes/5aa119a8-d25b-45a7-8d1b-88e127885635",
                    "rel": "self"
                },
                {
                    "href": "http://localhost:8776/0c2eba2c5af04d3f9e9d0d410b371fde/volumes/5aa119a8-d25b-45a7-8d1b-88e127885635",
                    "rel": "bookmark"
                }
            ],
            "name": "vol-003"
        }
    ]
}

<?xml version='1.0' encoding='UTF-8'?>
<volumes xmlns:atom="http://www.w3.org/2005/Atom"
    xmlns="http://docs.openstack.org/api/openstack-block-storage/2.0/content">
    <volume name="vol-004" id="45baf976-c20a-4894-a7c3-c94b7376bf55">
        <attachments/>
        <metadata/>
    </volume>
    <volume name="vol-003" id="5aa119a8-d25b-45a7-8d1b-88e127885635">
        <attachments/>
        <metadata/>
    </volume>
</volumes>

GET

/v2/{tenant_id}/volumes/detail

List volumes (detailed)

Lists detailed information for all Block Storage volumes that the tenant who submits the request can access.

Normal response codes

200

Request parameters

Parameter	Style	Type	Description
tenant_id	URI	xsd:string	The unique identifier of the tenant or account.
sort (Optional)	query	xsd:string	Comma-separated list of sort keys and optional sort directions in the form of <key>[:<direction>]. A valid direction is `asc` (ascending) or `desc` (descending).
limit (Optional)	query	xsd:int	Requests a specified page size of returned items from the query. Returns a number of items up to the specified limit value. Use the `limit` parameter to make an initial limited request and use the ID of the last-seen item from the response as the `marker` parameter value in a subsequent limited request.
marker (Optional)	query	xsd:string	Specifies the ID of the last-seen item. Use the `limit` parameter to make an initial limited request and use the ID of the last-seen item from the response as the `marker` parameter value in a subsequent limited request.

Response parameters

Parameter	Style	Type	Description
status	plain	xsd:string	The volume status.
name	plain	xsd:string	The volume name.
attachments	plain	xsd:dict	One or more instance attachments.
availability_zone	plain	xsd:string	The availability zone.
created_at	plain	xsd:datetime	Date and time when the volume was created.
description	plain	xsd:string	The volume description.
volume_type	plain	xsd:string	The associated volume type.
snapshot_id	plain	csapi:uuid	The ID of the source volume snapshot.
source_volid	plain	csapi:uuid	The ID of the source volume.
metadata	plain	xsd:string	One or more metadata key and value pairs to associate with the volume.
id	plain	csapi:uuid	The volume ID.
size	plain	xsd:int	The size of the volume, in gibibytes (GiB).

{
    "volumes": [
        {
            "status": "available",
            "attachments": [],
            "links": [
                {
                    "href": "http://localhost:8776/v2/0c2eba2c5af04d3f9e9d0d410b371fde/volumes/45baf976-c20a-4894-a7c3-c94b7376bf55",
                    "rel": "self"
                },
                {
                    "href": "http://localhost:8776/0c2eba2c5af04d3f9e9d0d410b371fde/volumes/45baf976-c20a-4894-a7c3-c94b7376bf55",
                    "rel": "bookmark"
                }
            ],
            "availability_zone": "nova",
            "os-vol-host-attr:host": "ip-10-168-107-25",
            "source_volid": null,
            "snapshot_id": null,
            "id": "45baf976-c20a-4894-a7c3-c94b7376bf55",
            "description": "Another volume.",
            "name": "vol-004",
            "created_at": "2013-02-25T06:36:28.000000",
            "volume_type": "None",
            "os-vol-tenant-attr:tenant_id": "0c2eba2c5af04d3f9e9d0d410b371fde",
            "size": 1,
            "metadata": {
                "contents": "junk"
            }
        },
        {
            "status": "available",
            "attachments": [],
            "links": [
                {
                    "href": "http://localhost:8776/v2/0c2eba2c5af04d3f9e9d0d410b371fde/volumes/5aa119a8-d25b-45a7-8d1b-88e127885635",
                    "rel": "self"
                },
                {
                    "href": "http://localhost:8776/0c2eba2c5af04d3f9e9d0d410b371fde/volumes/5aa119a8-d25b-45a7-8d1b-88e127885635",
                    "rel": "bookmark"
                }
            ],
            "availability_zone": "nova",
            "os-vol-host-attr:host": "ip-10-168-107-25",
            "source_volid": null,
            "snapshot_id": null,
            "id": "5aa119a8-d25b-45a7-8d1b-88e127885635",
            "description": "This is yet, another volume.",
            "name": "vol-003",
            "created_at": "2013-02-25T02:40:21.000000",
            "volume_type": "None",
            "os-vol-tenant-attr:tenant_id": "0c2eba2c5af04d3f9e9d0d410b371fde",
            "size": 1,
            "metadata": {
                "contents": "not junk"
            }
        }
    ]
}

<?xml version='1.0' encoding='UTF-8'?>
<volumes
    xmlns:os-vol-image-meta="http://docs.openstack.org/openstack-block-storage/2.0/content/Volume_Image_Metadata.html"
    xmlns:os-vol-tenant-attr="http://docs.openstack.org/openstack-block-storage/2.0/content/Volume_Tenant_Attribute.html"
    xmlns:os-vol-host-attr="http://docs.openstack.org/openstack-block-storage/2.0/content/Volume_Host_Attribute.html"
    xmlns:atom="http://www.w3.org/2005/Atom"
    xmlns="http://docs.openstack.org/api/openstack-block-storage/2.0/content">
    <volume status="available" name="vol-004" availability_zone="nova"
        created_at="2013-02-25 06:36:28" description="Another volume."
        volume_type="None" source_volid="None" snapshot_id="None"
        id="45baf976-c20a-4894-a7c3-c94b7376bf55" size="1"
        os-vol-tenant-attr:tenant_id="0c2eba2c5af04d3f9e9d0d410b371fde"
        os-vol-host-attr:host="ip-10-168-107-25">
        <attachments/>
        <metadata>
            <meta key="contents">junk</meta>
        </metadata>
    </volume>
    <volume status="available" name="vol-003" availability_zone="nova"
        created_at="2013-02-25 02:40:21"
        description="This is yet, another volume." volume_type="None"
        source_volid="None" snapshot_id="None"
        id="5aa119a8-d25b-45a7-8d1b-88e127885635" size="1"
        os-vol-tenant-attr:tenant_id="0c2eba2c5af04d3f9e9d0d410b371fde"
        os-vol-host-attr:host="ip-10-168-107-25">
        <attachments/>
        <metadata>
            <meta key="contents">not junk</meta>
        </metadata>
    </volume>
</volumes>

GET

/v2/{tenant_id}/volumes/{volume_id}

Show volume information

Shows information about a specified volume.

Preconditions

The specified volume must exist.

Normal response codes

200

Request parameters

Parameter	Style	Type	Description
tenant_id	URI	xsd:string	The unique identifier of the tenant or account.
volume_id	URI	csapi:UUID	The unique identifier of an existing volume.

Response parameters

Parameter	Style	Type	Description
status	plain	xsd:string	The volume status.
name	plain	xsd:string	The volume name.
attachments	plain	xsd:dict	One or more instance attachments.
availability_zone	plain	xsd:string	The availability zone.
created_at	plain	xsd:datetime	Date and time when the volume was created.
description	plain	xsd:string	The volume description.
volume_type	plain	xsd:string	The associated volume type.
snapshot_id	plain	csapi:uuid	The ID of the source volume snapshot.
source_volid	plain	csapi:uuid	The ID of the source volume.
metadata	plain	xsd:string	One or more metadata key and value pairs to associate with the volume.
id	plain	csapi:uuid	The volume ID.
size	plain	xsd:int	The size of the volume, in gibibytes (GiB).

{
    "volume": {
        "status": "available",
        "attachments": [],
        "links": [
            {
                "href": "http://localhost:8776/v2/0c2eba2c5af04d3f9e9d0d410b371fde/volumes/5aa119a8-d25b-45a7-8d1b-88e127885635",
                "rel": "self"
            },
            {
                "href": "http://localhost:8776/0c2eba2c5af04d3f9e9d0d410b371fde/volumes/5aa119a8-d25b-45a7-8d1b-88e127885635",
                "rel": "bookmark"
            }
        ],
        "availability_zone": "nova",
        "bootable": "false",
        "os-vol-host-attr:host": "ip-10-168-107-25",
        "source_volid": null,
        "snapshot_id": null,
        "id": "5aa119a8-d25b-45a7-8d1b-88e127885635",
        "description": "Super volume.",
        "name": "vol-002",
        "created_at": "2013-02-25T02:40:21.000000",
        "volume_type": "None",
        "os-vol-tenant-attr:tenant_id": "0c2eba2c5af04d3f9e9d0d410b371fde",
        "size": 1,
        "metadata": {
            "contents": "not junk"
        }
    }
}

<?xml version='1.0' encoding='UTF-8'?>
<volume
    xmlns:os-vol-image-meta="http://docs.openstack.org/openstack-block-storage/2.0/content/Volume_Image_Metadata.html"
    xmlns:os-vol-tenant-attr="http://docs.openstack.org/openstack-block-storage/2.0/content/Volume_Tenant_Attribute.html"
    xmlns:os-vol-host-attr="http://docs.openstack.org/openstack-block-storage/2.0/content/Volume_Host_Attribute.html"
    xmlns:atom="http://www.w3.org/2005/Atom"
    xmlns="http://docs.openstack.org/api/openstack-block-storage/2.0/content"
    status="available" name="vol-003" availability_zone="nova"
    bootable="false" created_at="2013-02-25 02:40:21"
    description="This is yet, another volume." volume_type="None"
    source_volid="None" snapshot_id="None"
    id="5aa119a8-d25b-45a7-8d1b-88e127885635" size="1"
    os-vol-tenant-attr:tenant_id="0c2eba2c5af04d3f9e9d0d410b371fde"
    os-vol-host-attr:host="ip-10-168-107-25">
    <attachments/>
    <metadata>
        <meta key="contents">not junk</meta>
    </metadata>
</volume>

This operation does not accept a request body.

PUT

/v2/{tenant_id}/volumes/{volume_id}

Update volume

Updates a volume.

Normal response codes

200

Request parameters

Parameter	Style	Type	Description
tenant_id	URI	xsd:string	The unique identifier of the tenant or account.
volume_id	URI	csapi:UUID	The unique identifier of an existing volume.

Response parameters

Parameter	Style	Type	Description
status	plain	xsd:string	The volume status.
name	plain	xsd:string	The volume name.
attachments	plain	xsd:dict	One or more instance attachments.
availability_zone	plain	xsd:string	The availability zone.
created_at	plain	xsd:datetime	Date and time when the volume was created.
description	plain	xsd:string	The volume description.
volume_type	plain	xsd:string	The associated volume type.
snapshot_id	plain	csapi:uuid	The ID of the source volume snapshot.
source_volid	plain	csapi:uuid	The ID of the source volume.
metadata	plain	xsd:string	One or more metadata key and value pairs to associate with the volume.
id	plain	csapi:uuid	The volume ID.
size	plain	xsd:int	The size of the volume, in gibibytes (GiB).

{
    "volume": {
        "name": "vol-003",
        "description": "This is yet, another volume."
    }
}

<?xml version="1.0" encoding="UTF-8"?>
<snapshot
    xmlns="http://docs.openstack.org/openstack-block-storage/2.0/content"
    name="vol-003" description="This is yet, another volume."/>

{
    "volume": {
        "status": "available",
        "attachments": [],
        "links": [
            {
                "href": "http://localhost:8776/v2/0c2eba2c5af04d3f9e9d0d410b371fde/volumes/5aa119a8-d25b-45a7-8d1b-88e127885635",
                "rel": "self"
            },
            {
                "href": "http://localhost:8776/0c2eba2c5af04d3f9e9d0d410b371fde/volumes/5aa119a8-d25b-45a7-8d1b-88e127885635",
                "rel": "bookmark"
            }
        ],
        "availability_zone": "nova",
        "source_volid": null,
        "snapshot_id": null,
        "id": "5aa119a8-d25b-45a7-8d1b-88e127885635",
        "description": "This is yet, another volume.",
        "name": "vol-003",
        "created_at": "2013-02-25T02:40:21.000000",
        "volume_type": "None",
        "size": 1,
        "metadata": {
            "contents": "not junk"
        }
    }
}

<?xml version='1.0' encoding='UTF-8'?>
<volume xmlns:atom="http://www.w3.org/2005/Atom"
    xmlns="http://docs.openstack.org/api/openstack-block-storage/2.0/content"
    status="available" name="vol-003" availability_zone="nova"
    created_at="2013-02-25 02:40:21"
    description="This is yet, another volume." volume_type="None"
    source_volid="None" snapshot_id="None"
    id="5aa119a8-d25b-45a7-8d1b-88e127885635" size="1">
    <attachments/>
    <metadata>
        <meta key="contents">not junk</meta>
    </metadata>
</volume>

DELETE

/v2/{tenant_id}/volumes/{volume_id}

Delete volume

Deletes a specified volume.

Preconditions

Volume status must be available, in-use, error, or error_restoring.
You cannot already have a snapshot related to the specified volume.
You cannot delete a volume that is in a migration.

Asynchronous Postconditions

The volume is deleted in volume index.
The volume managed by OpenStack Block Storage is deleted in storage node.

Troubleshooting

If volume status remains in deleting or becomes error_deleting the request failed. Ensure you meet the preconditions then investigate the storage back end.
The volume managed by OpenStack Block Storage is not deleted from the storage system.

Normal response codes

202

Request parameters

Parameter	Style	Type	Description
tenant_id	URI	xsd:string	The unique identifier of the tenant or account.
volume_id	URI	csapi:UUID	The unique identifier of an existing volume.

This operation does not accept a request body and does not return a response body.

Volume actions

Performs actions for a specified volume. Extends the size, resets statuses for, sets image metadata, or removes image metadata from a volume.

POST

/v2/{tenant_id}/volumes/{volume_id}/action

Extend volume

Extends the size of a specified volume to a new size requested in gibibytes (GiB). Specify the os-extend action in the request body.

Preconditions

Volume status must be available.

Sufficient amount of storage must exist to extend the volume.

The user quota must have sufficient volume storage.

Troubleshooting

An error_extending volume status indicates that the request failed. Ensure that you meet the preconditions and retry the request. If the request fails again, investigate the storage back end.

Normal response codes

202

Request parameters

Parameter	Style	Type	Description
tenant_id	URI	xsd:string	The unique identifier of the tenant or account.
volume_id	URI	csapi:UUID	The unique identifier of an existing volume.
new_size	plain	xsd:int	The new size of the volume, in gibibytes (GiB).

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

This operation does not return a response body.

POST

/v2/{tenant_id}/volumes/{volume_id}/action

Reset volume statuses

Resets the status, attach status, and migration status for a specified volume. Specify the os-reset_status action in the request body.

Normal response codes

202

Request parameters

Parameter	Style	Type	Description
tenant_id	URI	xsd:string	The unique identifier of the tenant or account.
volume_id	URI	csapi:UUID	The unique identifier of an existing volume.
status (Optional)	plain	xsd:string	The volume status.
attach_status (Optional)	plain	xsd:string	The volume attach status.
migration_status (Optional)	plain	xsd:string	The volume migration status.

{
    "os-reset_status": {
        "status": "available",
        "attach_status": "detached",
        "migration_status": "migrating"
    }
}

This operation does not return a response body.

POST

/v2/{tenant_id}/volumes/{volume_id}/action

Set image metadata for volume

Sets the image metadata for a specified volume. Specify the os-set_image_metadata action in the request body.

Normal response codes

202

Request parameters

Parameter	Style	Type	Description
tenant_id	URI	xsd:string	The unique identifier of the tenant or account.
volume_id	URI	csapi:UUID	The unique identifier of an existing volume.
os-set_image_metadata	plain	xsd:string	The `os-set_image_metadata` action.
metadata	plain	xsd:string	The image metadata to add to the volume as a set of metadata key and value pairs.

{
    "os-set_image_metadata": {
        "metadata": {
            "image_id": "521752a6-acf6-4b2d-bc7a-119f9148cd8c",
            "image_name": "image",
            "kernel_id": "155d900f-4e14-4e4c-a73d-069cbf4541e6",
            "ramdisk_id": "somedisk"
        }
    }
}

This operation does not return a response body.

POST

/v2/{tenant_id}/volumes/{volume_id}/action

Remove image metadata from volume

Removes image metadata, by key, from a specified volume. Specify the os-unset_image_metadata action in the request body and the key for the metadata key and value pair that you want to remove.

Normal response codes

202

Request parameters

Parameter	Style	Type	Description
tenant_id	URI	xsd:string	The unique identifier of the tenant or account.
volume_id	URI	csapi:UUID	The unique identifier of an existing volume.
os-unset_image_metadata	plain	xsd:string	The `os-unset_image_metadata` action.
key	plain	xsd:string	The metadata key name for the metadata that you want to remove.

{
    "os-unset_image_metadata": {
        "key": "ramdisk_id"
    }
}

This operation does not return a response body.

POST

/v2/{tenant_id}/volumes/{volume_id}/action

Attach volume

Attaches the specified volume to the specified server. Specify the os-attach action in the request body.

Preconditions

Volume status must be available.
You should set instance_uuid or host_name.

Normal response codes

202

Request parameters

Parameter	Style	Type	Description
tenant_id	URI	xsd:string	The unique identifier of the tenant or account.
volume_id	URI	csapi:UUID	The unique identifier of an existing volume.
os-attach	plain	xsd:string	The `os-attach` action.
instance_uuid (Optional)	plain	csapi:UUID	The UUID of the attaching instance.
host_name (Optional)	plain	xsd:string	The name of the attaching host.
mountpoint (Optional)	plain	xsd:string	The attaching mountpoint.

{
    "os-attach": {
        "instance_uuid": "95D9EF50-507D-11E5-B970-0800200C9A66",
        "host_name": "cinder-2",
        "mountpoint": "/dev/vdc"
    }
}

This operation does not return a response body.

Volume types

GET

/v2/{tenant_id}/types

List volume types

Lists volume types.

Normal response codes

200

Request parameters

Parameter	Style	Type	Description
tenant_id	URI	xsd:string	The unique identifier of the tenant or account.

{
    "volume_types": [
        {
            "extra_specs": {
                "capabilities": "gpu"
            },
            "id": "6685584b-1eac-4da6-b5c3-555430cf68ff",
            "name": "SSD"
        },
        {
            "extra_specs": {},
            "id": "8eb69a46-df97-4e41-9586-9a40a7533803",
            "name": "SATA"
        }
    ]
}

<?xml version="1.0" encoding="UTF-8"?>
<volume_types
    xmlns="http://docs.openstack.org/openstack-block-storage/2.0/content">
    <volume_type id="6685584b-1eac-4da6-b5c3-555430cf68ff" name="SSD">
        <extra_specs>
            <extra_spec key="capabilities">gpu</extra_spec>
        </extra_specs>
    </volume_type>
    <volume_type id="8eb69a46-df97-4e41-9586-9a40a7533803" name="SATA"
    />
</volume_types>

This operation does not accept a request body.

POST

/v2/{tenant_id}/types

Create volume type

Creates a volume type.

Normal response codes

200

Request parameters

Parameter	Style	Type	Description
tenant_id	URI	xsd:string	The unique identifier of the tenant or account.

{
    "volume_type": {
        "name": "vol-type-001",
        "extra_specs": {
            "capabilities": "gpu"
        }
    }
}

<?xml version="1.0" encoding="UTF-8"?>
<volume_type xmlns="http://docs.openstack.org/volume/api/v1"
        name="vol-type-001">
        <extra_specs>
            <extra_spec key="capabilities">gpu</extra_spec>
        </extra_specs>
</volume_type>

{
    "volume_type": {
        "id": "6685584b-1eac-4da6-b5c3-555430cf68ff",
        "name": "vol-type-001",
        "extra_specs": {
            "capabilities": "gpu"
        }
    }
}

<?xml version="1.0" encoding="UTF-8"?>
<volume_type
    xmlns="http://docs.openstack.org/openstack-block-storage/2.0/content"
    id="6685584b-1eac-4da6-b5c3-555430cf68ff" name="vol-type-001">
    <extra_specs>
        <extra_spec key="capabilities">gpu</extra_spec>
    </extra_specs>
</volume_type>

PUT

/v2/{tenant_id}/types/{volume_type_id}

Update volume type

Updates a volume type.

Normal response codes

200

Request parameters

Parameter	Style	Type	Description
tenant_id	URI	xsd:string	The unique identifier of the tenant or account.
volume_type_id	URI	csapi:UUID	The unique identifier for an existing volume type.
volume_type	plain	csapi:string	A volume type offers a way to categorize or group volumes.

{
    "volume_type": {
        "name": "vol-type-001",
        "extra_specs": {
            "capabilities": "gpu"
        }
    }
}

<?xml version="1.0" encoding="UTF-8"?>
<volume_type xmlns="http://docs.openstack.org/volume/api/v1"
        name="vol-type-001">
        <extra_specs>
            <extra_spec key="capabilities">gpu</extra_spec>
        </extra_specs>
</volume_type>

{
    "volume_type": {
        "id": "289da7f8-6440-407c-9fb4-7db01ec49164",
        "name": "vol-type-001",
        "extra_specs": {
            "capabilities": "gpu"
        }
    }
}

<?xml version="1.0" encoding="UTF-8"?>
<volume_type xmlns="http://docs.openstack.org/volume/api/v1"
             id="289da7f8-6440-407c-9fb4-7db01ec49164"
             name="vol-type-001">
    <extra_specs>
        <extra_spec key="capabilities">gpu</extra_spec>
    </extra_specs>
</volume_type>

PUT

/v2/{tenant_id}/types/{volume_type_id}

Update extra specs for a volume type

Updates the extra specifications assigned to a volume type.

Normal response codes

200

Request parameters

Parameter	Style	Type	Description
tenant_id	URI	xsd:string	The unique identifier of the tenant or account.
volume_type_id	URI	csapi:UUID	The unique identifier for an existing volume type.
volume_type	plain	csapi:string	A volume type offers a way to categorize or group volumes.
extra_specs	plain	csapi:string	A key:value pair that offers a way to show additional specifications associated with the volume type. Examples include capabilities, capacity, compression, and so on, depending on the storage driver in use.

{
    "volume_type": {
        "name": "vol-type-001",
        "extra_specs": {
            "capabilities": "gpu"
        }
    }
}

<?xml version="1.0" encoding="UTF-8"?>
<volume_type xmlns="http://docs.openstack.org/volume/api/v1"
        name="vol-type-001">
        <extra_specs>
            <extra_spec key="capabilities">gpu</extra_spec>
        </extra_specs>
</volume_type>

{
    "volume_type": {
        "id": "289da7f8-6440-407c-9fb4-7db01ec49164",
        "name": "vol-type-001",
        "extra_specs": {
            "capabilities": "gpu"
        }
    }
}

<?xml version="1.0" encoding="UTF-8"?>
<volume_type xmlns="http://docs.openstack.org/volume/api/v1"
             id="289da7f8-6440-407c-9fb4-7db01ec49164"
             name="vol-type-001">
    <extra_specs>
        <extra_spec key="capabilities">gpu</extra_spec>
    </extra_specs>
</volume_type>

GET

/v2/{tenant_id}/types/{volume_type_id}

Show volume type information

Shows information about a specified volume type.

Normal response codes

200

Request parameters

Parameter	Style	Type	Description
tenant_id	URI	xsd:string	The unique identifier of the tenant or account.
volume_type_id	URI	csapi:UUID	The unique identifier for an existing volume type.

{
    "volume_type": {
        "id": "6685584b-1eac-4da6-b5c3-555430cf68ff",
        "name": "vol-type-001",
        "extra_specs": {
            "capabilities": "gpu"
        }
    }
}

<?xml version="1.0" encoding="UTF-8"?>
<volume_type
    xmlns="http://docs.openstack.org/openstack-block-storage/2.0/content"
    id="6685584b-1eac-4da6-b5c3-555430cf68ff" name="vol-type-001">
    <extra_specs>
        <extra_spec key="capabilities">gpu</extra_spec>
    </extra_specs>
</volume_type>

This operation does not accept a request body.

DELETE

/v2/{tenant_id}/types/{volume_type_id}

Delete volume type

Deletes a specified volume type.

Normal response codes

202

Request parameters

Parameter	Style	Type	Description
tenant_id	URI	xsd:string	The unique identifier of the tenant or account.
volume_type_id	URI	csapi:UUID	The unique identifier for an existing volume type.

This operation does not accept a request body and does not return a response body.

Snapshots

A snapshot is a point-in-time copy of the data that a volume contains.

When you create, list, or delete snapshots, these status values are possible:

Snapshot statuses
Status	Description
creating	The snapshot is being created.
available	The snapshot is ready to be used.
deleting	The snapshot is being deleted.
error	An error occurred during snapshot creation.
error_deleting	An error occurred during snapshot deletion.

POST

/v2/{tenant_id}/snapshots

Create snapshot

Creates a snapshot, which is a point-in-time complete copy of a volume. You can create a volume from the snapshot.

Normal response codes

202

Request parameters

Parameter	Style	Type	Description
tenant_id	URI	xsd:string	The unique identifier of the tenant or account.
snapshot	query	string	A partial representation of a snapshot used in the creation process.
volume_id	query	string	To create a snapshot from an existing volume, specify the ID of the existing volume.
force (Optional)	query	xsd:boolean	[True/False] Indicate whether to snapshot, even if the volume is attached. Default==False.
name (Optional)	query	string	Name of the snapshot. Default==None.
description (Optional)	query	string	Description of snapshot. Default==None.

Response parameters

Parameter	Style	Type	Description
size	plain	xsd:int	The size of the volume, in gibibytes (GiB).

{
    "snapshot": {
        "name": "snap-001",
        "description": "Daily backup",
        "volume_id": "5aa119a8-d25b-45a7-8d1b-88e127885635",
        "force": true
    }
}

<?xml version="1.0" encoding="UTF-8"?>
<snapshot
    xmlns="http://docs.openstack.org/openstack-block-storage/2.0/content"
    name="snap-001" description="Daily backup"
    volume_id="5aa119a8-d25b-45a7-8d1b-88e127885635" force="true"/>

{
    "snapshot": {
        "status": "creating",
        "description": "Daily backup",
        "created_at": "2013-02-25T03:56:53.081642",
        "metadata": {},
        "volume_id": "5aa119a8-d25b-45a7-8d1b-88e127885635",
        "size": 1,
        "id": "ffa9bc5e-1172-4021-acaf-cdcd78a9584d",
        "name": "snap-001"
    }
}

<?xml version='1.0' encoding='UTF-8'?>
<snapshot status="creating" description="Daily backup"
    created_at="2013-02-25T03:56:53.081642"
    volume_id="5aa119a8-d25b-45a7-8d1b-88e127885635" size="1"
    id="ffa9bc5e-1172-4021-acaf-cdcd78a9584d" name="snap-001">
    <metadata/>
</snapshot>

GET

/v2/{tenant_id}/snapshots

List snapshots

Lists summary information for all Block Storage snapshots that the tenant who submits the request can access.

Normal response codes

200

Request parameters

Parameter	Style	Type	Description
tenant_id	URI	xsd:string	The unique identifier of the tenant or account.
sort_key (Optional)	query	xsd:string	Sorts by the requested image attribute. Accepted values are `name`, `status`, `container_format`, `disk_format`, `size`, `id`, `created_at`, and `updated_at`. Default is `created_at`. The API uses the natural sorting direction of the image attribute that is provided as the `sort_key`.
sort_dir (Optional)	query	xsd:string	Sorts by one or more sets of attribute and sort direction combinations. If you omit the sort direction in a set, default is `desc`.
limit (Optional)	query	xsd:int	Requests a specified page size of returned items from the query. Returns a number of items up to the specified limit value. Use the `limit` parameter to make an initial limited request and use the ID of the last-seen item from the response as the `marker` parameter value in a subsequent limited request.
marker (Optional)	query	xsd:string	Specifies the ID of the last-seen item. Use the `limit` parameter to make an initial limited request and use the ID of the last-seen item from the response as the `marker` parameter value in a subsequent limited request.

{
    "snapshots": [
        {
            "status": "available",
            "description": "Very important",
            "created_at": "2013-02-25T04:13:17.000000",
            "metadata": {},
            "volume_id": "5aa119a8-d25b-45a7-8d1b-88e127885635",
            "size": 1,
            "id": "2bb856e1-b3d8-4432-a858-09e4ce939389",
            "name": "snap-001"
        },
        {
            "status": "available",
            "description": "Weekly backup",
            "created_at": "2013-02-25T07:20:38.000000",
            "metadata": {},
            "volume_id": "806092e3-7551-4fff-a005-49016f4943b1",
            "size": 1,
            "id": "e820db06-58b5-439d-bac6-c01faa3f6499",
            "name": "snap-002"
        }
    ]
}

<?xml version='1.0' encoding='UTF-8'?>
<snapshots>
    <snapshot status="available" description="Very important"
        created_at="2013-02-25 04:13:17"
        volume_id="5aa119a8-d25b-45a7-8d1b-88e127885635" size="1"
        id="2bb856e1-b3d8-4432-a858-09e4ce939389" name="snap-001">
        <metadata/>
    </snapshot>
    <snapshot status="available" description="Weekly backup"
        created_at="2013-02-25 07:20:38"
        volume_id="806092e3-7551-4fff-a005-49016f4943b1" size="1"
        id="e820db06-58b5-439d-bac6-c01faa3f6499" name="snap-002">
        <metadata/>
    </snapshot>
</snapshots>

GET

/v2/{tenant_id}/snapshots/detail

List snapshots (detailed)

Lists detailed information for all Block Storage snapshots that the tenant who submits the request can access.

Normal response codes

200

Request parameters

Parameter	Style	Type	Description
tenant_id	URI	xsd:string	The unique identifier of the tenant or account.

{
    "snapshots": [
        {
            "status": "available",
            "os-extended-snapshot-attributes:progress": "100%",
            "description": "Daily backup",
            "created_at": "2013-02-25T07:30:12.000000",
            "metadata": {},
            "volume_id": "5aa119a8-d25b-45a7-8d1b-88e127885635",
            "os-extended-snapshot-attributes:project_id": "0c2eba2c5af04d3f9e9d0d410b371fde",
            "size": 30,
            "id": "43f20e0e-2c2c-4770-9d4e-c3d769ae5470",
            "name": "snap-001"
        },
        {
            "status": "available",
            "os-extended-snapshot-attributes:progress": "100%",
            "description": "Weekly backup",
            "created_at": "2013-02-25T07:20:38.000000",
            "metadata": {},
            "volume_id": "806092e3-7551-4fff-a005-49016f4943b1",
            "os-extended-snapshot-attributes:project_id": "0c2eba2c5af04d3f9e9d0d410b371fde",
            "size": 1,
            "id": "e820db06-58b5-439d-bac6-c01faa3f6499",
            "name": "snap-002"
        }
    ]
}

<?xml version='1.0' encoding='UTF-8'?>
<snapshots
    xmlns:os-extended-snapshot-attributes="http://docs.openstack.org/openstack-block-storage/2.0/content/Extended_Snapshot_Attributes.html">
    <snapshot status="available" description="Daily backup"
        created_at="2013-02-25 07:30:12"
        volume_id="5aa119a8-d25b-45a7-8d1b-88e127885635" size="30"
        id="43f20e0e-2c2c-4770-9d4e-c3d769ae5470" name="snap-001"
        os-extended-snapshot-attributes:project_id="0c2eba2c5af04d3f9e9d0d410b371fde"
        os-extended-snapshot-attributes:progress="100%">
        <metadata/>
    </snapshot>
    <snapshot status="available" description="Weekly backup"
        created_at="2013-02-25 07:20:38"
        volume_id="806092e3-7551-4fff-a005-49016f4943b1" size="1"
        id="e820db06-58b5-439d-bac6-c01faa3f6499" name="snap-002"
        os-extended-snapshot-attributes:project_id="0c2eba2c5af04d3f9e9d0d410b371fde"
        os-extended-snapshot-attributes:progress="100%">
        <metadata/>
    </snapshot>
</snapshots>

This operation does not accept a request body.

GET

/v2/{tenant_id}/snapshots/{snapshot_id}

Show snapshot information

Shows information for a specified snapshot.

Normal response codes

200

Request parameters

Parameter	Style	Type	Description
tenant_id	URI	xsd:string	The unique identifier of the tenant or account.
snapshot_id	URI	csapi:UUID	The unique identifier of an existing snapshot.

{
    "snapshot": {
        "status": "available",
        "os-extended-snapshot-attributes:progress": "100%",
        "description": "Daily backup",
        "created_at": "2013-02-25T04:13:17.000000",
        "metadata": {},
        "volume_id": "5aa119a8-d25b-45a7-8d1b-88e127885635",
        "os-extended-snapshot-attributes:project_id": "0c2eba2c5af04d3f9e9d0d410b371fde",
        "size": 1,
        "id": "2bb856e1-b3d8-4432-a858-09e4ce939389",
        "name": "snap-001"
    }
}

<?xml version='1.0' encoding='UTF-8'?>
<snapshot
  xmlns:os-extended-snapshot-attributes="http://docs.openstack.org/openstack-block-storage/2.0/content/Extended_Snapshot_Attributes.html"
  status="available" description="Very important"
  created_at="2013-02-25 04:13:17"
  volume_id="5aa119a8-d25b-45a7-8d1b-88e127885635" size="1"
  id="2bb856e1-b3d8-4432-a858-09e4ce939389" name="snap-001"
  os-extended-snapshot-attributes:project_id="0c2eba2c5af04d3f9e9d0d410b371fde"
  os-extended-snapshot-attributes:progress="100%">
  <metadata/>
</snapshot>

This operation does not accept a request body.

PUT

/v2/{tenant_id}/snapshots/{snapshot_id}

Update snapshot

Updates a specified snapshot.

Normal response codes

200

Request parameters

Parameter	Style	Type	Description
tenant_id	URI	xsd:string	The unique identifier of the tenant or account.
snapshot_id	URI	csapi:UUID	The unique identifier of an existing snapshot.

{
    "snapshot": {
        "name": "snap-002",
        "description": "This is yet, another snapshot."
    }
}

<?xml version="1.0" encoding="UTF-8"?>
<snapshot
    xmlns="http://docs.openstack.org/openstack-block-storage/2.0/content"
    name="snap-002" description="This is yet, another snapshot."/>

{
    "snapshot": {
        "created_at": "2013-02-20T08:11:34.000000",
        "description": "This is yet, another snapshot",
        "name": "snap-002",
        "id": "4b502fcb-1f26-45f8-9fe5-3b9a0a52eaf2",
        "size": 1,
        "status": "available",
        "volume_id": "2402b902-0b7a-458c-9c07-7435a826f794"
    }
}

<?xml version='1.0' encoding='UTF-8'?>
<snapshot
  xmlns:os-extended-snapshot-attributes="http://docs.openstack.org/openstack-block-storage/2.0/content/Extended_Snapshot_Attributes.html"
    status="available"
    description="This is yet, another snapshot"
    created_at="2013-02-20T08:11:34.000000"
    volume_id="2402b902-0b7a-458c-9c07-7435a826f794"
    size="1"
    id="4b502fcb-1f26-45f8-9fe5-3b9a0a52eaf2"
    name="snap-002"
    os-extended-snapshot-attributes:project_id="0c2eba2c5af04d3f9e9d0d410b371fde"
    os-extended-snapshot-attributes:progress="100%">
    <metadata/>
</snapshot>

DELETE

/v2/{tenant_id}/snapshots/{snapshot_id}

Delete snapshot

Deletes a specified snapshot.

Normal response codes

202

Request parameters

Parameter	Style	Type	Description
tenant_id	URI	xsd:string	The unique identifier of the tenant or account.
snapshot_id	URI	csapi:UUID	The unique identifier of an existing snapshot.

This operation does not accept a request body and does not return a response body.

GET

/v2/{tenant_id}/snapshots/{snapshot_id}/metadata

Show snapshot metadata

Shows the metadata for a specified snapshot.

Normal response codes

200

Request parameters

Parameter	Style	Type	Description
tenant_id	URI	xsd:string	The unique identifier of the tenant or account.
snapshot_id	URI	csapi:UUID	The unique identifier of an existing snapshot.

{
    "snapshot": {
        "status": "available",
        "os-extended-snapshot-attributes:progress": "0%",
        "description": null,
        "created_at": "2014-05-06T17:59:52.000000",
        "metadata": {
            "key": "v2"
        },
        "volume_id": "ebd80b99-bc3d-4154-9d28-5583baa80580",
        "os-extended-snapshot-attributes:project_id": "7e0105e19cd2466193729ef78b604f79",
        "size": 10,
        "id": "dfcd17fe-3b64-44ba-b95f-1c9c7109ef95",
        "name": "my-snapshot"
    }
}

<?xml version='1.0' encoding='UTF-8'?>
<snapshot
    xmlns:os-extended-snapshot-attributes="http://docs.openstack.org/volume/ext/extended_snapshot_attributes/api/v1"
    status="available" description="None"
    created_at="2014-05-06 17:59:52"
    volume_id="ebd80b99-bc3d-4154-9d28-5583baa80580" size="10"
    id="dfcd17fe-3b64-44ba-b95f-1c9c7109ef95" name="my-snapshot"
    os-extended-snapshot-attributes:project_id="7e0105e19cd2466193729ef78b604f79"
    os-extended-snapshot-attributes:progress="0%">
    <metadata>
        <meta key="key">v2</meta>
    </metadata>
</snapshot>

This operation does not accept a request body.

PUT

/v2/{tenant_id}/snapshots/{snapshot_id}/metadata

Update snapshot metadata

Updates the metadata for a specified snapshot.

Normal response codes

200

Request parameters

Parameter	Style	Type	Description
tenant_id	URI	xsd:string	The unique identifier of the tenant or account.
snapshot_id	URI	csapi:UUID	The unique identifier of an existing snapshot.

{
    "metadata": {
        "key": "v2"
    }
}

<?xml version='1.0' encoding='UTF-8'?>
<metadata>
    <meta key="key">v2</meta>
</metadata>

{
    "metadata": {
        "key": "v2"
    }
}

<?xml version='1.0' encoding='UTF-8'?>
<metadata xmlns="http://docs.openstack.org/compute/api/v1.1">
    <meta key="key">v2</meta>
</metadata>

Quality of service (QoS) specifications (qos-specs)

Administrators only, depending on policy settings.

Creates, lists, shows details for, associates, disassociates, sets keys, unsets keys, and deletes quality of service (QoS) specifications.

POST

/v2/{tenant_id}/qos-specs

Create QoS specification

Creates a QoS specification.

Normal response codes

202

Request parameters

Parameter	Style	Type	Description
tenant_id	URI	xsd:string	The unique ID of the tenant or account.
qos_specs	plain	xsd:string	A `qos_specs` object.
name	plain	xsd:string	The name of the QoS specification.
specs	plain	xsd:string	Specification key and value pairs.

Response parameters

Parameter	Style	Type	Description
qos_specs	plain	xsd:string	A `qos_specs` object.
specs	plain	xsd:string	A `specs` object.
consumer	plain	xsd:string	The consumer type.
name	plain	xsd:string	The name of the QoS specification.
id	plain	csapi:uuid	The generated ID for the QoS specification.
links	plain	xsd:dict	The QoS specification links.

{
    "qos_specs": {
        "availability": "100",
        "name": "reliability-spec",
        "numberOfFailures": "0"
    }
}

<?xml version="1.0" encoding="UTF-8"?>
<qos_specs name="performance-spec" delay="0" throughput="100"/>

{
    "qos_specs": {
        "specs": {
            "availability": "100",
            "numberOfFailures": "0"
        },
        "consumer": "back-end",
        "name": "reliability-spec",
        "id": "0388d6c6-d5d4-42a3-b289-95205c50dd15"
    },
    "links": [
        {
            "href": "http://23.253.228.211:8776/v2/e1cf63117ae74309a5bcc2002a23be8b/qos_specs/0388d6c6-d5d4-42a3-b289-95205c50dd15",
            "rel": "self"
        },
        {
            "href": "http://23.253.228.211:8776/e1cf63117ae74309a5bcc2002a23be8b/qos_specs/0388d6c6-d5d4-42a3-b289-95205c50dd15",
            "rel": "bookmark"
        }
    ]
}

<?xml version='1.0' encoding='UTF-8'?>
<qos_specs>
    <qos_spec consumer="back-end"
        id="ecfc6e2e-7117-44a4-8eec-f84d04f531a8"
        name="performance-spec">
        <specs>
            <delay>0</delay>
            <throughput>100</throughput>
        </specs>
    </qos_spec>
</qos_specs>

GET

/v2/{tenant_id}/qos-specs

List QoS specs

Lists quality of service (QoS) specifications.

Normal response codes

200, 300

Request parameters

Parameter	Style	Type	Description
tenant_id	URI	xsd:string	The unique ID of the tenant or account.

Response parameters

Parameter	Style	Type	Description
qos_specs	plain	xsd:string	A `qos_specs` object.
specs	plain	xsd:string	Specification key and value pairs.
consumer	plain	xsd:string	The consumer type.
name	plain	xsd:string	The name of the QoS specification.
id	plain	csapi:uuid	The generated ID for the QoS specification.

{
    "qos_specs": [
        {
            "specs": {
                "availability": "100",
                "numberOfFailures": "0"
            },
            "consumer": "back-end",
            "name": "reliability-spec",
            "id": "0388d6c6-d5d4-42a3-b289-95205c50dd15"
        },
        {
            "specs": {
                "delay": "0",
                "throughput": "100"
            },
            "consumer": "back-end",
            "name": "performance-spec",
            "id": "ecfc6e2e-7117-44a4-8eec-f84d04f531a8"
        }
    ]
}

<?xml version='1.0' encoding='UTF-8'?>
<qos_specs>
    <qos_spec consumer="back-end"
        id="0388d6c6-d5d4-42a3-b289-95205c50dd15"
        name="reliability-spec">
        <specs>
            <availability>100</availability>
            <numberOfFailures>0</numberOfFailures>
        </specs>
    </qos_spec>
    <qos_spec consumer="back-end"
        id="ecfc6e2e-7117-44a4-8eec-f84d04f531a8"
        name="performance-spec">
        <specs>
            <delay>0</delay>
            <throughput>100</throughput>
        </specs>
    </qos_spec>
</qos_specs>

This operation does not accept a request body.

GET

/v2/{tenant_id}/qos-specs/{qos_id}

Show QoS specification details

Shows details for a specified QoS specification.

Normal response codes

200

Error response codes

computeFault (400, 500, …), serviceUnavailable (503), badRequest (400), unauthorized (401), forbidden (403), badMethod (405), overLimit (413), itemNotFound (404)

Request parameters

Parameter	Style	Type	Description
tenant_id	URI	xsd:string	The unique ID of the tenant or account.
qos_id	URI	csapi:UUID	The UUID for the QoS specification.

Response parameters

Parameter	Style	Type	Description
qos_specs	plain	xsd:string	A `qos_specs` object.
specs	plain	xsd:string	Specification key and value pairs.
consumer	plain	xsd:string	The consumer type.
name	plain	xsd:string	The name of the QoS specification.
id	plain	csapi:uuid	The generated ID for the QoS specification.
links	plain	xsd:dict	The QoS specification links.

{
    "qos_specs": {
        "specs": {
            "availability": "100",
            "numberOfFailures": "0"
        },
        "consumer": "back-end",
        "name": "reliability-spec",
        "id": "0388d6c6-d5d4-42a3-b289-95205c50dd15"
    },
    "links": [
        {
            "href": "http://23.253.228.211:8776/v2/e1cf63117ae74309a5bcc2002a23be8b/qos_specs/0388d6c6-d5d4-42a3-b289-95205c50dd15",
            "rel": "self"
        },
        {
            "href": "http://23.253.228.211:8776/e1cf63117ae74309a5bcc2002a23be8b/qos_specs/0388d6c6-d5d4-42a3-b289-95205c50dd15",
            "rel": "bookmark"
        }
    ]
}

<?xml version='1.0' encoding='UTF-8'?>
<qos_specs>
    <qos_spec consumer="back-end"
        id="0388d6c6-d5d4-42a3-b289-95205c50dd15"
        name="reliability-spec">
        <specs>
            <availability>100</availability>
            <numberOfFailures>0</numberOfFailures>
        </specs>
    </qos_spec>
</qos_specs>

This operation does not accept a request body.

PUT

/v2/{tenant_id}/qos-specs/{qos_id}

Set or unset keys in QoS specification

Sets or unsets keys in a specified QoS specification.

Normal response codes

200

Request parameters

Parameter	Style	Type	Description
tenant_id	URI	xsd:string	The unique ID of the tenant or account.
qos_id	URI	csapi:UUID	The UUID for the QoS specification.
qos_specs	plain	xsd:string	A `qos_specs` object.
specs	plain	xsd:string	Specification key and value pairs.

{
    "qos_specs": {
        "delay": "1"
    }
}

<?xml version="1.0" encoding="UTF-8"?>
<qos_specs delay="2" throughput="100"/>

{
    "qos_specs": {
        "delay": "1"
    }
}

<?xml version='1.0' encoding='UTF-8'?>
<qos_specs>
    <qos_spec/>
</qos_specs>

DELETE

/v2/{tenant_id}/qos-specs/{qos_id}

Delete QoS specification

Deletes a specified QoS specification.

Normal response codes

202

Request parameters

Parameter	Style	Type	Description
tenant_id	URI	xsd:string	The unique ID of the tenant or account.
qos_id	URI	csapi:UUID	The UUID for the QoS specification.
qos_id	URI	xsd:string	The unique ID of the QoS specification.
force	URI	String	Optional flag that indicates whether to delete the specified QoS specification even if it is in-use.

This operation does not return a response body.

GET

/v2/{tenant_id}/qos-specs/{qos_id}/associate

Associate QoS specification with volume type

Associates a QoS specification with a specified volume type.

Normal response codes

202

Request parameters

Parameter	Style	Type	Description
tenant_id	URI	xsd:string	The unique ID of the tenant or account.
qos_id	URI	csapi:UUID	The UUID for the QoS specification.
vol_type_id (Optional)	query	xsd:string	The unique ID of the volume type.

This operation does not accept a request body and does not return a response body.

GET

/v2/{tenant_id}/qos-specs/{qos_id}/disassociate

Disassociate QoS specification from volume type

Disassociates a QoS specification from a specified volume type.

Normal response codes

202

Request parameters

Parameter	Style	Type	Description
tenant_id	URI	xsd:string	The unique ID of the tenant or account.
qos_id	URI	csapi:UUID	The UUID for the QoS specification.
vol_type_id (Optional)	query	xsd:string	The unique ID of the volume type.

This operation does not accept a request body and does not return a response body.

GET

/v2/{tenant_id}/qos-specs/{qos_id}/disassociate_all

Disassociate QoS specification from all associations

Disassociates a specified QoS specification from all associations.

Normal response codes

202

Request parameters

Parameter	Style	Type	Description
tenant_id	URI	xsd:string	The unique ID of the tenant or account.
qos_id	URI	csapi:UUID	The UUID for the QoS specification.

This operation does not accept a request body and does not return a response body.

GET

/v2/{tenant_id}/qos-specs/{qos_id}/associations

Get all associations for QoS specification

Gets all associations for a specified QoS specification.

Normal response codes

200

Request parameters

Parameter	Style	Type	Description
tenant_id	URI	xsd:string	The unique ID of the tenant or account.
qos_id	URI	csapi:UUID	The UUID for the QoS specification.

{
    "qos_associations": [
        {
            "association_type": "volume_type",
            "name": "reliability-type",
            "id": "a12983c2-83bd-4afa-be9f-ad796573ead6"
        }
    ]
}

<?xml version='1.0' encoding='UTF-8'?>
<qos_associations>
    <associations association_type="volume_type"
        name="reliability-type"
        id="a12983c2-83bd-4afa-be9f-ad796573ead6"/>
</qos_associations>

This operation does not accept a request body.

Quota sets extension (os-quota-sets)

Administrators only, depending on policy settings.

Shows, updates, and deletes quotas for a tenant.

GET

/v2/{tenant_id}/os-quota-sets/{tenant_id}

Show quotas

Shows quotas for a tenant.

Normal response codes

200

Request parameters

Parameter	Style	Type	Description
tenant_id	URI	xsd:string	The ID for the tenant or project in a multi-tenancy cloud.
tenant_id	URI	xsd:string	The ID for the tenant for which you want to show, update, or delete quotas. This ID is different from the first tenant ID that you specify in the URI: That ID is for the admin tenant.
usage (Optional)	query	xsd:boolean	Set to `usage=True` to show quota usage. Default is `False`.

Response parameters

Parameter	Style	Type	Description
quota_set	plain	xsd:string	A `quota_set` object.
gigabytes	plain	xsd:int	The number of gigabytes allowed for each tenant.
snapshots	plain	xsd:int	The number of snapshots allowed for each tenant.
volumes	plain	xsd:int	The number of volumes allowed for each tenant.
in_use (Optional)	plain	xsd:string	The in use data size. Visible only if you set the `usage=True` query parameter.
reserved (Optional)	plain	xsd:int	Reserved volume size. Visible only if you set the `usage=True` query parameter.

{
    "quota_set": {
        "gigabytes": 5,
        "snapshots": 10,
        "volumes": 20
    }
}

<?xml version='1.0' encoding='UTF-8'?>
<quota_set id="fake_tenant">
  <gigabytes>5</gigabytes>
  <snapshots>10</snapshots>
  <volumes>20</volumes>
</quota_set>

PUT

/v2/{tenant_id}/os-quota-sets/{tenant_id}

Update quotas

Updates quotas for a tenant.

Normal response codes

200

Request parameters

Parameter	Style	Type	Description
tenant_id	URI	xsd:string	The ID for the tenant or project in a multi-tenancy cloud.
tenant_id	URI	xsd:string	The ID for the tenant for which you want to show, update, or delete quotas. This ID is different from the first tenant ID that you specify in the URI: That ID is for the admin tenant.
quota_set	plain	xsd:string	A `quota_set` object.
gigabytes	plain	xsd:int	The number of gigabytes allowed for each tenant.
snapshots	plain	xsd:int	The number of snapshots allowed for each tenant.
volumes	plain	xsd:int	The number of volumes allowed for each tenant.

Response parameters

Parameter	Style	Type	Description
quota_set	plain	xsd:string	A `quota_set` object.
gigabytes	plain	xsd:int	The number of gigabytes allowed for each tenant.
snapshots	plain	xsd:int	The number of snapshots allowed for each tenant.
volumes	plain	xsd:int	The number of volumes allowed for each tenant.

{
    "quota_set": {
        "snapshots": 45
    }
}

<?xml version='1.0' encoding='UTF-8'?>
<quota_set id="fake_tenant">
  <snapshots>45</snapshots>
</quota_set>

{
    "quota_set": {
        "snapshots": 45
    }
}

<?xml version='1.0' encoding='UTF-8'?>
<quota_set id="fake_tenant">
  <gigabytes>5</gigabytes>
  <snapshots>10</snapshots>
  <volumes>20</volumes>
</quota_set>

DELETE

/v2/{tenant_id}/os-quota-sets/{tenant_id}

Delete quotas

Deletes quotas for a tenant so the quotas revert to default values.

Normal response codes

200

Request parameters

Parameter	Style	Type	Description
tenant_id	URI	xsd:string	The ID for the tenant or project in a multi-tenancy cloud.
tenant_id	URI	xsd:string	The ID for the tenant for which you want to show, update, or delete quotas. This ID is different from the first tenant ID that you specify in the URI: That ID is for the admin tenant.

This operation does not accept a request body and does not return a response body.

GET

/v2/{tenant_id}/os-quota-sets/defaults

Get default quotas

Gets default quotas for a tenant.

Normal response codes

200

Request parameters

Parameter	Style	Type	Description
tenant_id	URI	xsd:string	The ID for the tenant or project in a multi-tenancy cloud.

Response parameters

Parameter	Style	Type	Description
quota_set	plain	xsd:string	A `quota_set` object.
gigabytes	plain	xsd:int	The number of gigabytes allowed for each tenant.
snapshots	plain	xsd:int	The number of snapshots allowed for each tenant.
volumes	plain	xsd:int	The number of volumes allowed for each tenant.

{
    "quota_set": {
        "gigabytes": 5,
        "snapshots": 10,
        "volumes": 20
    }
}

<?xml version='1.0' encoding='UTF-8'?>
<quota_set id="fake_tenant">
  <gigabytes>5</gigabytes>
  <snapshots>10</snapshots>
  <volumes>20</volumes>
</quota_set>

This operation does not accept a request body.

GET

/v2/{tenant_id}/os-quota-sets/{tenant_id}/{user_id}

Show quotas for user

Enables an admin user to show quotas for a specified tenant and user.

Normal response codes

200

Request parameters

Parameter	Style	Type	Description
tenant_id	URI	xsd:string	The ID for the tenant or project in a multi-tenancy cloud.
tenant_id	URI	xsd:string	The ID for the tenant for which you want to show or update quotas. This ID is different from the first tenant ID that you specify in the URI: That ID is for the admin tenant.
user_id	URI	xsd:string	The user ID. Specify in the URI as a query string: `user_id={user_id}`.

Response parameters

Parameter	Style	Type	Description
quota_set	plain	xsd:string	A `quota_set` object.
gigabytes	plain	xsd:int	The number of gigabytes allowed for each tenant.
snapshots	plain	xsd:int	The number of snapshots allowed for each tenant.
volumes	plain	xsd:int	The number of volumes allowed for each tenant.

{
    "quota_set": {
        "snapshots": 45
    }
}

<?xml version='1.0' encoding='UTF-8'?>
<quota_set id="fake_tenant">
  <gigabytes>5</gigabytes>
  <snapshots>10</snapshots>
  <volumes>20</volumes>
</quota_set>

This operation does not accept a request body.

PUT

/v2/{tenant_id}/os-quota-sets/{tenant_id}/{user_id}

Update quotas for user

Updates quotas for a specified tenant/project and user.

Normal response codes

200

Request parameters

Parameter	Style	Type	Description
tenant_id	URI	xsd:string	The ID for the tenant or project in a multi-tenancy cloud.
tenant_id	URI	xsd:string	The ID for the tenant for which you want to show or update quotas. This ID is different from the first tenant ID that you specify in the URI: That ID is for the admin tenant.
user_id	URI	xsd:string	The user ID. Specify in the URI as a query string: `user_id={user_id}`.
quota_set	plain	xsd:string	A `quota_set` object.
gigabytes	plain	xsd:int	The number of gigabytes allowed for each tenant.
snapshots	plain	xsd:int	The number of snapshots allowed for each tenant.
volumes	plain	xsd:int	The number of volumes allowed for each tenant.

Response parameters

Parameter	Style	Type	Description
quota_set	plain	xsd:string	A `quota_set` object.
gigabytes	plain	xsd:int	The number of gigabytes allowed for each tenant.
snapshots	plain	xsd:int	The number of snapshots allowed for each tenant.
volumes	plain	xsd:int	The number of volumes allowed for each tenant.

{
    "quota_set": {
        "snapshots": 45
    }
}

<?xml version='1.0' encoding='UTF-8'?>
<quota_set id="fake_tenant">
  <snapshots>45</snapshots>
</quota_set>

{
    "quota_set": {
        "snapshots": 45
    }
}

<?xml version='1.0' encoding='UTF-8'?>
<quota_set id="fake_tenant">
  <gigabytes>5</gigabytes>
  <snapshots>10</snapshots>
  <volumes>20</volumes>
</quota_set>

DELETE

/v2/{tenant_id}/os-quota-sets/{tenant_id}/{user_id}

Delete quotas for user

Deletes quotas for a user so that the quotas revert to default values.

Normal response codes

200

Request parameters

Parameter	Style	Type	Description
tenant_id	URI	xsd:string	The ID for the tenant or project in a multi-tenancy cloud.
tenant_id	URI	xsd:string	The ID for the tenant for which you want to show or update quotas. This ID is different from the first tenant ID that you specify in the URI: That ID is for the admin tenant.
user_id	URI	xsd:string	The user ID. Specify in the URI as a query string: `user_id={user_id}`.

This operation does not accept a request body and does not return a response body.

GET

/v2/{tenant_id}/os-quota-sets/{tenant_id}/detail/{user_id}

Show quota details for user

Shows details for quotas for a specified tenant and user.

Normal response codes

200

Request parameters

Parameter	Style	Type	Description
tenant_id	URI	xsd:string	The ID for the tenant or project in a multi-tenancy cloud.
tenant_id	URI	xsd:string	The ID for the tenant for which you want to show or update quotas. This ID is different from the first tenant ID that you specify in the URI: That ID is for the admin tenant.
user_id	URI	xsd:string	The user ID. Specify in the URI as a query string: `user_id={user_id}`.

Response parameters

Parameter	Style	Type	Description
quota_set	plain	xsd:string	A `quota_set` object.
gigabytes	plain	xsd:int	The number of gigabytes allowed for each tenant.
snapshots	plain	xsd:int	The number of snapshots allowed for each tenant.
volumes	plain	xsd:int	The number of volumes allowed for each tenant.

{
    "quota_set": {
        "snapshots": 45
    }
}

This operation does not accept a request body.

Limits extension (limits)

Shows absolute limits for a tenant.

An absolute limit value of -1 indicates that the absolute limit for the item is infinite.

GET

/v2/{tenant_id}/limits

Show absolute limits

Shows absolute limits for a tenant.

An absolute limit value of -1 indicates that the absolute limit for the item is infinite.

Normal response codes

200, 203

Request parameters

Parameter	Style	Type	Description
tenant_id	URI	xsd:string	The ID for the tenant or project in a multi-tenancy cloud.

Response parameters

Parameter	Style	Type	Description
limits	plain	xsd:string	A `limits` object.
absolute	plain	xsd:string	An `absolute` limits object.
totalSnapshotsUsed	plain	xsd:int	Total number of snapshots used.
maxTotalVolumeGigabytes	plain	xsd:int	Maximum total amount of volumes, in gibibytes (GiB).
totalGigabytesUsed	plain	xsd:int	Total number of gibibytes (GiB) used.
maxTotalSnapshots	plain	xsd:int	Maximum number of snapshots.
totalVolumesUsed	plain	xsd:int	Total number of volumes used.
maxTotalVolumes	plain	xsd:int	Maximum number of volumes.

{
    "limits": {
        "rate": [],
        "absolute": {
            "totalSnapshotsUsed": 0,
            "maxTotalVolumeGigabytes": 1000,
            "totalGigabytesUsed": 0,
            "maxTotalSnapshots": 10,
            "totalVolumesUsed": 0,
            "maxTotalVolumes": 10
        }
    }
}

<?xml version='1.0' encoding='UTF-8'?>
<limits xmlns:atom="http://www.w3.org/2005/Atom"
    xmlns="http://docs.openstack.org/common/api/v1.0">
    <rates/>
    <absolute>
        <limit name="totalSnapshotsUsed" value="0"/>
        <limit name="maxTotalVolumeGigabytes" value="1000"/>
        <limit name="totalGigabytesUsed" value="0"/>
        <limit name="maxTotalSnapshots" value="10"/>
        <limit name="totalVolumesUsed" value="0"/>
        <limit name="maxTotalVolumes" value="10"/>
    </absolute>
</limits>

This operation does not accept a request body.

Backups

A backup is a full copy of a volume stored in an external service. The service can be configured. The only supported service for now is Object Storage. A backup can subsequently be restored from the external service to either the same volume that the backup was originally taken from, or to a new volume. Backup and restore operations can only be carried out on volumes which are in an unattached and available state.

When you create, list, or delete backups, these status values are possible:

Backup statuses
Status	Description
creating	The backup is being created.
available	The backup is ready to be restored to a volume.
deleting	The backup is being deleted.
error	An error has occurred with the backup.
restoring	The backup is being restored to a volume.
error_restoring	An error occurred during backup restoration to a volume.

In the event of an error, more information about the error can be found in the fail_reason field for the backup.

POST

/v2/{tenant_id}/backups

Create backup

Creates a Block Storage backup from a volume.

Normal response codes

202

Request parameters

Parameter	Style	Type	Description
tenant_id	URI	xsd:string	The unique identifier of the tenant or account.
backup	plain	xsd:string	A `backup` object.
container	plain	xsd:string	The container name or null.
name	plain	xsd:string	The backup name.
description	plain	xsd:string	The backup description or null.
volume_id	plain	csapi:uuid	The ID of the volume that you want to back up.
incremental (Optional)	plain	xsd:boolean	The backup mode. A valid value is `True` for incremental backup mode or `False` for full backup mode. Default is `False`.

Response parameters

Parameter	Style	Type	Description
backup	plain	xsd:string	A `backup` object.
id	plain	csapi:uuid	The ID of the backup.
links	plain	xsd:dict	Links for the backup.
name	plain	xsd:string	The backup name.

{
    "backup": {
        "container": null,
        "description": null,
        "name": "backup001",
        "volume_id": "64f5d2fb-d836-4063-b7e2-544d5c1ff607",
        "incremental": "True"
    }
}

{
    "backup": {
        "id": "deac8b8c-35c9-4c71-acaa-889c2d5d5c8e",
        "links": [
            {
                "href": "http://localhost:8776/v2/c95fc3e4afe248a49a28828f286a7b38/backups/deac8b8c-35c9-4c71-acaa-889c2d5d5c8e",
                "rel": "self"
            },
            {
                "href": "http://localhost:8776/c95fc3e4afe248a49a28828f286a7b38/backups/deac8b8c-35c9-4c71-acaa-889c2d5d5c8e",
                "rel": "bookmark"
            }
        ],
        "name": "backup001"
    }
}

GET

/v2/{tenant_id}/backups

List backups

Lists backups defined in Block Storage to which the tenant who submits the request has access.

Normal response codes

200

Request parameters

Parameter	Style	Type	Description
tenant_id	URI	xsd:string	The unique identifier of the tenant or account.
sort_key (Optional)	query	xsd:string	Sorts by the requested image attribute. Accepted values are `name`, `status`, `container_format`, `disk_format`, `size`, `id`, `created_at`, and `updated_at`. Default is `created_at`. The API uses the natural sorting direction of the image attribute that is provided as the `sort_key`.
sort_dir (Optional)	query	xsd:string	Sorts by one or more sets of attribute and sort direction combinations. If you omit the sort direction in a set, default is `desc`.
limit (Optional)	query	xsd:int	Requests a specified page size of returned items from the query. Returns a number of items up to the specified limit value. Use the `limit` parameter to make an initial limited request and use the ID of the last-seen item from the response as the `marker` parameter value in a subsequent limited request.
marker (Optional)	query	xsd:string	Specifies the ID of the last-seen item. Use the `limit` parameter to make an initial limited request and use the ID of the last-seen item from the response as the `marker` parameter value in a subsequent limited request.

Response parameters

Parameter	Style	Type	Description
backups	plain	xsd:string	A `backups` object.
id	plain	csapi:uuid	The ID of the backup.
links	plain	xsd:dict	Links for the backup.
name	plain	xsd:string	The backup name.

{
    "backups": [
        {
            "id": "2ef47aee-8844-490c-804d-2a8efe561c65",
            "links": [
                {
                    "href": "http://localhost:8776/v1/c95fc3e4afe248a49a28828f286a7b38/backups/2ef47aee-8844-490c-804d-2a8efe561c65",
                    "rel": "self"
                },
                {
                    "href": "http://localhost:8776/c95fc3e4afe248a49a28828f286a7b38/backups/2ef47aee-8844-490c-804d-2a8efe561c65",
                    "rel": "bookmark"
                }
            ],
            "name": "backup001"
        },
        {
            "id": "4dbf0ec2-0b57-4669-9823-9f7c76f2b4f8",
            "links": [
                {
                    "href": "http://localhost:8776/v1/c95fc3e4afe248a49a28828f286a7b38/backups/4dbf0ec2-0b57-4669-9823-9f7c76f2b4f8",
                    "rel": "self"
                },
                {
                    "href": "http://localhost:8776/c95fc3e4afe248a49a28828f286a7b38/backups/4dbf0ec2-0b57-4669-9823-9f7c76f2b4f8",
                    "rel": "bookmark"
                }
            ],
            "name": "backup002"
        }
    ]
}

GET

/v2/{tenant_id}/backups/detail

List backups (detailed)

Lists detailed information for backups defined in Block Storage to which the tenant who submits the request has access.

Normal response codes

200

Request parameters

Parameter	Style	Type	Description
tenant_id	URI	xsd:string	The unique identifier of the tenant or account.
sort_key (Optional)	query	xsd:string	Sorts by the requested image attribute. Accepted values are `name`, `status`, `container_format`, `disk_format`, `size`, `id`, `created_at`, and `updated_at`. Default is `created_at`. The API uses the natural sorting direction of the image attribute that is provided as the `sort_key`.
sort_dir (Optional)	query	xsd:string	Sorts by one or more sets of attribute and sort direction combinations. If you omit the sort direction in a set, default is `desc`.
limit (Optional)	query	xsd:int	Requests a specified page size of returned items from the query. Returns a number of items up to the specified limit value. Use the `limit` parameter to make an initial limited request and use the ID of the last-seen item from the response as the `marker` parameter value in a subsequent limited request.
marker (Optional)	query	xsd:string	Specifies the ID of the last-seen item. Use the `limit` parameter to make an initial limited request and use the ID of the last-seen item from the response as the `marker` parameter value in a subsequent limited request.

Response parameters

Parameter	Style	Type	Description
backups	plain	xsd:string	A `backups` object.
availability_zone	plain	xsd:string	The availability zone.
container	plain	xsd:string	The container name or null.
created_at	plain	xsd:timestamp	The date and time when the backup was created.
description	plain	xsd:string	The backup description or null.
fail_reason	plain	xsd:string	If the backup failed, the reason for the failure. Otherwise, null.
id	plain	csapi:uuid	The ID of the backup.
links	plain	xsd:dict	Links for the backup.
name	plain	xsd:string	The backup name.
object_count	plain	xsd:int	The number of objects in the backup.
size	plain	xsd:int	The size of the backup, in GB.
status	plain	xsd:string	The backup status, such as available.
volume_id	plain	csapi:uuid	The ID of the volume from which the backup was created.
is_incremental	plain	xsd:boolean	Indicates whether the backup mode is incremental. If this value is `True`, the backup mode is incremental. If this value is `False`, the backup mode is full.
has_dependent_backups	plain	xsd:boolean	Indicates whether the backup depends on other backups. If this value is `True`, the backup depends on other backups.

{
    "backups": [
        {
            "availability_zone": "az1",
            "container": "volumebackups",
            "created_at": "2013-04-02T10:35:27.000000",
            "description": null,
            "fail_reason": null,
            "id": "2ef47aee-8844-490c-804d-2a8efe561c65",
            "links": [
                {
                    "href": "http://localhost:8776/v1/c95fc3e4afe248a49a28828f286a7b38/backups/2ef47aee-8844-490c-804d-2a8efe561c65",
                    "rel": "self"
                },
                {
                    "href": "http://localhost:8776/c95fc3e4afe248a49a28828f286a7b38/backups/2ef47aee-8844-490c-804d-2a8efe561c65",
                    "rel": "bookmark"
                }
            ],
            "name": "backup001",
            "object_count": 22,
            "size": 1,
            "status": "available",
            "volume_id": "e5185058-943a-4cb4-96d9-72c184c337d6",
            "is_incremental": "True",
            "has_dependent_backups": "False"
        },
        {
            "availability_zone": "az1",
            "container": "volumebackups",
            "created_at": "2013-04-02T10:21:48.000000",
            "description": null,
            "fail_reason": null,
            "id": "4dbf0ec2-0b57-4669-9823-9f7c76f2b4f8",
            "links": [
                {
                    "href": "http://localhost:8776/v1/c95fc3e4afe248a49a28828f286a7b38/backups/4dbf0ec2-0b57-4669-9823-9f7c76f2b4f8",
                    "rel": "self"
                },
                {
                    "href": "http://localhost:8776/c95fc3e4afe248a49a28828f286a7b38/backups/4dbf0ec2-0b57-4669-9823-9f7c76f2b4f8",
                    "rel": "bookmark"
                }
            ],
            "name": "backup002",
            "object_count": 22,
            "size": 1,
            "status": "available",
            "volume_id": "e5185058-943a-4cb4-96d9-72c184c337d6",
            "is_incremental": "True",
            "has_dependent_backups": "False"
        }
    ]
}

GET

/v2/{tenant_id}/backups/{backup_id}

Show backup details

Shows details for a specified backup.

Normal response codes

200

Request parameters

Parameter	Style	Type	Description
tenant_id	URI	xsd:string	The unique identifier of the tenant or account.
backup_id	URI	csapi:UUID	The unique identifier for a backup.

Response parameters

Parameter	Style	Type	Description
backup	plain	xsd:string	A `backup` object.
availability_zone	plain	xsd:string	The availability zone.
container	plain	xsd:string	The container name or null.
created_at	plain	xsd:timestamp	The date and time when the backup was created.
description	plain	xsd:string	The backup description or null.
fail_reason	plain	xsd:string	If the backup failed, the reason for the failure. Otherwise, null.
id	plain	csapi:uuid	The ID of the backup.
links	plain	xsd:dict	Links for the backup.
name	plain	xsd:string	The backup name.
object_count	plain	xsd:int	The number of objects in the backup.
size	plain	xsd:int	The size of the backup, in GB.
status	plain	xsd:string	The backup status, such as available.
volume_id	plain	csapi:uuid	The ID of the volume from which the backup was created.
is_incremental	plain	xsd:boolean	Indicates whether the backup mode is incremental. If this value is `True`, the backup mode is incremental. If this value is `False`, the backup mode is full.
has_dependent_backups	plain	xsd:boolean	Indicates whether the backup depends on other backups. If this value is `True`, the backup depends on other backups.

{
    "backup": {
        "availability_zone": "az1",
        "container": "volumebackups",
        "created_at": "2013-04-02T10:35:27.000000",
        "description": null,
        "fail_reason": null,
        "id": "2ef47aee-8844-490c-804d-2a8efe561c65",
        "links": [
            {
                "href": "http://localhost:8776/v1/c95fc3e4afe248a49a28828f286a7b38/backups/2ef47aee-8844-490c-804d-2a8efe561c65",
                "rel": "self"
            },
            {
                "href": "http://localhost:8776/c95fc3e4afe248a49a28828f286a7b38/backups/2ef47aee-8844-490c-804d-2a8efe561c65",
                "rel": "bookmark"
            }
        ],
        "name": "backup001",
        "object_count": 22,
        "size": 1,
        "status": "available",
        "volume_id": "e5185058-943a-4cb4-96d9-72c184c337d6",
        "is_incremental": "True",
        "has_dependent_backups": "False"
    }
}

This operation does not accept a request body.

DELETE

/v2/{tenant_id}/backups/{backup_id}

Delete backup

Deletes a specified backup.

Normal response codes

202

Request parameters

Parameter	Style	Type	Description
tenant_id	URI	xsd:string	The unique identifier of the tenant or account.
backup_id	URI	csapi:UUID	The unique identifier for a backup.

This operation does not accept a request body and does not return a response body.

POST

/v2/{tenant_id}/backups/{backup_id}/restore

Restore backup

Restores a Block Storage backup to an existing or new Block Storage volume.

You must specify either the volume ID or name. If you specify both the volume ID and name, the ID takes priority.

Normal response codes

202

Request parameters

Parameter	Style	Type	Description
tenant_id	URI	xsd:string	The unique identifier of the tenant or account.
backup_id	URI	csapi:UUID	The unique identifier for a backup.
restore	plain	xsd:string	The `restore` action.
volume_id (Optional)	plain	csapi:UUID	The ID of the volume to which you want to restore a backup.
name (Optional)	plain	xsd:string	The name of the volume to which you want to restore a backup.

Response parameters

Parameter	Style	Type	Description
restore	plain	xsd:string	The `restore` action.
backup_id	plain	csapi:UUID	The ID of the backup.
volume_id	plain	csapi:UUID	The ID of the volume to which the backup was restored.

{
    "restore": {
        "name": "vol-01",
        "volume_id": "64f5d2fb-d836-4063-b7e2-544d5c1ff607"
    }
}

{
    "restore": {
        "backup_id": "2ef47aee-8844-490c-804d-2a8efe561c65",
        "volume_id": "795114e8-7489-40be-a978-83797f2c1dd3"
    }
}

Backup actions

Force-deletes a backup.

POST

/v2/{tenant_id}/backups/{backup_id}/action

Force-delete backup

Force-deletes a specified backup. Specify the os-force_delete action in the request body.

The backup and any backup data is deleted.

The backup driver returns the 405 status code if it does not support this operation.

Normal response codes

202

Error response codes

404, 405

Request parameters

Parameter	Style	Type	Description
tenant_id	URI	xsd:string	The unique identifier of the tenant or account.
backup_id	URI	csapi:UUID	The unique identifier for a backup.
os-force_delete	plain	xsd:string	The `os-force_delete` action.

{
    "os-force_delete": {}
}

This operation does not return a response body.

Volume manage extension (os-volume-manage)

Creates volumes by using existing storage instead of allocating new storage.

POST

/v2/{tenant_id}/os-volume-manage

Manage existing volume

Creates a Block Storage volume by using existing storage rather than allocating new storage.

The caller must specify a reference to an existing storage volume in the ref parameter in the request. Although each storage driver might interpret this reference differently, the driver should accept a reference structure that contains either a source-volume-id or source-volume-name element, if possible.

The API chooses the size of the volume by rounding up the size of the existing storage volume to the next gibibyte (GiB).

Normal response codes

202

Request parameters

Parameter	Style	Type	Description
tenant_id	URI	xsd:string	The unique identifier of the tenant or account.
volume	plain	xsd:string	A `volume` object.
host	plain	xsd:string	The OpenStack Block Storage host where the existing volume resides.
ref	plain	xsd:string	A reference to the existing volume. The internal structure of this reference depends on the volume driver implementation. For details about the required elements in the structure, see the documentation for the volume driver.
name (Optional)	plain	xsd:string	The volume name.
availability_zone (Optional)	plain	xsd:string	The availability zone.
description (Optional)	plain	xsd:string	The volume description.
volume_type (Optional)	plain	xsd:string	The associated volume type.
bootable (Optional)	plain	xsd:boolean	Enables or disables the bootable attribute. You can boot an instance from a bootable volume.
metadata (Optional)	plain	xsd:string	One or more metadata key and value pairs to associate with the volume.

{
    "volume": {
        "host": "geraint-VirtualBox",
        "ref": {
            "source-volume-name": "existingLV",
            "source-volume-id": "1234"
        },
        "name": "New Volume",
        "availability_zone": "az2",
        "description": "Volume imported from existingLV",
        "volume_type": null,
        "bootable": "True",
        "metadata": {
            "key1": "value1",
            "key2": "value2"
        }
    }
}

{
    "volume": {
        "status": "creating",
        "user_id": "eae1472b5fc5496998a3d06550929e7e",
        "attachments": [],
        "links": [
            {
                "href": "http://10.0.2.15:8776/v2/87c8522052ca4eed98bc672b4c1a3ddb/volumes/23cf872b-c781-4cd4-847d-5f2ec8cbd91c",
                "rel": "self"
            },
            {
                "href": "http://10.0.2.15:8776/87c8522052ca4eed98bc672b4c1a3ddb/volumes/23cf872b-c781-4cd4-847d-5f2ec8cbd91c",
                "rel": "bookmark"
            }
        ],
        "availability_zone": "az2",
        "bootable": "false",
        "encrypted": "false",
        "created_at": "2014-07-18T00:12:54.000000",
        "description": "Volume imported from existingLV",
        "os-vol-tenant-attr:tenant_id": "87c8522052ca4eed98bc672b4c1a3ddb",
        "volume_type": null,
        "name": "New Volume",
        "source_volid": null,
        "snapshot_id": null,
        "metadata": {
            "key2": "value2",
            "key1": "value1"
        },
        "id": "23cf872b-c781-4cd4-847d-5f2ec8cbd91c",
        "size": 0
    }
}

Volume image metadata extension (os-vol-image-meta)

Shows image metadata that is associated with a specified volume.

GET

/v2/{tenant_id}/os-vol-image-meta

Show image metadata for volume

Shows image metadata that is associated with a specified volume.

When the request is made, the caller must specify (in the ref element) a reference to an existing storage volume. Each storage driver may interpret the existing storage volume reference differently, but should accept a reference structure containing either a source-volume-id or source-volume-name element if possible.

Normal response codes

202

Request parameters

Parameter	Style	Type	Description
tenant_id	URI	xsd:string	The unique identifier of the tenant or account.
volume	plain	xsd:string	A `volume` object.
host	plain	xsd:string	The OpenStack Block Storage host where the existing volume resides.
ref	plain	xsd:string	A reference to the existing volume. The internal structure of this reference is dependent on the implementation of the volume driver, see the specific driver's documentation for details of the required elements in the structure.
name (Optional)	plain	xsd:string	The volume name.
availability_zone (Optional)	plain	xsd:string	The availability zone.
description (Optional)	plain	xsd:string	The volume description.
volume_type (Optional)	plain	xsd:string	The associated volume type.
bootable (Optional)	plain	xsd:boolean	Enables or disables the bootable attribute. You can boot an instance from a bootable volume.
metadata (Optional)	plain	xsd:string	One or more metadata key and value pairs to associate with the volume.

{
    "volume": {
        "host": "geraint-VirtualBox",
        "ref": {
            "source-volume-name": "existingLV",
            "source-volume-id": "1234"
        },
        "name": "New Volume",
        "availability_zone": "az2",
        "description": "Volume imported from existingLV",
        "volume_type": null,
        "bootable": "True",
        "metadata": {
            "key1": "value1",
            "key2": "value2"
        }
    }
}

{
    "volume": {
        "status": "creating",
        "user_id": "eae1472b5fc5496998a3d06550929e7e",
        "attachments": [],
        "links": [
            {
                "href": "http://10.0.2.15:8776/v2/87c8522052ca4eed98bc672b4c1a3ddb/volumes/23cf872b-c781-4cd4-847d-5f2ec8cbd91c",
                "rel": "self"
            },
            {
                "href": "http://10.0.2.15:8776/87c8522052ca4eed98bc672b4c1a3ddb/volumes/23cf872b-c781-4cd4-847d-5f2ec8cbd91c",
                "rel": "bookmark"
            }
        ],
        "availability_zone": "az2",
        "bootable": "false",
        "encrypted": "false",
        "created_at": "2014-07-18T00:12:54.000000",
        "description": "Volume imported from existingLV",
        "os-vol-tenant-attr:tenant_id": "87c8522052ca4eed98bc672b4c1a3ddb",
        "volume_type": null,
        "name": "New Volume",
        "source_volid": null,
        "snapshot_id": null,
        "metadata": {
            "key2": "value2",
            "key1": "value1"
        },
        "id": "23cf872b-c781-4cd4-847d-5f2ec8cbd91c",
        "size": 0
    }
}

Volume type access (volumes)

Creates private volumes.

By default, volumes are public. To create a private volume, set the is_public boolean field to false at volume creation time. To control access to a private volume, you add a project to or remove a project from the volume. Private volume types without projects are only accessible by users with the administrative role and context.

POST

/v2/{tenant_id}/volumes

Create private volume

Creates a private Block Storage volume.

Normal response codes

202

Request parameters

Parameter	Style	Type	Description
tenant_id	URI	xsd:string	The unique identifier of the tenant or account.
availability_zone (Optional)	plain	xsd:string	The availability zone.
source_volid (Optional)	plain	csapi:uuid	To create a volume from an existing volume, specify the ID of the existing volume. The volume is created with the same size as the source volume.
description (Optional)	plain	xsd:string	The volume description.
snapshot_id (Optional)	plain	csapi:uuid	To create a volume from an existing snapshot, specify the ID of the existing volume snapshot. The volume is created in same availability zone and with same size as the snapshot.
size	plain	xsd:int	The size of the volume, in gibibytes (GiB).
name (Optional)	plain	xsd:string	The volume name.
imageRef (Optional)	plain	csapi:uuid	The ID of the image from which you want to create the volume. Required to create a bootable volume.
volume_type (Optional)	plain	xsd:string	The associated volume type.
metadata (Optional)	plain	xsd:string	One or more metadata key and value pairs to associate with the volume.
os-volume-type-access:is_public (Optional)	plain	xsd:boolean	The volume type access. Set to `true` if access is public. Set to `false` if access is private. Default is `true`.

Response parameters

Parameter	Style	Type	Description
status	plain	xsd:string	The volume status.
name	plain	xsd:string	The volume name.
attachments	plain	xsd:dict	One or more instance attachments.
availability_zone	plain	xsd:string	The availability zone.
created_at	plain	xsd:datetime	Date and time when the volume was created.
description	plain	xsd:string	The volume description.
volume_type	plain	xsd:string	The associated volume type.
snapshot_id	plain	csapi:uuid	The ID of the source volume snapshot.
source_volid	plain	csapi:uuid	The ID of the source volume.
metadata	plain	xsd:string	One or more metadata key and value pairs to associate with the volume.
id	plain	csapi:uuid	The volume ID.
size	plain	xsd:int	The size of the volume, in gibibytes (GiB).
os-volume-type-access:is_public	plain	xsd:boolean	The volume type access. Set to `true` if access is public. Set to `false` if access is private.

{
    "volume": {
        "availability_zone": null,
        "source_volid": null,
        "description": null,
        "snapshot_id": null,
        "size": 10,
        "name": "my_volume",
        "imageRef": null,
        "volume_type": null,
        "metadata": {},
        "os-volume-type-access: is_public": false
    }
}

<?xml version="1.0" encoding="UTF-8"?>
<volume xmlns="http://docs.openstack.org/openstack-block-storage/2.0/content" xmlns:os-volume-type-access="http://docs.openstack.org/openstack-block-storage/2.0/ext/os-volume-type-access/api/v2.0" name="vol-001" description="Another volume." size="2" os-volume-type-access:is_public="false" />

{
    "volume": {
        "status": "creating",
        "name": "my_volume",
        "attachments": [],
        "availability_zone": "nova",
        "bootable": "false",
        "created_at": "2014-02-21T19: 52: 04.949734",
        "description": null,
        "volume_type": "None",
        "snapshot_id": null,
        "source_volid": null,
        "metadata": {},
        "id": "93c2e2aa-7744-4fd6-a31a-80c4726b08d7",
        "size": 10,
        "os-volume-type-access: is_public": false
    }
}

<?xml version="1.0" encoding="UTF-8"?>
<volume xmlns="http://docs.openstack.org/openstack-block-storage/2.0/content" xmlns:atom="http://www.w3.org/2005/Atom" xmlns:os-volume-type-access="http://docs.openstack.org/openstack-block-storage/2.0/ext/os-volume-type-access/api/v2.0" status="creating" name="vol-001" availability_zone="nova" bootable="false" created_at="2014-02-21 20:18:33.122452" description="Another volume." volume_type="None" snapshot_id="None" source_volid="None" id="83960a54-8dad-4fd8-bc41-33c71e098e04" size="2" os-volume-type-access:is_public="false">
    <attachments />
    <metadata />
</volume>