Skip to content
DigitalOcean Gradient™ AI Agentic Cloud SDK Docs
  • Auto
  • Light
  • Dark

Initiate By ID

API Reference
GPU Droplets
Volumes
Actions
Initiate A Block Storage Action By Volume Id
post/v2/volumes/{volume_id}/actions

To initiate an action on a block storage volume by Id, send a POST request to ~/v2/volumes/$VOLUME_ID/actions. The body should contain the appropriate attributes for the respective action.

Attach a Block Storage Volume to a Droplet

Attribute Details
type This must be attach
droplet_id Set to the Droplet's ID
region Set to the slug representing the region where the volume is located

Each volume may only be attached to a single Droplet. However, up to fifteen volumes may be attached to a Droplet at a time. Pre-formatted volumes will be automatically mounted to Ubuntu, Debian, Fedora, Fedora Atomic, and CentOS Droplets created on or after April 26, 2018 when attached. On older Droplets, additional configuration is required.

Remove a Block Storage Volume from a Droplet

Attribute Details
type This must be detach
droplet_id Set to the Droplet's ID
region Set to the slug representing the region where the volume is located

Resize a Volume

Attribute Details
type This must be resize
size_gigabytes The new size of the block storage volume in GiB (1024^3)
region Set to the slug representing the region where the volume is located

Volumes may only be resized upwards. The maximum size for a volume is 16TiB.

Path ParametersExpand Collapse
volume_id: string
Query ParametersExpand Collapse
page: optional number

Which 'page' of paginated results to return.

minimum1
per_page: optional number

Number of items returned per page

minimum1
maximum200
Body ParametersExpand Collapse
body: object { droplet_id, type, region, tags } or object { droplet_id, type, region } or object { size_gigabytes, type, region }
Accepts one of the following:
UnionMember0 = object { droplet_id, type, region, tags }
droplet_id: number

The unique identifier for the Droplet the volume will be attached or detached from.

type: "attach" or "detach" or "resize"

The volume action to initiate.

Accepts one of the following:
"attach"
"detach"
"resize"
region: optional "ams1" or "ams2" or "ams3" or 12 more

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

Accepts one of the following:
"ams1"
"ams2"
"ams3"
"blr1"
"fra1"
"lon1"
"nyc1"
"nyc2"
"nyc3"
"sfo1"
"sfo2"
"sfo3"
"sgp1"
"tor1"
"syd1"
tags: optional array of string

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.

UnionMember1 = object { droplet_id, type, region }
droplet_id: number

The unique identifier for the Droplet the volume will be attached or detached from.

type: "attach" or "detach" or "resize"

The volume action to initiate.

Accepts one of the following:
"attach"
"detach"
"resize"
region: optional "ams1" or "ams2" or "ams3" or 12 more

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

Accepts one of the following:
"ams1"
"ams2"
"ams3"
"blr1"
"fra1"
"lon1"
"nyc1"
"nyc2"
"nyc3"
"sfo1"
"sfo2"
"sfo3"
"sgp1"
"tor1"
"syd1"
UnionMember2 = object { size_gigabytes, type, region }
size_gigabytes: number

The new size of the block storage volume in GiB (1024^3).

maximum16384
type: "attach" or "detach" or "resize"

The volume action to initiate.

Accepts one of the following:
"attach"
"detach"
"resize"
region: optional "ams1" or "ams2" or "ams3" or 12 more

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

Accepts one of the following:
"ams1"
"ams2"
"ams3"
"blr1"
"fra1"
"lon1"
"nyc1"
"nyc2"
"nyc3"
"sfo1"
"sfo2"
"sfo3"
"sgp1"
"tor1"
"syd1"
ReturnsExpand Collapse
action: optional VolumeAction { resource_id, type }
resource_id: optional number
type: optional string

This is the type of action that the object represents. For example, this could be "attach_volume" to represent the state of a volume attach action.

Initiate A Block Storage Action By Volume Id
  • http
  • typescript
  • python
curl https://api.digitalocean.com/v2/volumes/$VOLUME_ID/actions \
    -H 'Content-Type: application/json' \
    -H "Authorization: Bearer $DIGITALOCEAN_ACCESS_TOKEN" \
    -d '{
          "droplet_id": 11612190,
          "type": "attach",
          "region": "nyc3",
          "tags": [
            "base-image",
            "prod"
          ]
        }'
{
  "action": {
    "id": 72531856,
    "status": "completed",
    "type": "attach_volume",
    "started_at": "2020-11-12T17:51:03Z",
    "completed_at": "2020-11-12T17:51:14Z",
    "resource_type": "volume",
    "region": {
      "name": "New York 1",
      "slug": "nyc1",
      "sizes": [
        "s-1vcpu-1gb",
        "s-1vcpu-2gb",
        "s-1vcpu-3gb",
        "s-2vcpu-2gb",
        "s-3vcpu-1gb",
        "s-2vcpu-4gb",
        "s-4vcpu-8gb",
        "s-6vcpu-16gb",
        "s-8vcpu-32gb",
        "s-12vcpu-48gb",
        "s-16vcpu-64gb",
        "s-20vcpu-96gb",
        "s-24vcpu-128gb",
        "s-32vcpu-192gb"
      ],
      "features": [
        "private_networking",
        "backups",
        "ipv6",
        "metadata"
      ],
      "available": true
    },
    "region_slug": "nyc1"
  }
}
Returns Examples
{
  "action": {
    "id": 72531856,
    "status": "completed",
    "type": "attach_volume",
    "started_at": "2020-11-12T17:51:03Z",
    "completed_at": "2020-11-12T17:51:14Z",
    "resource_type": "volume",
    "region": {
      "name": "New York 1",
      "slug": "nyc1",
      "sizes": [
        "s-1vcpu-1gb",
        "s-1vcpu-2gb",
        "s-1vcpu-3gb",
        "s-2vcpu-2gb",
        "s-3vcpu-1gb",
        "s-2vcpu-4gb",
        "s-4vcpu-8gb",
        "s-6vcpu-16gb",
        "s-8vcpu-32gb",
        "s-12vcpu-48gb",
        "s-16vcpu-64gb",
        "s-20vcpu-96gb",
        "s-24vcpu-128gb",
        "s-32vcpu-192gb"
      ],
      "features": [
        "private_networking",
        "backups",
        "ipv6",
        "metadata"
      ],
      "available": true
    },
    "region_slug": "nyc1"
  }
}