Block Storage API v1

Service enables instant creation of configurable or storage volumes and there cloud server attachments. It is already know under OpenStack as Cinder.

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": "https://volume.fr1.cloudwatt.com/v1/",
                    "rel": "self"
                }
            ]
        },
        {
            "status": "CURRENT",
            "updated": "2012-11-21T11:33:21Z",
            "id": "v2.0",
            "links": [
                {
                    "href": "https://volume.fr1.cloudwatt.com/v2/",
                    "rel": "self"
                }
            ]
        }
    ]
}

This operation does not accept a request body.

GET
/v1
Show API v1 details

Shows details for Block Storage API v1.

 
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": "https://volume.fr1.cloudwatt.com/v1/",
                "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.

Volumes

POST
/v1/​{tenant_id}​/volumes
Create volume

Creates a volume.

 
Normal response codes
201
Request parameters
Parameter Style Type Description
tenant_id URI csapi:UUID

The unique identifier of the tenant or account.

volume plain csapi:string

A partial representation of a volume used in the creation process.

{
    "volume": {
        "display_name": "vol-001",
        "display_description": "Another volume.",
        "size": 30,
        "volume_type": "289da7f8-6440-407c-9fb4-7db01ec49164",
        "metadata": {
            "contents": "junk"
        },
        "availability_zone": "us-east1"
    }
}
<?xml version="1.0" encoding="UTF-8"?>
<volume xmlns="http://docs.openstack.org/volume/api/v1"
        display_name="vol-001"
        display_description="Another volume."
        size="30"
        volume_type="289da7f8-6440-407c-9fb4-7db01ec49164"
        availability_zone="us-east1">
    <metadata>
        <meta key="contents">junk</meta>
    </metadata>
</volume>
{
    "volume": {
        "id": "521752a6-acf6-4b2d-bc7a-119f9148cd8c",
        "display_name": "vol-001",
        "display_description": "Another volume.",
        "size": 30,
        "volume_type": "289da7f8-6440-407c-9fb4-7db01ec49164",
        "metadata": {
            "contents": "junk"
        },
        "availability_zone": "us-east1",
        "bootable": "false",
        "snapshot_id": null,
        "attachments": [],
        "created_at": "2012-02-14T20:53:07Z"
    }
}
<?xml version="1.0" encoding="UTF-8"?>
<volume xmlns="http://docs.openstack.org/volume/api/v1"
        id="521752a6-acf6-4b2d-bc7a-119f9148cd8c"
        display_name="vol-001"
        display_description="Another volume."
        status="active"
        size="30"
        volume_type="289da7f8-6440-407c-9fb4-7db01ec49164"
        availability_zone="us-east1"
        bootable="false"
        created_at="2012-02-14T20:53:07Z">
    <metadata>
        <meta key="contents">junk</meta>
    </metadata>
</volume>
GET
/v1/​{tenant_id}​/volumes
List volumes

Lists simple volume entities.

 
Normal response codes
200
Request parameters
Parameter Style Type Description
tenant_id URI csapi:UUID

The unique identifier of the tenant or account.

{
    "volumes": [
        {
            "id": "521752a6-acf6-4b2d-bc7a-119f9148cd8c",
            "display_name": "vol-001",
            "display_description": "Another volume.",
            "size": 30,
            "volume_type": "289da7f8-6440-407c-9fb4-7db01ec49164",
            "metadata": {
                "contents": "junk"
            },
            "availability_zone": "us-east1",
            "snapshot_id": null,
            "attachments": [],
            "created_at": "2012-02-14T20:53:07Z"
        },
        {
            "id": "76b8950a-8594-4e5b-8dce-0dfa9c696358",
            "display_name": "vol-002",
            "display_description": "Yet another volume.",
            "size": 25,
            "volume_type": "96c3bda7-c82a-4f50-be73-ca7621794835",
            "metadata": {},
            "availability_zone": "us-east2",
            "snapshot_id": null,
            "attachments": [],
            "created_at": "2012-03-15T19:10:03Z"
        }
    ]
}
<?xml version="1.0" encoding="UTF-8"?>
<volumes xmlns="http://docs.openstack.org/volume/api/v1">
    <volume xmlns="http://docs.openstack.org/volume/api/v1"
            id="521752a6-acf6-4b2d-bc7a-119f9148cd8c"
            display_name="vol-001"
            display_description="Another volume."
            status="active"
            size="30"
            volume_type="289da7f8-6440-407c-9fb4-7db01ec49164"
            availability_zone="us-east1"
            created_at="2012-02-14T20:53:07Z">
        <metadata>
            <meta key="contents">junk</meta>
        </metadata>
    </volume>
    <volume xmlns="http://docs.openstack.org/volume/api/v1"
            id="76b8950a-8594-4e5b-8dce-0dfa9c696358"
            display_name="vol-002"
            display_description="Yet another volume."
            status="active"
            size="25"
            volume_type="96c3bda7-c82a-4f50-be73-ca7621794835"
            availability_zone="us-east2"
            created_at="2012-03-15T19:10:03Z" />
