Fly.io
App · 20 actions
Manage Fly apps, machine lifecycle, volumes and machine diagnostics.
Actions
| Action | What it does |
|---|---|
| Create app | Create an app with the specified details in the request body. |
| Destroy app | Delete an app by its name. |
| Get app | Retrieve details about a specific app by its name. |
| Get certificate details | Get certificate details |
| Get lease | Retrieve the current lease of a specific Machine within an app. |
| Get machine | Get details of a specific Machine within an app by the Machine ID. |
| Get metadata | Retrieve metadata for a specific Machine within an app. |
| Get volume | Retrieve details about a specific volume by its ID within an app. |
| List apps | List all apps with the ability to filter by organization slug. |
| List certificates for app | List certificates for app |
| List events | List all events associated with a specific Machine within an app. |
| List machines | List all Machines associated with a specific app, with optional filters for including deleted Machines and filtering by region. |
| List processes | List all processes running on a specific Machine within an app, with optional sorting parameters. |
| List snapshots | List all snapshots for a specific volume within an app. |
| List versions | List all versions of the configuration for a specific Machine within an app. |
| List volumes | List all volumes associated with a specific app. |
| Restart machine | Restart a specific Machine within an app, with an optional timeout parameter. |
| Start machine | Start a specific Machine within an app. |
| Stop machine | Stop a specific Machine within an app, with an optional request body to specify signal and timeout. |
| Suspend machine | Suspend a specific Machine within an app. |
Create app
Create an app with the specified details in the request body.
Inputs
- Enable subdomains
enable_subdomainstrue/false - Request a wildcard TLS certificate for *.svc. .fly.dev. Defaults to false. Certificate provisioning is asynchronous; this does not create services or configure their routing.
- Idempotency key
idempotency_keytext - When set, makes a retry of this exact request safe: a second create with the same key and the same name (or no name) returns the app the first request created, instead of erroring on a false name conflict or creating a duplicate. A second create with the same key but a *different* name is rejected outright; it won't silently hand back the first app.
- Name
nametextRequired - Globally unique name for the app. Required.
- Network
networktext - Name of the organization's private network to attach the app to. Creates the network if it does not exist. Omit, use an empty string, or use "default" to select the organization's default network.
- Org slug
org_slugtextRequired - Slug of the organization that will own the app, or "personal" for your personal organization. Required.
Outputs
dataobject- Returned value.
Example output
{
"data": {
"created_at": 1,
"id": "example"
}
}Destroy app
Delete an app by its name.
Inputs
- App name
app_nametextRequired - Fly App Name
Outputs
dataobject- Returned value.
Example output
{
"data": {}
}Get app
Retrieve details about a specific app by its name.
Inputs
- App name
app_nametextRequired - Fly App Name
Outputs
dataobject- Returned value.
Example output
{
"data": {
"id": "example",
"internal_numeric_id": 1,
"machine_count": 1,
"name": "example",
"network": "example",
"network_cidr": "example",
"organization": {
"internal_numeric_id": 1,
"name": "example",
"slug": "example"
},
"status": "example",
"volume_count": 1
}
}Get certificate details
Get certificate details
Inputs
- App name
app_nametextRequired - Fly App Name
- Hostname
hostnametextRequired - Certificate Hostname
Outputs
dataobject- Returned value.
Example output
{
"data": {
"acme_requested": false,
"certificates": [],
"configured": false,
"dns_provider": "example",
"dns_requirements": {
"a": [],
"aaaa": [],
"acme_challenge": {
"name": "example",
"target": "example"
},
"cname": "example",
"ownership": {
"app_value": "example",
"name": "example",
"org_value": "example"
}
},
"hostname": "example",
"rate_limited_until": "example",
"status": "example",
"validation": {
"alpn_configured": false,
"dns_configured": false,
"http_configured": false,
"ownership_txt_configured": false
},
"validation_errors": []
}
}Get lease
Retrieve the current lease of a specific Machine within an app. Machine leases can be used to obtain an exclusive lock on modifying a Machine.
Inputs
- App name
app_nametextRequired - Fly App Name
- Machine ID
machine_idtextRequired - Machine ID
Outputs
dataobject- Returned value.
Example output
{
"data": {
"description": "example",
"expires_at": 1,
"nonce": "example",
"owner": "example",
"version": "example"
}
}Get machine
Get details of a specific Machine within an app by the Machine ID.
Inputs
- App name
app_nametextRequired - Fly App Name
- Machine ID
machine_idtextRequired - Machine ID
- Version
versiontext - 26-character Machine version ID; returns that version of the Machine instead of the current one
- Include leases
include_leasestrue/false - Include machine lease
Outputs
dataobject- Returned value.
Example output
{
"data": {
"checks": [],
"config": {
"auto_destroy": false,
"cache_drive": {
"size_mb": 1
},
"checks": {},
"containers": [],
"disable_machine_autostart": false,
"dns": {
"dns_forward_rules": [],
"hostname": "example",
"hostname_fqdn": "example",
"nameservers": [],
"options": [],
"searches": [],
"skip_registration": false
},
"env": {},
"files": [],
"guest": {
"cpu_kind": "example",
"cpus": 1,
"gpu_kind": "example",
"gpus": 1,
"host_dedication_id": "example",
"kernel_args": [],
"max_memory_mb": 1,
"memory_mb": 1,
"persist_rootfs": "never",
"required_host_features": []
},
"image": "example",
"init": {
"cmd": [],
"entrypoint": [],
"exec": [],
"kernel_args": [],
"swap_size_mb": 1,
"tty": false
},
"metadata": {},
"metrics": {
"https": false,
"path": "example",
"port": 1
},
"mounts": [],
"processes": [],
"restart": {
"max_retries": 1,
"policy": "no"
},
"rootfs": {
"persist": "never",
"size_gb": 1
},
"schedule": "example",
"services": [],
"size": "example",
"spot": {
"max_price_fraction": 1
},
"standbys": [],
"statics": [],
"stop_config": {
"signal": "SIGHUP",
"timeout": "example"
}
},
"cordoned": false,
"created_at": "example",
"events": [],
"host_features": [],
"host_status": "ok",
"id": "example",
"image_ref": {
"digest": "example",
"labels": {},
"registry": "example",
"repository": "example",
"tag": "example"
},
"incomplete_config": {
"auto_destroy": false,
"cache_drive": {
"size_mb": 1
},
"checks": {},
"containers": [],
"disable_machine_autostart": false,
"dns": {
"dns_forward_rules": [],
"hostname": "example",
"hostname_fqdn": "example",
"nameservers": [],
"options": [],
"searches": [],
"skip_registration": false
},
"env": {},
"files": [],
"guest": {
"cpu_kind": "example",
"cpus": 1,
"gpu_kind": "example",
"gpus": 1,
"host_dedication_id": "example",
"kernel_args": [],
"max_memory_mb": 1,
"memory_mb": 1,
"persist_rootfs": "never",
"required_host_features": []
},
"image": "example",
"init": {
"cmd": [],
"entrypoint": [],
"exec": [],
"kernel_args": [],
"swap_size_mb": 1,
"tty": false
},
"metadata": {},
"metrics": {
"https": false,
"path": "example",
"port": 1
},
"mounts": [],
"processes": [],
"restart": {
"max_retries": 1,
"policy": "no"
},
"rootfs": {
"persist": "never",
"size_gb": 1
},
"schedule": "example",
"services": [],
"size": "example",
"spot": {
"max_price_fraction": 1
},
"standbys": [],
"statics": [],
"stop_config": {
"signal": "SIGHUP",
"timeout": "example"
}
},
"instance_id": "example",
"lease": {
"description": "example",
"expires_at": 1,
"owner": "example"
},
"name": "example",
"nonce": "example",
"private_ip": "example",
"region": "example",
"state": "example",
"updated_at": "example",
"version": "example"
}
}Get metadata
Retrieve metadata for a specific Machine within an app.
Inputs
- App name
app_nametextRequired - Fly App Name
- Machine ID
machine_idtextRequired - Machine ID
Outputs
dataobject- Returned value.
Example output
{
"data": {}
}Get volume
Retrieve details about a specific volume by its ID within an app.
Inputs
- App name
app_nametextRequired - Fly App Name
- Volume ID
volume_idtextRequired - Volume ID
Outputs
dataobject- Returned value.
Example output
{
"data": {
"attached_alloc_id": "example",
"attached_machine_id": "example",
"auto_backup_enabled": false,
"block_size": 1,
"blocks": 1,
"blocks_avail": 1,
"blocks_free": 1,
"bytes_total": 1,
"bytes_used": 1,
"created_at": "example",
"encrypted": false,
"fstype": "example",
"host_features": [],
"host_status": "ok",
"id": "example",
"name": "example",
"region": "example",
"required_host_features": [],
"size_gb": 1,
"snapshot_retention": 1,
"state": "example",
"type": "local",
"zone": "example"
}
}List apps
List all apps with the ability to filter by organization slug.
Inputs
- Org slug
org_slugtextRequired - The org slug, or 'personal', to filter apps
- App role
app_roletext - Filter apps by role
- Limit
limitnumber - The number of apps to fetch (must be between 1 and 5000). Providing a limit enables pagination. Without it, all apps are returned in one response.
- Cursor
cursortext - Value of next_cursor from the previous page. Requires limit. Later pages only include apps that existed when the first page was requested. Apps created in the seconds before the first page was requested may be missing. Cursors expire 30 minutes after the first page was requested.
Outputs
dataobject- Returned value.
Example output
{
"data": {
"apps": [],
"next_cursor": "example",
"total_apps": 1
}
}List certificates for app
List certificates for app
Inputs
- App name
app_nametextRequired - Fly App Name
- Filter
filtertext - Hostname filter (substring match)
- Cursor
cursortext - Pagination cursor from previous response
- Limit
limitnumber - Number of results per page (default 25, max 500)
Outputs
dataobject- Returned value.
Example output
{
"data": {
"certificates": [],
"next_cursor": "example",
"total_count": 1
}
}List events
List all events associated with a specific Machine within an app.
Inputs
- App name
app_nametextRequired - Fly App Name
- Machine ID
machine_idtextRequired - Machine ID
- Limit
limitnumber - The number of events to fetch (max of 50). If omitted, this is set to 20 by default.
Outputs
datalist- Returned value.
Example output
{
"data": []
}List machines
List all Machines associated with a specific app, with optional filters for including deleted Machines and filtering by region.
Inputs
- App name
app_nametextRequired - Fly App Name
- Include deleted
include_deletedtrue/false - Include deleted machines
- Include leases
include_leasestrue/false - Include machine leases
- Region
regiontext - Region filter
- State
statetext - comma separated list of states to filter (created, started, stopped, suspended)
- Summary
summarytrue/false - Only return summary info about machines (omit config, checks, events, host_status, nonce, etc.)
Outputs
datalist- Returned value.
Example output
{
"data": []
}List processes
List all processes running on a specific Machine within an app, with optional sorting parameters.
Inputs
- App name
app_nametextRequired - Fly App Name
- Machine ID
machine_idtextRequired - Machine ID
- Sort by
sort_bytext - Sort by
- Order
ordertext - Order
Outputs
datalist- Returned value.
Example output
{
"data": []
}List snapshots
List all snapshots for a specific volume within an app.
Inputs
- App name
app_nametextRequired - Fly App Name
- Volume ID
volume_idtextRequired - Volume ID
Outputs
datalist- Returned value.
Example output
{
"data": []
}List versions
List all versions of the configuration for a specific Machine within an app.
Inputs
- App name
app_nametextRequired - Fly App Name
- Machine ID
machine_idtextRequired - Machine ID
Outputs
datalist- Returned value.
Example output
{
"data": []
}List volumes
List all volumes associated with a specific app.
Inputs
- App name
app_nametextRequired - Fly App Name
- Summary
summarytrue/false - Only return summary info about volumes (omit blocks, block size, etc)
Outputs
datalist- Returned value.
Example output
{
"data": []
}Restart machine
Restart a specific Machine within an app, with an optional timeout parameter.
Inputs
- App name
app_nametextRequired - Fly App Name
- Machine ID
machine_idtextRequired - Machine ID
- Timeout
timeouttext - Restart timeout as a Go duration string or number of seconds
- Signal
signaltext - Unix signal nameOne of:
SIGHUP,SIGINT,SIGQUIT,SIGKILL,SIGUSR1,SIGUSR2,SIGTERM.
Outputs
dataobject- Returned value.
Example output
{
"data": {
"ok": false
}
}Start machine
Start a specific Machine within an app.
Inputs
- App name
app_nametextRequired - Fly App Name
- Machine ID
machine_idtextRequired - Machine ID
Outputs
dataobject- Returned value.
Example output
{
"data": {
"migrated": false,
"new_host": "example",
"previous_state": "example"
}
}Stop machine
Stop a specific Machine within an app, with an optional request body to specify signal and timeout.
Inputs
- App name
app_nametextRequired - Fly App Name
- Machine ID
machine_idtextRequired - Machine ID
- Signal
signaltext - Returned value.One of:
SIGHUP,SIGINT,SIGQUIT,SIGKILL,SIGUSR1,SIGUSR2,SIGTERM. - Timeout
timeouttext - Returned value.
Outputs
dataobject- Returned value.
Example output
{
"data": {
"ok": false
}
}Suspend machine
Suspend a specific Machine within an app. The next start operation will attempt (but is not guaranteed) to resume the Machine from a snapshot taken at suspension time, rather than performing a cold boot.
Inputs
- App name
app_nametextRequired - Fly App Name
- Machine ID
machine_idtextRequired - Machine ID
Outputs
dataobject- Returned value.
Example output
{
"data": {
"ok": false
}
}