Skip to main content
POST
Create Volume

Authorizations

Authorization
string
header
required

A Fly API token with access to the requested organization or resource. Send it as Authorization: Bearer <Fly API token>.

Path Parameters

app_name
string
required

Fly App Name

Body

application/json

Request body

auto_backup_enabled
boolean

Take daily automatic snapshots of the volume. Defaults to true.

compute
object

Requirements of the Machine that will use the volume, so that the volume is placed on a host that can run it. Uses cpus, memory_mb, cpu_kind, host_dedication_id, and required_host_features.

compute_image
string

Ignored.

encrypted
boolean

Encrypt the volume at rest. Defaults to true. When forking, the source volume's setting is used.

fstype
enum<string>

Filesystem to format the volume with: ext4, or raw for an unformatted block device.

Available options:
ext4,
raw
name
string

Name of the volume: at most 30 lowercase letters, digits, and underscores. Required.

region
string

Region to create the volume in. Accepts the same values as the region of Create Machine. When forking, defaults to the source volume's region; otherwise defaults to the region of the API server handling the request.

require_unique_zone
boolean

Place the volume on a host that has no other volume of the app with the same name in the region, so that Machines using these volumes don't share a host. Fails with 400 if no such host is available.

size_gb
integer

Size of the volume in GiB, from 1 to the organization's maximum (500 by default). Required unless forking, in which case it must be omitted and the source volume's size is used.

snapshot_id
string

ID of a snapshot to restore into the new volume. Mutually exclusive with source_volume_id.

snapshot_retention
integer

Number of days to keep snapshots of the volume, from 1 to 60. Defaults to 5.

source_volume_id
string

ID of a volume to fork: the new volume starts as a copy of it. The volume must belong to an app in the same organization.

unique_zone_app_wide
boolean

With require_unique_zone, avoid hosts with any volume of the app in the region, not just volumes with the same name.

Response

200 - application/json

OK

attached_alloc_id
string

Always null.

Deprecated: volumes are no longer attached to Nomad allocations.

attached_machine_id
string

ID of the Machine the volume is attached to, or null if it is not attached.

auto_backup_enabled
boolean

Whether daily automatic snapshots are taken.

block_size
integer

Size of a filesystem block, in bytes. See blocks.

blocks
integer

Size of the volume's filesystem, in blocks of block_size bytes, as last reported by a Machine that mounted the volume. 0 if never reported, if the host could not be reached, or with summary=true.

blocks_avail
integer

Number of filesystem blocks available to unprivileged users. See blocks.

blocks_free
integer

Number of free filesystem blocks, including blocks reserved for the root user. See blocks.

bytes_total
integer

Size of the volume, in bytes. 0 if the host could not be reached or with summary=true.

bytes_used
integer

Bytes of storage the volume occupies on its host. Volumes are thinly provisioned, so this grows as blocks are written and does not shrink when files are deleted. It is not the filesystem's usage; use blocks and blocks_free for that. 0 if the host could not be reached or with summary=true.

created_at
string

When the volume was created.

encrypted
boolean

Whether the volume is encrypted at rest.

fstype
string

Filesystem the volume was formatted with: ext4, or raw for an unformatted block device.

host_features
string[]

Features of the volume's host. Only returned when the request sets the fly-include-host-features: true header.

host_status
enum<string>

Whether Fly.io could reach the volume's host: ok if it could, unreachable or unknown if it could not, in which case host-reported fields are missing.

Available options:
ok,
unknown,
unreachable
id
string

Unique ID of the volume, such as vol_1234567890abcdef.

name
string

Name of the volume. Several volumes of an app can share a name.

region
string

Code of the region the volume is in.

required_host_features
string[]

Host features the volume's host was required to have; see compute.required_host_features in the create request.

size_gb
integer

Size of the volume, in GiB.

snapshot_retention
integer

Number of days snapshots of the volume are kept.

state
string

State of the volume, such as creating, created, extending, restoring, hydrating, scheduling_destroy, pending_destroy, destroying, destroyed, or failed.

type
enum<string>

Kind of volume: local for regular volumes, or cache for volumes that hold disposable data and support neither snapshots nor restores.

Available options:
local,
cache
zone
string

Identifies the host the volume is on. Volumes with different zones are on different hosts.