</volumes>

This operation does not accept a request body.

GET
/v1/​{tenant_id}​/volumes/detail
List volumes (detailed)

Lists details for volume entities.

 
Normal response codes
200
Request parameters
Parameter Style Type Description
tenant_id URI csapi:UUID

The unique identifier of the tenant or account.

{
    "volumes": [
        {
            "id": "521752a6-acf6-4b2d-bc7a-119f9148cd8c",
            "display_name": "vol-001",
            "display_description": "Another volume.",
            "size": 30,
            "volume_type": "289da7f8-6440-407c-9fb4-7db01ec49164",
            "metadata": {
                "contents": "junk"
            },
            "availability_zone": "us-east1",
            "snapshot_id": null,
            "attachments": [],
            "created_at": "2012-02-14T20:53:07Z"
        },
        {
            "id": "76b8950a-8594-4e5b-8dce-0dfa9c696358",
            "display_name": "vol-002",
            "display_description": "Yet another volume.",
            "size": 25,
            "volume_type": "96c3bda7-c82a-4f50-be73-ca7621794835",
            "metadata": {},
            "availability_zone": "us-east2",
            "snapshot_id": null,
            "attachments": [],
            "created_at": "2012-03-15T19:10:03Z"
        }
    ]
}
<?xml version="1.0" encoding="UTF-8"?>
<volumes xmlns="http://docs.openstack.org/volume/api/v1">
    <volume xmlns="http://docs.openstack.org/volume/api/v1"
            id="521752a6-acf6-4b2d-bc7a-119f9148cd8c"
            display_name="vol-001"
            display_description="Another volume."
            status="active"
            size="30"
            volume_type="289da7f8-6440-407c-9fb4-7db01ec49164"
            availability_zone="us-east1"
            created_at="2012-02-14T20:53:07Z">
        <metadata>
            <meta key="contents">junk</meta>
        </metadata>
    </volume>
    <volume xmlns="http://docs.openstack.org/volume/api/v1"
            id="76b8950a-8594-4e5b-8dce-0dfa9c696358"
            display_name="vol-002"
            display_description="Yet another volume."
            status="active"
            size="25"
            volume_type="96c3bda7-c82a-4f50-be73-ca7621794835"
            availability_zone="us-east2"
            created_at="2012-03-15T19:10:03Z" />
</volumes>

This operation does not accept a request body.

GET
/v1/​{tenant_id}​/volumes/​{volume_id}​
Show volume information

Shows information about a specified volume.

 
Normal response codes
200
Request parameters
Parameter Style Type Description
tenant_id URI csapi:UUID

The unique identifier of the tenant or account.

volume_id URI csapi:UUID

The unique identifier of an existing volume.

{
    "volume": {
        "id": "521752a6-acf6-4b2d-bc7a-119f9148cd8c",
        "display_name": "vol-001",
        "display_description": "Another volume.",
        "size": 30,
        "volume_type": "289da7f8-6440-407c-9fb4-7db01ec49164",
        "metadata": {
            "contents": "junk"
        },
        "availability_zone": "us-east1",
        "bootable": "false",
        "snapshot_id": null,
        "attachments": [],
        "created_at": "2012-02-14T20:53:07Z"
    }
}
<?xml version="1.0" encoding="UTF-8"?>
<volume xmlns="http://docs.openstack.org/volume/api/v1"
        id="521752a6-acf6-4b2d-bc7a-119f9148cd8c"
        display_name="vol-001"
        display_description="Another volume."
        status="active"
        size="30"
        volume_type="289da7f8-6440-407c-9fb4-7db01ec49164"
        availability_zone="us-east1"
        bootable="false"
        created_at="2012-02-14T20:53:07Z">
    <metadata>
        <meta key="contents">junk</meta>
    </metadata>
</volume>

This operation does not accept a request body.

DELETE
/v1/​{tenant_id}​/volumes/​{volume_id}​
Delete volume

Deletes a specified volume.

 
Normal response codes
202
Request parameters
Parameter Style Type Description
tenant_id URI csapi:UUID

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 types

GET
/v1/​{tenant_id}​/types
List volume types

Request a list of volume types.

 
Normal response codes
200
Request parameters
Parameter Style Type Description
tenant_id URI csapi:UUID

