POST
/v2/volumesCreate a block storage volume
Creates a block storage volume, optionally from a snapshot. Set filesystem_type to format the volume automatically, and provide snapshot_id when creating from a snapshot. Pre-formatted volumes auto-mount only on supported Droplets created on or after April 26, 2018; attaching them to unsupported Droplets is not recommended.
- IdempotentThe SDK sends
Idempotency-Key, so a retried request is only applied once.
Volume creation details, including volume attributes and optional filesystem formatting.
idstringoptional
The unique identifier for the block storage volume.
droplet_idsarray<integer>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.
namestringrequired
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.
descriptionstringoptional
An optional free-form text field to describe a block storage volume.
size_gigabytesintegerrequired
The size of the block storage volume in GiB (1024^3). This field does not apply when creating a volume from a snapshot.
created_atstringoptional
A time value given in ISO8601 combined date and time format that represents when the block storage volume was created.
tagsarray<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. <br><br>Requires `tag:create` scope.
snapshot_idstringoptional
The unique identifier for the volume snapshot from which to create the volume.
filesystem_typestringoptional
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.
regionstringrequired
The slug identifier for the region where the resource will initially be available.
filesystem_labelobjectoptional
201Returns a JSON object containing the created volume and its standard attributes.
volumeobjectoptional
400Returned when the request body cannot be parsed.
idstringrequired
A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."
messagestringrequired
A message providing additional information about the error, including details to help resolve it when possible.
request_idstringoptional
Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.
401Returned when authentication fails because the credentials are invalid.
idstringrequired
A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."
messagestringrequired
A message providing additional information about the error, including details to help resolve it when possible.
request_idstringoptional
Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.
404Returned when the requested resource is not found.
idstringrequired
A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."
messagestringrequired
A message providing additional information about the error, including details to help resolve it when possible.
request_idstringoptional
Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.
429Returned when the API rate limit has been exceeded.
idstringrequired
A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."
messagestringrequired
A message providing additional information about the error, including details to help resolve it when possible.
request_idstringoptional
Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.
500Returned when a server error occurs.
idstringrequired
A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."
messagestringrequired
A message providing additional information about the error, including details to help resolve it when possible.
request_idstringoptional
Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.
defaultReturned when an unexpected error occurs.
idstringrequired
A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."
messagestringrequired
A message providing additional information about the error, including details to help resolve it when possible.
request_idstringoptional
Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.
Error handling
A 400 is returned when the request body cannot be parsed, so send a valid volume creation payload. A 401 indicates invalid credentials, a 404 indicates that a resource was not found, a 429 indicates that the API rate limit was exceeded, and a 500 indicates a server error. When creating from a snapshot, use a valid snapshot_id; filesystem_type is optional and controls automatic formatting.