# Volumes

## Create

**post** `/v2/volumes`

To create a new volume, send a POST request to `/v2/volumes`. Optionally, a `filesystem_type` attribute may be provided in order to automatically format the volume's filesystem. Pre-formatted volumes are automatically mounted when attached to Ubuntu, Debian, Fedora, Fedora Atomic, and CentOS Droplets created on or after April 26, 2018. Attaching pre-formatted volumes to Droplets without support for auto-mounting is not recommended.

### Returns

- **volume:** `object { id, created_at, description, 7 more }`

  - **id:** `string`

    The unique identifier for the block storage volume.

  - **created\_at:** `string`

    A time value given in ISO8601 combined date and time format that represents when the block storage volume was created.

  - **description:** `string`

    An optional free-form text field to describe a block storage volume.

  - **droplet\_ids:** `array of number`

    An array containing the IDs of the Droplets the volume is attached to. Note that at this time, a volume can only be attached to a single Droplet.

  - **filesystem\_label:** `string`

    The label currently applied to the filesystem.

  - **filesystem\_type:** `string`

    The type of filesystem currently in-use on the volume.

  - **name:** `string`

    A human-readable name for the block storage volume. Must be lowercase and be composed only of numbers, letters and "-", up to a limit of 64 characters. The name must begin with a letter.

  - **region:** `Region`

    The region that the block storage volume is located in. When setting a region, the value should be the slug identifier for the region. When you query a block storage volume, the entire region object will be returned.

  - **size\_gigabytes:** `number`

    The size of the block storage volume in GiB (1024^3). This field does not apply  when creating a volume from a snapshot.

  - **tags:** `array of string`

    A flat array of tag names as strings applied to the resource. <br><br>Requires `tag:read` scope.

## Retrieve

**get** `/v2/volumes/{volume_id}`

To show information about a block storage volume, send a GET request to `/v2/volumes/$VOLUME_ID`.

### Returns

- **volume:** `object { id, created_at, description, 7 more }`

  - **id:** `string`

    The unique identifier for the block storage volume.

  - **created\_at:** `string`

    A time value given in ISO8601 combined date and time format that represents when the block storage volume was created.

  - **description:** `string`

    An optional free-form text field to describe a block storage volume.

  - **droplet\_ids:** `array of number`

    An array containing the IDs of the Droplets the volume is attached to. Note that at this time, a volume can only be attached to a single Droplet.

  - **filesystem\_label:** `string`

    The label currently applied to the filesystem.

  - **filesystem\_type:** `string`

    The type of filesystem currently in-use on the volume.

  - **name:** `string`

    A human-readable name for the block storage volume. Must be lowercase and be composed only of numbers, letters and "-", up to a limit of 64 characters. The name must begin with a letter.

  - **region:** `Region`

    The region that the block storage volume is located in. When setting a region, the value should be the slug identifier for the region. When you query a block storage volume, the entire region object will be returned.

  - **size\_gigabytes:** `number`

    The size of the block storage volume in GiB (1024^3). This field does not apply  when creating a volume from a snapshot.

  - **tags:** `array of string`

    A flat array of tag names as strings applied to the resource. <br><br>Requires `tag:read` scope.

## List

**get** `/v2/volumes`

To list all of the block storage volumes available on your account, send a GET request to `/v2/volumes`.

## Filtering Results

### By Region

The `region` may be provided as query parameter in order to restrict results to volumes available in a specific region. For example: `/v2/volumes?region=nyc1`

### By Name

It is also possible to list volumes on your account that match a specified name. To do so, send a GET request with the volume's name as a query parameter to `/v2/volumes?name=$VOLUME_NAME`.
**Note:** You can only create one volume per region with the same name.

### By Name and Region

It is also possible to retrieve information about a block storage volume by name. To do so, send a GET request with the volume's name and the region slug for the region it is located in as query parameters to `/v2/volumes?name=$VOLUME_NAME&region=nyc1`.

### Returns

- **meta:** `MetaProperties`

  Information about the response itself.

- **volumes:** `array of object { id, created_at, description, 7 more }`

  Array of volumes.

  - **id:** `string`

    The unique identifier for the block storage volume.

  - **created\_at:** `string`

    A time value given in ISO8601 combined date and time format that represents when the block storage volume was created.

  - **description:** `string`

    An optional free-form text field to describe a block storage volume.

  - **droplet\_ids:** `array of number`

    An array containing the IDs of the Droplets the volume is attached to. Note that at this time, a volume can only be attached to a single Droplet.

  - **filesystem\_label:** `string`

    The label currently applied to the filesystem.

  - **filesystem\_type:** `string`

    The type of filesystem currently in-use on the volume.

  - **name:** `string`

    A human-readable name for the block storage volume. Must be lowercase and be composed only of numbers, letters and "-", up to a limit of 64 characters. The name must begin with a letter.

  - **region:** `Region`

    The region that the block storage volume is located in. When setting a region, the value should be the slug identifier for the region. When you query a block storage volume, the entire region object will be returned.

  - **size\_gigabytes:** `number`

    The size of the block storage volume in GiB (1024^3). This field does not apply  when creating a volume from a snapshot.

  - **tags:** `array of string`

    A flat array of tag names as strings applied to the resource. <br><br>Requires `tag:read` scope.

- **links:** `PageLinks`

## Delete

**delete** `/v2/volumes/{volume_id}`

To delete a block storage volume, destroying all data and removing it from your account, send a DELETE request to `/v2/volumes/$VOLUME_ID`.
No response body will be sent back, but the response code will indicate success. Specifically, the response code will be a 204, which means that the action was successful with no returned body data.

## Delete By Name

**delete** `/v2/volumes`

Block storage volumes may also be deleted by name by sending a DELETE request with the volume's **name** and the **region slug** for the region it is located in as query parameters to `/v2/volumes?name=$VOLUME_NAME&region=nyc1`.
No response body will be sent back, but the response code will indicate success. Specifically, the response code will be a 204, which means that the action was successful with no returned body data.