For AI agents: The documentation index is at https://docs.digitalocean.com/llms.txt. Markdown versions of pages use the same URL with index.html.md in place of the HTML page (for example, append index.html.md to the directory path instead of opening the HTML document).

Usage

client.volumes.create(
    body={
        "name": "example",
        "description": "Block store for examples",
        "size_gigabytes": 10,
        ...,
    },
)

Description

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.

Parameters

id string optional read-only

Example: 506f78a4-e098-11e5-ad9f-000f53306ae1

The unique identifier for the block storage volume.

droplet_ids array of integers or null optional read-only

Example: []

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.

name string required

Example: example

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.

description string optional

Example: Block store for examples

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

size_gigabytes integer required

Example: 10

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

created_at string optional read-only

Example: 2020-03-02T17:00:49Z

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

tags array of strings or null optional

Example: ['base-image', 'prod']

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.

snapshot_id string optional

Example: b0798135-fb76-11eb-946a-0a58ac146f33

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

filesystem_type string optional

Example: ext4

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.

region string required

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

One of: ams1, ams2, ams3, blr1, fra1, lon1, nyc1, nyc2, nyc3, sfo1, sfo2, sfo3, sgp1, tor1, syd1

filesystem_label object optional

Request Sample

import os
from pydo import Client

client = Client(token=os.environ.get("DIGITALOCEAN_TOKEN"))

req = {
  "size_gigabytes": 10,
  "name": "ext4-example",
  "description": "Block store for examples",
  "region": "nyc1",
  "filesystem_type": "ext4",
  "filesystem_label": "ext4_volume_01"
}

resp = client.volumes.create(body=req)

Response Example

{
  "volume": {
    "id": "506f78a4-e098-11e5-ad9f-000f53306ae1",
    "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
    },
    "droplet_ids": [],
    "name": "example",
    "description": "Block store for examples",
    "size_gigabytes": 10,
    "filesystem_type": "ext4",
    "filesystem_label": "example",
    "created_at": "2020-03-02T17:00:49Z"
  }
}

More Information

See /v2/volumes in the API reference for additional detail on responses, headers, parameters, and more.