The unique identifier of the tenant or account.

{
    "volume_types": [
        {
            "id": "289da7f8-6440-407c-9fb4-7db01ec49164",
            "name": "vol-type-001",
            "extra_specs": {
                "capabilities": "gpu"
            }
        },
        {
            "id": "96c3bda7-c82a-4f50-be73-ca7621794835",
            "name": "vol-type-002",
            "extra_specs": {}
        }
    ]
}
<?xml version="1.0" encoding="UTF-8"?>
<volume_types xmlns="http://docs.openstack.org/volume/api/v1">
    <volume_type id="289da7f8-6440-407c-9fb4-7db01ec49164"
                 name="vol-type-001">
        <extra_specs>
            <extra_spec key="capabilities">gpu</extra_spec>
        </extra_specs>
    </volume_type>
    <volume_type id="96c3bda7-c82a-4f50-be73-ca7621794835"
                 name="vol-type-002" />
</volume_types>

This operation does not accept a request body.

POST
/v1/​{tenant_id}​/types
Create volume type

Creates a volume type.

 
Normal response codes
200
Request parameters
Parameter Style Type Description
tenant_id URI csapi:UUID

The unique identifier of the tenant or account.

volume_type plain csapi:string

A partial representation of a volume type used in the creation process.

{
    "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
/v1/​{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 csapi:UUID

The unique identifier of the tenant or account.

volume_type_id URI csapi:UUID

The unique identifier of an existing 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>

This operation does not accept a request body.

DELETE
/v1/​{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 csapi:UUID

The unique identifier of the tenant or account.

volume_type_id URI csapi:UUID

The unique identifier of an existing volume type.

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

Snapshots

POST
/v1/​{tenant_id}​/snapshots
Create snapshot

Creates a snapshot.

 
Normal response codes
201
Request parameters
Parameter Style Type Description
tenant_id URI csapi:UUID

The unique identifier of the tenant or account.

snapshot plain csapi:string

A partial representation of a snapshot used in the creation process.

{
    "snapshot": {
        "display_name": "snap-001",
        "display_description": "Daily backup",
        "volume_id": "521752a6-acf6-4b2d-bc7a-119f9148cd8c",
        "force": true
    }
}
<?xml version="1.0" encoding="UTF-8"?>
<snapshot xmlns="http://docs.openstack.org/volume/api/v1"
          name="snap-001" display_name="snap-001"
          display_description="Daily backup"
          volume_id="521752a6-acf6-4b2d-bc7a-119f9148cd8c"
          force="true"/>
{
    "snapshot": {
        "id": "3fbbcccf-d058-4502-8844-6feeffdf4cb5",
        "display_name": "snap-001",
        "display_description": "Daily backup",
        "volume_id": "521752a6-acf6-4b2d-bc7a-119f9148cd8c",
        "status": "available",
        "size": 30,
        "created_at": "2012-02-29T03:50:07Z"
    }
}
<?xml version="1.0" encoding="UTF-8"?>
<snapshot xmlns="http://docs.openstack.org/volume/api/v1"
          id="3fbbcccf-d058-4502-8844-6feeffdf4cb5"
          display_name="snap-001"
          display_description="Daily backup"
          volume_id="521752a6-acf6-4b2d-bc7a-119f9148cd8c"
          status="available"
          size="30"
          created_at="2012-02-29T03:50:07Z" />
GET
/v1/​{tenant_id}​/snapshots
List snapshots

Lists simple snapshot entities.

 
Normal response codes
200
Request parameters
Parameter Style Type Description
tenant_id URI csapi:UUID

The unique identifier of the tenant or account.

{
    "snapshots": [
        {
            "id": "3fbbcccf-d058-4502-8844-6feeffdf4cb5",
            "display_name": "snap-001",
            "display_description": "Daily backup",
            "volume_id": "521752a6-acf6-4b2d-bc7a-119f9148cd8c",
            "status": "available",
            "size": 30,
            "created_at": "2012-02-29T03:50:07Z"
        },
        {
            "id": "e479997c-650b-40a4-9dfe-77655818b0d2",
            "display_name": "snap-002",
            "display_description": "Weekly backup",
            "volume_id": "76b8950a-8594-4e5b-8dce-0dfa9c696358",
            "status": "available",
            "size": 25,
            "created_at": "2012-03-19T01:52:47Z"
        }
    ]
}
<?xml version="1.0" encoding="UTF-8"?>
<snapshots xmlns="http://docs.openstack.org/volume/api/v1">
    <snapshot id="3fbbcccf-d058-4502-8844-6feeffdf4cb5"
              display_name="snap-001"
              display_description="Daily backup"
              volume_id="521752a6-acf6-4b2d-bc7a-119f9148cd8c"
              status="available"
              size="30"
              created_at="2012-02-29T03:50:07Z" />
    <snapshot id="e479997c-650b-40a4-9dfe-77655818b0d2"
              display_name="snap-002"
              display_description="Weekly backup"
              volume_id="76b8950a-8594-4e5b-8dce-0dfa9c696358"
              status="available"
              size="25"
              created_at="2012-03-19T01:52:47Z" />
</snapshots>

This operation does not accept a request body.

GET
/v1/​{tenant_id}​/snapshots/detail
List snapshots (detailed)

Lists details for snapshot entities.

 
Normal response codes
200
Request parameters
Parameter Style Type Description
tenant_id URI csapi:UUID

The unique identifier of the tenant or account.

{
    "snapshots": [
        {
            "id": "3fbbcccf-d058-4502-8844-6feeffdf4cb5",
            "display_name": "snap-001",
            "display_description": "Daily backup",
            "volume_id": "521752a6-acf6-4b2d-bc7a-119f9148cd8c",
            "status": "available",
            "size": 30,
            "created_at": "2012-02-29T03:50:07Z"
        },
        {
            "id": "e479997c-650b-40a4-9dfe-77655818b0d2",
            "display_name": "snap-002",
            "display_description": "Weekly backup",
            "volume_id": "76b8950a-8594-4e5b-8dce-0dfa9c696358",
            "status": "available",
            "size": 25,
            "created_at": "2012-03-19T01:52:47Z"
        }
    ]
}
<?xml version="1.0" encoding="UTF-8"?>
<snapshots xmlns="http://docs.openstack.org/volume/api/v1">
    <snapshot id="3fbbcccf-d058-4502-8844-6feeffdf4cb5"
              display_name="snap-001"
              display_description="Daily backup"
              volume_id="521752a6-acf6-4b2d-bc7a-119f9148cd8c"
              status="available"
              size="30"
              created_at="2012-02-29T03:50:07Z" />
    <snapshot id="e479997c-650b-40a4-9dfe-77655818b0d2"
              display_name="snap-002"
              display_description="Weekly backup"
              volume_id="76b8950a-8594-4e5b-8dce-0dfa9c696358"
              status="available"
              size="25"
              created_at="2012-03-19T01:52:47Z" />
</snapshots>

This operation does not accept a request body.

GET
/v1/​{tenant_id}​/snapshots/​{snapshot_id}​
Show snapshot information

Shows information about a specified snapshot.

 
Normal response codes
200
Request parameters
Parameter Style Type Description
tenant_id URI csapi:UUID

The unique identifier of the tenant or account.

snapshot_id URI csapi:UUID

The unique identifier of an existing snapshot.

{
    "snapshot": {
        "id": "3fbbcccf-d058-4502-8844-6feeffdf4cb5",
        "display_name": "snap-001",
        "display_description": "Daily backup",
        "volume_id": "521752a6-acf6-4b2d-bc7a-119f9148cd8c",
        "status": "available",
        "size": 30,
        "created_at": "2012-02-29T03:50:07Z"
    }
}
<?xml version="1.0" encoding="UTF-8"?>
<snapshot xmlns="http://docs.openstack.org/volume/api/v1"
          id="3fbbcccf-d058-4502-8844-6feeffdf4cb5"
          display_name="snap-001"
          display_description="Daily backup"
          volume_id="521752a6-acf6-4b2d-bc7a-119f9148cd8c"
          status="available"
          size="30"
          created_at="2012-02-29T03:50:07Z" />

This operation does not accept a request body.

DELETE
/v1/​{tenant_id}​/snapshots/​{snapshot_id}​
Delete snapshot

Deletes a specified snapshot.

 
Normal response codes
202
Request parameters
Parameter Style Type Description
tenant_id URI csapi:UUID

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
/v1/​{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 csapi:UUID

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": "v1"
        },
        "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">v1</meta>
    </metadata>
</snapshot>

This operation does not accept a request body.

PUT
/v1/​{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 csapi:UUID

The unique identifier of the tenant or account.

snapshot_id URI csapi:UUID

The unique identifier of an existing snapshot.

metadata (Optional) plain xsd:string

One or more metadata key and value pairs to set or unset for the snapshot.

To unset a metadata key value, specify only the key name.

To set a metadata key value, specify the key and value pair.

The Block Storage server does not respect case-sensitive key names. For example, if you specify both "key": "v1" and "KEY": "V1", the server sets and returns only the KEY key and value pair.

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