Volume API

Creates an empty volume or restores a snapshot into a new volume.

Explicit null is invalid for the optional snapshot field. Use omission for an empty volume. Invalid policy, insufficient quota, or inadequate eligible pool capacity returns 422 with the corresponding error code.

{
  "data": { "id": "vol_data01", "state": "creating" },
  "operation": { "id": "op_volume01", "state": "queued" },
  "request_id": "req_storage01"
}

Returns id, revision, name, region_id, storage_policy_id, size_gib, state, health, attachments, and labels. Requires volumes:read. The response includes the configuration ETag.

Lists volumes using the selected region, state, and label filters.

List the collection with filters region_id, state, and label and the standard pagination parameters. States include creating, available, attached, resizing, deleting, and error. Replica health is reported separately from lifecycle state.

Creates a writable volume attachment for the target droplet.

Requires volumes:write, access to the target droplet, and the volume's current If-Match. Send droplet_id as a required string. The writable attachment mode is read_write, which is also the default; unsupported modes are rejected.

The response is 202 with an attachment summary and operation. A second writable attachment returns 409 volume_in_use. A different project or region returns 422 invalid_reference. The guest must discover and mount the device separately.

Detaches the selected volume attachment.

Requires volumes:write and the current volume revision. A root attachment requires a stopped droplet. A data attachment requires guest writes to have stopped before removal.

The API does not infer whether an application has safely unmounted its filesystem. An unreachable writer returns a conflict until ownership and fencing are resolved. See Detach a volume.

Expands the volume's block-device capacity.

Send type=resize and positive integer size_gib with the current If-Match. The requested value must exceed the current size and fit policy and quota limits. A smaller or equal size returns 422 invalid_size.

The operation expands the block device. It does not expand a guest partition or filesystem. A completed expansion cannot be reversed by another resize request.

Captures a volume snapshot with the requested consistency mode.

Requires volumes:write. Send name and optional consistency, whose values are crash, guest, or application, with default crash. Application mode requires hook_set_id referencing an approved guest hook set. Unsupported required consistency returns 422 unsupported_consistency; it does not downgrade the request.

The 202 response identifies the snapshot and operation. Use only a ready, complete recovery point for restoration. Snapshots documents groups, freeze behavior, and retained capacity.

Deletes an unattached volume while retaining independent recovery copies.

Requires volumes:write and If-Match. Active attachments return 409 volume_in_use. Accepted deletion returns 202; retained snapshots and independent backups keep their own lifecycle. Inspect the operation for cleanup failures before assuming pool capacity was released.

Updates explicit volume I/O limits.

Requires volumes:write and the volume ETag. Writable fields are read_iops, write_iops, read_bytes_per_second, and write_bytes_per_second.

A positive integer sets an explicit cap; null removes that field's override and restores policy inheritance. Omission preserves the current override. Zero, fractions, unsupported fields, and values above policy ceilings return 422 without changing the submitted override set.

Accepted application returns 202. Reads report requested and effective values and their policy sources. Limits do not reserve a minimum service rate. See storage performance and discard accounting.