Fly.io

App · 20 actions

Manage Fly apps, machine lifecycle, volumes and machine diagnostics.

Actions

ActionWhat it does
Create appCreate an app with the specified details in the request body.
Destroy appDelete an app by its name.
Get appRetrieve details about a specific app by its name.
Get certificate detailsGet certificate details
Get leaseRetrieve the current lease of a specific Machine within an app.
Get machineGet details of a specific Machine within an app by the Machine ID.
Get metadataRetrieve metadata for a specific Machine within an app.
Get volumeRetrieve details about a specific volume by its ID within an app.
List appsList all apps with the ability to filter by organization slug.
List certificates for appList certificates for app
List eventsList all events associated with a specific Machine within an app.
List machinesList all Machines associated with a specific app, with optional filters for including deleted Machines and filtering by region.
List processesList all processes running on a specific Machine within an app, with optional sorting parameters.
List snapshotsList all snapshots for a specific volume within an app.
List versionsList all versions of the configuration for a specific Machine within an app.
List volumesList all volumes associated with a specific app.
Restart machineRestart a specific Machine within an app, with an optional timeout parameter.
Start machineStart a specific Machine within an app.
Stop machineStop a specific Machine within an app, with an optional request body to specify signal and timeout.
Suspend machineSuspend a specific Machine within an app.

Create app

Create an app with the specified details in the request body.

Inputs

Enable subdomainsenable_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 keyidempotency_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.
NamenametextRequired
Globally unique name for the app. Required.
Networknetworktext
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 slugorg_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 nameapp_nametextRequired
Fly App Name

Outputs

dataobject
Returned value.
Example output
{
  "data": {}
}

Get app

Retrieve details about a specific app by its name.

Inputs

App nameapp_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 nameapp_nametextRequired
Fly App Name
HostnamehostnametextRequired
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 nameapp_nametextRequired
Fly App Name
Machine IDmachine_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 nameapp_nametextRequired
Fly App Name
Machine IDmachine_idtextRequired
Machine ID
Versionversiontext
26-character Machine version ID; returns that version of the Machine instead of the current one
Include leasesinclude_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 nameapp_nametextRequired
Fly App Name
Machine IDmachine_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 nameapp_nametextRequired
Fly App Name
Volume IDvolume_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 slugorg_slugtextRequired
The org slug, or 'personal', to filter apps
App roleapp_roletext
Filter apps by role
Limitlimitnumber
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.
Cursorcursortext
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 nameapp_nametextRequired
Fly App Name
Filterfiltertext
Hostname filter (substring match)
Cursorcursortext
Pagination cursor from previous response
Limitlimitnumber
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 nameapp_nametextRequired
Fly App Name
Machine IDmachine_idtextRequired
Machine ID
Limitlimitnumber
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 nameapp_nametextRequired
Fly App Name
Include deletedinclude_deletedtrue/false
Include deleted machines
Include leasesinclude_leasestrue/false
Include machine leases
Regionregiontext
Region filter
Statestatetext
comma separated list of states to filter (created, started, stopped, suspended)
Summarysummarytrue/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 nameapp_nametextRequired
Fly App Name
Machine IDmachine_idtextRequired
Machine ID
Sort bysort_bytext
Sort by
Orderordertext
Order

Outputs

datalist
Returned value.
Example output
{
  "data": []
}

List snapshots

List all snapshots for a specific volume within an app.

Inputs

App nameapp_nametextRequired
Fly App Name
Volume IDvolume_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 nameapp_nametextRequired
Fly App Name
Machine IDmachine_idtextRequired
Machine ID

Outputs

datalist
Returned value.
Example output
{
  "data": []
}

List volumes

List all volumes associated with a specific app.

Inputs

App nameapp_nametextRequired
Fly App Name
Summarysummarytrue/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 nameapp_nametextRequired
Fly App Name
Machine IDmachine_idtextRequired
Machine ID
Timeouttimeouttext
Restart timeout as a Go duration string or number of seconds
Signalsignaltext
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 nameapp_nametextRequired
Fly App Name
Machine IDmachine_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 nameapp_nametextRequired
Fly App Name
Machine IDmachine_idtextRequired
Machine ID
Signalsignaltext
Returned value.One of: SIGHUP, SIGINT, SIGQUIT, SIGKILL, SIGUSR1, SIGUSR2, SIGTERM.
Timeouttimeouttext
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 nameapp_nametextRequired
Fly App Name
Machine IDmachine_idtextRequired
Machine ID

Outputs

dataobject
Returned value.
Example output
{
  "data": {
    "ok": false
  }
}

On this page