Skip to content
Gradient SDK Docs
  • Auto
  • Light
  • Dark

Create

Create a New Block Storage Volume
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.

Body Parameters
bodyunion
One of the following 2 object variants:
Hide ParametersShow Parameters
UnionMember0object
Hide ParametersShow Parameters
namestring

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.

regionenum
"ams1" OR "ams2" OR "ams3" OR 12 more

The slug identifier for the region where the resource will initially be available.

Hide ParametersShow Parameters
"ams1"
"ams2"
"ams3"
"blr1"
"fra1"
"lon1"
"nyc1"
"nyc2"
"nyc3"
"sfo1"
"sfo2"
"sfo3"
"sgp1"
"tor1"
"syd1"
size_gigabytesnumber

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

idstring
optional

The unique identifier for the block storage volume.

created_atstring
optional

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

descriptionstring
optional

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

droplet_idsarray of number
optional

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_labelstring
optional

The label applied to the filesystem. Labels for ext4 type filesystems may contain 16 characters while labels for xfs type filesystems are limited to 12 characters. May only be used in conjunction with filesystem_type.

maxLength16
filesystem_typestring
optional

The name of the filesystem type to be used on the volume. When provided, the volume will automatically be formatted to the specified filesystem type. Currently, the available options are ext4 and xfs. 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 other Droplets is not recommended.

snapshot_idstring
optional

The unique identifier for the volume snapshot from which to create the volume.

tagsarray of string
optional

A flat array of tag names as strings to be applied to the resource. Tag names may be for either existing or new tags.

Requires tag:create scope.

UnionMember1object
Hide ParametersShow Parameters
namestring

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.

regionenum
"ams1" OR "ams2" OR "ams3" OR 12 more

The slug identifier for the region where the resource will initially be available.

Hide ParametersShow Parameters
"ams1"
"ams2"
"ams3"
"blr1"
"fra1"
"lon1"
"nyc1"
"nyc2"
"nyc3"
"sfo1"
"sfo2"
"sfo3"
"sgp1"
"tor1"
"syd1"
size_gigabytesnumber

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

idstring
optional

The unique identifier for the block storage volume.

created_atstring
optional

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

descriptionstring
optional

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

droplet_idsarray of number
optional

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_labelstring
optional

The label applied to the filesystem. Labels for ext4 type filesystems may contain 16 characters while labels for xfs type filesystems are limited to 12 characters. May only be used in conjunction with filesystem_type.

maxLength12
filesystem_typestring
optional

The name of the filesystem type to be used on the volume. When provided, the volume will automatically be formatted to the specified filesystem type. Currently, the available options are ext4 and xfs. 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 other Droplets is not recommended.

snapshot_idstring
optional

The unique identifier for the volume snapshot from which to create the volume.

tagsarray of string
optional

A flat array of tag names as strings to be applied to the resource. Tag names may be for either existing or new tags.

Requires tag:create scope.

Returns
volumeobject
optional
Hide ParametersShow Parameters
idstring
optional

The unique identifier for the block storage volume.

created_atstring
optional

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

descriptionstring
optional

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

droplet_idsarray of number
optional

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_labelstring
optional

The label currently applied to the filesystem.

filesystem_typestring
optional

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

namestring
optional

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.

regionavailablebooleanfeaturesarray of stringnamestringsizesarray of stringslugstringRegion
optional

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_gigabytesnumber
optional

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

tagsarray of string
optional

A flat array of tag names as strings applied to the resource.

Requires tag:read scope.

curl https://api.digitalocean.com//v2/volumes \
    -H 'Content-Type: application/json' \
    -H "Authorization: Bearer $GRADIENTAI_API_KEY" \
    -d '{
      "name": "example",
      "region": "nyc3",
      "size_gigabytes": 10,
      "description": "Block store for examples",
      "filesystem_label": "example",
      "filesystem_type": "ext4",
      "snapshot_id": "b0798135-fb76-11eb-946a-0a58ac146f33",
      "tags": [
        "base-image",
        "prod"
      ]
    }'
200 Example
{
  "volume": {
    "description": "Block store for examples",
    "filesystem_label": "example",
    "filesystem_type": "ext4",
    "name": "example",
    "size_gigabytes": 10,
    "tags": [
      "base-image",
      "prod"
    ]
  }
}