fly-io Volumes API
Operations for managing persistent storage volumes that can be attached to Fly Machines. Volumes provide durable block storage that persists across Machine restarts.
Work with this as data
Every API here is available over the APIs.io API and to AI agents over MCP.
MCP server
One button, every client — Claude, Cursor, VS Code and the rest.
https://apis.io/mcp
Tools for apis
7 MCP tools reach this
find_apisBrowse and filter every API in the catalog.get_api_artifactsOne API's artifacts, grouped by type.get_openapiThe primary OpenAPI for this API.find_similar_apisAPIs that look like this one.apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.resolveTurn a domain, URL or GitHub org into the provider it belongs to.find_cohortsEvery scored population of providers in the catalog.
Call it yourself
curl for this page
This API
curl "https://apis.io/api/v1/apis/fly-io:fly-io-volumes-api"
All apis
curl "https://apis.io/api/v1/apis?limit=25"Discovery needs no key. Ratings and market analysis are Pro.
Get an API key
Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.
A second provider on the same verified email joins the account you already have.
OpenAPI Specification
openapi: 3.2.0
info:
title: Machines Volumes API
description: This site hosts documentation generated from the Fly.io Machines API OpenAPI specification. Visit our complete Machines API docs for how to get started, more information about each endpoint, parameter descriptions, and examples.
contact: {}
license:
name: Apache 2.0
url: http://www.apache.org/licenses/LICENSE-2.0.html
version: '1.0'
servers:
- url: https://api.machines.dev
security:
- FlyBearerAuth: []
tags:
- name: Volumes
description: This site hosts documentation generated from the Fly.io Machines API OpenAPI specification. Visit our complete Machines API docs for details about using the Volumes resource.
paths:
/v1/apps/{app_name}/volumes:
get:
tags:
- Volumes
summary: List Volumes
description: List all volumes associated with a specific app.
operationId: Volumes_list
parameters:
- name: app_name
in: path
description: Fly App Name
required: true
schema:
type: string
- name: summary
in: query
description: Only return summary info about volumes (omit blocks, block size, etc)
schema:
type: boolean
- name: cursor
in: query
description: Value of the fly-next-cursor response header from the previous page. Requires limit.
schema:
type: string
- name: limit
in: query
description: The number of volumes to fetch (must be between 1 and 1000). Providing a limit enables pagination. This limit is advisory; responses may be shorter, or even empty, even when more volumes remain.
schema:
type: integer
responses:
'200':
description: OK
headers:
fly-next-cursor:
description: Pagination cursor for the next page. Absent when no more volumes remain. Cursor expires 30 minutes after the first page was requested.
schema:
type: string
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/Volume'
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
post:
tags:
- Volumes
summary: Create Volume
description: Create a volume for a specific app using the details provided in the request body.
operationId: Volumes_create
parameters:
- name: app_name
in: path
description: Fly App Name
required: true
schema:
type: string
requestBody:
description: Request body
content:
application/json:
schema:
$ref: '#/components/schemas/CreateVolumeRequest'
required: true
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/Volume'
x-codegen-request-body-name: request
/v1/apps/{app_name}/volumes/{volume_id}:
get:
tags:
- Volumes
summary: Get Volume
description: Retrieve details about a specific volume by its ID within an app.
operationId: Volumes_get_by_id
parameters:
- name: app_name
in: path
description: Fly App Name
required: true
schema:
type: string
- name: volume_id
in: path
description: Volume ID
required: true
schema:
type: string
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/Volume'
put:
tags:
- Volumes
summary: Update Volume
description: Update a volume's configuration using the details provided in the request body.
operationId: Volumes_update
parameters:
- name: app_name
in: path
description: Fly App Name
required: true
schema:
type: string
- name: volume_id
in: path
description: Volume ID
required: true
schema:
type: string
requestBody:
description: Request body
content:
application/json:
schema:
$ref: '#/components/schemas/UpdateVolumeRequest'
required: true
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/Volume'
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
x-codegen-request-body-name: request
delete:
tags:
- Volumes
summary: Destroy Volume
description: Delete a specific volume within an app by volume ID.
operationId: Volume_delete
parameters:
- name: app_name
in: path
description: Fly App Name
required: true
schema:
type: string
- name: volume_id
in: path
description: Volume ID
required: true
schema:
type: string
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/Volume'
/v1/apps/{app_name}/volumes/{volume_id}/extend:
put:
tags:
- Volumes
summary: Extend Volume
description: Extend a volume's size within an app using the details provided in the request body.
operationId: Volumes_extend
parameters:
- name: app_name
in: path
description: Fly App Name
required: true
schema:
type: string
- name: volume_id
in: path
description: Volume ID
required: true
schema:
type: string
requestBody:
description: Request body
content:
application/json:
schema:
$ref: '#/components/schemas/ExtendVolumeRequest'
required: true
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/ExtendVolumeResponse'
x-codegen-request-body-name: request
/v1/apps/{app_name}/volumes/{volume_id}/snapshots:
get:
tags:
- Volumes
summary: List Snapshots
description: List all snapshots for a specific volume within an app.
operationId: Volumes_list_snapshots
parameters:
- name: app_name
in: path
description: Fly App Name
required: true
schema:
type: string
- name: volume_id
in: path
description: Volume ID
required: true
schema:
type: string
responses:
'200':
description: OK
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/VolumeSnapshot'
post:
tags:
- Volumes
summary: Create Snapshot
description: Create a snapshot for a specific volume within an app.
operationId: createVolumeSnapshot
parameters:
- name: app_name
in: path
description: Fly App Name
required: true
schema:
type: string
- name: volume_id
in: path
description: Volume ID
required: true
schema:
type: string
responses:
'200':
description: OK
content: {}
components:
schemas:
UpdateVolumeRequest:
type: object
properties:
auto_backup_enabled:
type: boolean
snapshot_retention:
type: integer
fly.MachineGuest:
type: object
properties:
cpu_kind:
type: string
cpus:
type: integer
gpu_kind:
type: string
gpus:
type: integer
host_dedication_id:
type: string
kernel_args:
type: array
items:
type: string
max_memory_mb:
type: integer
memory_mb:
type: integer
persist_rootfs:
type: string
description: 'Deprecated: use MachineConfig.Rootfs instead'
enum:
- never
- always
- restart
required_host_features:
type: array
items:
type: string
main.statusCode:
type: string
enum:
- unknown
- insufficient_capacity
- volume_placement_capacity
- name_taken
x-enum-varnames:
- unknown
- capacityErr
- volumePlacementCapacityErr
- nameTakenErr
CreateVolumeRequest:
type: object
properties:
auto_backup_enabled:
type: boolean
description: enable scheduled automatic snapshots. Defaults to `true`
compute:
$ref: '#/components/schemas/fly.MachineGuest'
compute_image:
type: string
encrypted:
type: boolean
fstype:
type: string
name:
type: string
region:
type: string
require_unique_zone:
type: boolean
size_gb:
type: integer
snapshot_id:
type: string
description: restore from snapshot
snapshot_retention:
type: integer
source_volume_id:
type: string
description: fork from remote volume
unique_zone_app_wide:
type: boolean
ExtendVolumeResponse:
type: object
properties:
needs_restart:
type: boolean
volume:
$ref: '#/components/schemas/Volume'
VolumeSnapshot:
type: object
properties:
created_at:
type: string
digest:
type: string
id:
type: string
retention_days:
type: integer
size:
type: integer
status:
type: string
volume_size:
type: integer
Volume:
type: object
properties:
attached_alloc_id:
type: string
attached_machine_id:
type: string
auto_backup_enabled:
type: boolean
block_size:
type: integer
blocks:
type: integer
blocks_avail:
type: integer
blocks_free:
type: integer
bytes_total:
type: integer
bytes_used:
type: integer
created_at:
type: string
encrypted:
type: boolean
fstype:
type: string
host_features:
type: array
items:
type: string
host_status:
type: string
enum:
- ok
- unknown
- unreachable
id:
type: string
name:
type: string
region:
type: string
required_host_features:
type: array
items:
type: string
size_gb:
type: integer
snapshot_retention:
type: integer
state:
type: string
type:
type: string
enum:
- local
- cache
zone:
type: string
ErrorResponse:
type: object
properties:
details:
type: object
description: Deprecated
error:
type: string
status:
$ref: '#/components/schemas/main.statusCode'
ExtendVolumeRequest:
type: object
properties:
size_gb:
type: integer
securitySchemes:
FlyBearerAuth:
type: http
scheme: bearer
description: 'A Fly API token with access to the requested organization or resource. Send it as `Authorization: Bearer <Fly API token>`.'
externalDocs:
url: https://fly.io/docs/machines/working-with-machines/
x-original-swagger-version: '2.0'
x-provenance:
method: harvested
publisher: Fly Io
source: https://fly.io/openapi.json
note: split by refine-openapis from the provider's own published document, verified by fetch (openapi/_original/*.fetch.json);
stamped by stamp-openapi-provenance.py (roadmap#793)