Skip to content

Latest commit

 

History

History
1776 lines (1375 loc) · 105 KB

models.mdx

File metadata and controls

1776 lines (1375 loc) · 105 KB
title Models
icon boxes
description Schema reference for every object in the Fly Machines API.

{/* This file is generated by scripts/generate-machines-models.py in superfly/nomad-firecracker from api/machines/openapi.json. Don't edit it here: changes are overwritten when the Machines API spec changes. */}

These are the data models used across the Machines API requests and responses, generated from the OpenAPI specification.

AcmeChallenge

Property Type Required Description
name string No Name of the CNAME record to create, such as _acme-challenge.example.com.
target string No Value the CNAME record must point to.

App

Property Type Required Description
id string No Unique ID of the app, as used by Fly.io's GraphQL API.
internal_numeric_id integer No Fly.io's internal numeric ID of the app.
machine_count integer No Number of the app's Machines that have not been destroyed.
name string No Globally unique name of the app.
network string No Name of the private network the app is attached to: default for the organization's default network, or the name given when the app was created.
network_cidr string No The /48 IPv6 prefix of the private (6PN) network the app is attached to, such as fdaa:0:1234::/48. Apps on the same network share it.
organization AppOrganizationInfo No The organization that owns the app.
status string No State of the app. pending until one of its Machines changes state. After that, updated asynchronously whenever a Machine changes state: deployed if at least one Machine is started, and suspended otherwise. Enum: pending, deployed, suspended
volume_count integer No Number of the app's volumes that have not been destroyed or scheduled for destruction.

AppOrganizationInfo

Property Type Required Description
internal_numeric_id integer No Fly.io's internal numeric ID of the organization.
name string No Display name of the organization.
slug string No Slug of the organization, used to refer to it in API requests such as org_slug.

AppSecret

Property Type Required Description
created_at string No When the secret was first set. Only returned when reading secrets.
digest string No Short fingerprint of the value, to tell whether it changed without revealing it. Omitted for deleted secrets.
name string No Name of the secret.
updated_at string No When the secret's value last changed. Only returned when reading secrets.
value string No Value of the secret. Only returned with show_secrets=true, and when setting secrets.

AppSecrets

Property Type Required Description
secrets AppSecret[] No The app's secrets.

AppSecretsUpdateRequest

Property Type Required Description
values map<string, string> No Secrets to change, keyed by name. A string value sets the secret; null deletes it. Names may only contain letters, digits, and underscores. Secrets not listed are left alone.

AppSecretsUpdateResp

Property Type Required Description
Version integer No Same value as version. Deprecated: use version.
secrets AppSecret[] No The secrets from the request, with their new values and digests; deleted secrets only have a name.
version integer No The app's secrets version after this change. Pass it as min_secrets_version when creating or updating Machines so that they are guaranteed to see the change.

assignIPRequest

Property Type Required Description
network string No Only for private_v6: name of the private network to allocate the Flycast address in. Defaults to the organization's default network.
org_slug string No Only for private_v6: slug of the organization whose private network the Flycast address is allocated in, to make the app reachable from that organization. Defaults to the app's organization.
region string No Region to scope the address to. Required for egress types. Optional for v4 and v6, which default to global (announced in all regions). Must be empty or global for shared_v4 and private_v6.
service_name string No Scope the address to a single service of the app. Not supported for egress types.
type IPAssignmentType No Type of IP address to allocate. Required.

AssignIPResponse

Property Type Required Description
created_at string No When the address was assigned to the app, in RFC 3339 format.
egress boolean No Whether this is an egress address.
ip string No The allocated IP address. Null for egress_pair; see ip_pair.
ip_pair IPPair No The allocated IPv4 and IPv6 addresses when the egress_pair type was requested; null otherwise.
network IPAssignmentNetwork No
region string No Region the address is scoped to, or global for addresses announced in all regions.
service_name string No Name of the service the address is scoped to, if any.
shared boolean No Whether this is the app's shared IPv4 address.

authenticateTokenRequest

Property Type Required Description
header string No Value of the Authorization header to verify, e.g. FlyV1 fm2_....

authorizeResponse

Property Type Required Description
access flyio.Access No The requested access, with names resolved to IDs.
verified_token root.VerifiedToken No The token that grants the requested access.

authorizeTokenRequest

Property Type Required Description
access main.TokenAccess No Access to check the token against.
header string No Value of the Authorization header to verify, e.g. FlyV1 fm2_....

CertificateCheckResponse

Property Type Required Description
acme_requested boolean No Whether Fly.io-issued (ACME) certificates were requested for the hostname.
certificates CertificateEntry[] No The hostname's certificates: at most one custom entry and one Fly.io entry.
configured boolean No Whether ownership of the hostname has been verified.
dns_provider string No DNS provider detected for the hostname, if known.
dns_records DNSRecords No
dns_requirements DNSRequirements No DNS records to create to point the hostname at the app and validate it.
hostname string No The hostname the certificate is for. May start with *. for a wildcard certificate.
rate_limited_until string No If Let's Encrypt is rate-limiting certificate requests for the hostname, when that ends.
status string No Human-readable status: Ready, Awaiting certificates, Awaiting configuration, or a hint about what is misconfigured.
validation CertificateValidation No Which validation methods are currently possible.
validation_errors CertificateValidationError[] No Problems found by the most recent validation.

CertificateDetail

Property Type Required Description
acme_requested boolean No Whether Fly.io-issued (ACME) certificates were requested for the hostname.
certificates CertificateEntry[] No The hostname's certificates: at most one custom entry and one Fly.io entry.
configured boolean No Whether ownership of the hostname has been verified.
dns_provider string No DNS provider detected for the hostname, if known.
dns_requirements DNSRequirements No DNS records to create to point the hostname at the app and validate it.
hostname string No The hostname the certificate is for. May start with *. for a wildcard certificate.
rate_limited_until string No If Let's Encrypt is rate-limiting certificate requests for the hostname, when that ends.
status string No Human-readable status: Ready, Awaiting certificates, Awaiting configuration, or a hint about what is misconfigured.
validation CertificateValidation No Which validation methods are currently possible.
validation_errors CertificateValidationError[] No Problems found by the most recent validation.

CertificateEntry

Property Type Required Description
created_at string No When the certificate was added; for Fly.io-issued certificates, the earliest one.
expires_at string No When the certificate expires; for Fly.io-issued certificates, the latest one.
issued IssuedCertificate[] No The individual Fly.io-issued certificates, newest first. Empty for custom certificates.
issuer string No Issuer of a custom certificate. Omitted for Fly.io-issued certificates.
source string No custom for an uploaded certificate, fly for certificates issued by Fly.io. Enum: custom, fly
status string No active once ownership of the hostname is verified. Until then, pending_ownership for custom certificates and pending_validation for Fly.io-issued certificates. Enum: active, pending_ownership, pending_validation

CertificateSummary

Property Type Required Description
acme_alpn_configured boolean No Whether the hostname points at the app, allowing TLS-ALPN-01 validation.
acme_dns_configured boolean No Whether the _acme-challenge CNAME record is set up, allowing DNS-01 validation.
acme_http_configured boolean No Whether the hostname points at the app, allowing HTTP-01 validation.
acme_requested boolean No Whether Fly.io-issued (ACME) certificates were requested for the hostname.
configured boolean No Whether ownership of the hostname has been verified by any of the methods above.
created_at string No When the hostname was added to the app.
dns_provider string No DNS provider detected for the hostname, if known.
has_custom_certificate boolean No Whether a custom certificate was uploaded for the hostname.
has_fly_certificate boolean No Whether Fly.io has issued certificates for the hostname.
hostname string No The hostname the certificate is for. May start with *. for a wildcard certificate.
ownership_txt_configured boolean No Whether the _fly-ownership TXT record is set up.
status string No Human-readable status: Ready, Awaiting certificates, Awaiting configuration, or a hint about what is misconfigured.
updated_at string No When the hostname's certificate configuration last changed.

CertificateValidation

Property Type Required Description
alpn_configured boolean No Whether the hostname points at the app, allowing TLS-ALPN-01 validation.
dns_configured boolean No Whether the _acme-challenge CNAME record is set up, allowing DNS-01 validation.
http_configured boolean No Whether the hostname points at the app, allowing HTTP-01 validation.
ownership_txt_configured boolean No Whether the _fly-ownership TXT record is set up.

CertificateValidationError

Property Type Required Description
code string No Machine-readable error code.
message string No Human-readable description of the problem.
remediation string No How to fix the problem, if known.
timestamp string No When the problem was detected.

CheckStatus

Property Type Required Description
name string No Name of the check: the key of a top-level check in config.checks, or servicecheck-<index>-<type>-<internal_port> for a check defined in a service.
output string No Output of the most recent check run, such as an error message.
status string No Result of the check: passing, warning, or critical. Enum: passing, warning, critical
updated_at string No When the check's status was last updated.

createAcmeCertificateRequest

Property Type Required Description
hostname string No Hostname to request certificates for, such as example.com or *.example.com. Required. Hostnames under fly.dev are not allowed.

CreateAppDeployTokenRequest

Property Type Required Description
expiry string No How long the token is valid, as a Go duration string such as 720h. If omitted, the token is valid for as long as the token used to make this request.

CreateAppDeployTokenResponse

Property Type Required Description
token string No The deploy token, including its FlyV1 scheme prefix, ready to be used as an Authorization header value. It is derived from the token used to make this request and limited to the app, plus the organization's WireGuard and remote builder features.

CreateAppRequest

Property Type Required Description
enable_subdomains boolean No 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 string No 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 string No Globally unique name for the app. Required.
network string No 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 string No Slug of the organization that will own the app, or "personal" for your personal organization. Required.

CreateAppResponse

Property Type Required Description
created_at integer No When the app was created, in Unix milliseconds.
id string No Name of the new app. Despite the field's name, this is not the app's id as returned by Get App.

createCustomCertificateRequest

Property Type Required Description
fullchain string No PEM-encoded certificate, followed by any intermediate certificates. Required.
hostname string No Hostname the certificate is for. Required. Hostnames under fly.dev are not allowed.
private_key string No PEM-encoded private key of the certificate. Required.

CreateLeaseRequest

Property Type Required Description
description string No Description or reason for the lease, shown to others who look at it.
ttl integer No How long the lease is valid, in seconds. Defaults to 60.

CreateMachineRequest

Property Type Required Description
config fly.MachineConfig No An object defining the Machine configuration
lease_ttl integer No Acquire a lease on the new Machine that lasts this many seconds. The response's nonce field holds the lease nonce.
min_secrets_version integer No The minimum version of the app's secrets the Machine must run with. Set it to the version returned by the endpoints that set or delete app secrets, so that the Machine is guaranteed to see those changes. This field belongs at the top level of the request body, not in config. If omitted, the app's current secrets version is looked up for you.
name string No Name for this Machine. If omitted, one is generated for you. Names are not required to be unique.
region string No The region to create the Machine in, such as iad. Also accepts a comma-separated list of regions and region groups (any, us, na, sa, eu, apac, africa, asia_pacific, europe, north_america, south_america), in which case Fly.io picks one with capacity. If the Machine mounts a volume, defaults to the volume's region; the region must include it. Otherwise defaults to the region of the API server handling the request, which is usually the one closest to you.
skip_launch boolean No Create the Machine without starting it. It ends up stopped; start it with the Start Machine endpoint. Not allowed for spot Machines.
skip_secrets boolean No Don't look up the app's current secrets version. The Machine still gets the app's secrets, but may not see recent changes to them. Takes precedence over min_secrets_version.
skip_service_registration boolean No Create the Machine cordoned, so Fly Proxy doesn't route requests to it until it is uncordoned. Its services are still registered.

CreateOIDCTokenRequest

Optional parameters

Property Type Required Description
aud string No Value of the token's aud claim. Defaults to https://fly.io/<org-slug>.
aws_principal_tags boolean No Add AWS principal tag claims (https://aws.amazon.com/tags/principal_tags/<tag>) for use with AWS IAM: FlyAppName, FlyOrgSlug, FlyOrgId, FlyMachineName and FlyRegion.

createPostgresAttachmentRequest

Property Type Required Description
app_name string Yes Name of the Fly app to attach.

createPostgresAttachmentResponse

Property Type Required Description
data PostgresAttachment No

createPostgresBackupRequest

Property Type Required Description
type string Yes Backup type. Enum: full, incr, diff

createPostgresClusterRequest

Property Type Required Description
disk_size_gb integer No Disk size in gigabytes.
name string No Name for the cluster. A name is generated when omitted.
org_slug string Yes Slug of the organization that will own the cluster, or "personal" for the caller's personal organization.
pg_major_version string No Postgres major version. Enum: 16, 17
plan string Yes Plan slug selecting CPU, memory, and disk sizing. Matched case-insensitively. Enum: basic, starter, launch, scale, Performance
pool_mode string No Connection pooler mode. Enum: session, transaction
postgis_enabled boolean No Enable PostGIS support, required to later enable PostGIS extensions.
region string Yes Fly region code where the cluster's primary runs.

createPostgresDatabaseRequest

Property Type Required Description
name string Yes Name of the database to create. Must start and end with an alphanumeric character and may contain hyphens and underscores, up to 63 characters.

createPostgresUserRequest

Property Type Required Description
role string Yes Role to grant the user. Enum: schema_admin, writer, reader
username string Yes Name for the new user. Must start and end with a lowercase alphanumeric character and may contain hyphens and underscores, up to 63 characters.

createPostgresUserResponse

Property Type Required Description
data PostgresUser No

CreateVolumeRequest

Property Type Required Description
auto_backup_enabled boolean No Take daily automatic snapshots of the volume. Defaults to true.
compute fly.MachineGuest No 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 No Ignored.
encrypted boolean No Encrypt the volume at rest. Defaults to true. When forking, the source volume's setting is used.
fstype string No Filesystem to format the volume with: ext4, or raw for an unformatted block device. Enum: ext4, raw
name string No Name of the volume: at most 30 lowercase letters, digits, and underscores. Required.
region string No 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 No 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 No 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 No ID of a snapshot to restore into the new volume. Mutually exclusive with source_volume_id.
snapshot_retention integer No Number of days to keep snapshots of the volume, from 1 to 60. Defaults to 5.
source_volume_id string No 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 No With require_unique_zone, avoid hosts with any volume of the app in the region, not just volumes with the same name.

CurrentTokenResponse

Property Type Required Description
tokens main.tokenInfo[] No One entry per token in the Authorization header that could be verified, in no particular order; use token_id to tell them apart. Tokens that fail verification or are not scoped to an organization are left out.

DecryptSecretkeyRequest

Property Type Required Description
associated_data string No Additional data passed when encrypting, base64-encoded.
ciphertext string No Data to decrypt, as returned by the encrypt endpoint, base64-encoded.

DecryptSecretkeyResponse

Property Type Required Description
plaintext string No Decrypted data, base64-encoded.

DeleteAppSecretResponse

Property Type Required Description
Version integer No Same value as version. Deprecated: use version.
version integer No The app's secrets version after this change. Pass it as min_secrets_version when creating or updating Machines so that they are guaranteed to see the change.

DeleteSecretkeyResponse

Property Type Required Description
Version integer No Same value as version. Deprecated: use version.
version integer No The app's secrets version after this change.

destroyCustomCertificateResponse

Property Type Required Description
acme_requested boolean No Whether Fly.io-issued (ACME) certificates were requested for the hostname.
certificates CertificateEntry[] No The hostname's certificates: at most one custom entry and one Fly.io entry.
configured boolean No Whether ownership of the hostname has been verified.
dns_provider string No DNS provider detected for the hostname, if known.
dns_requirements DNSRequirements No DNS records to create to point the hostname at the app and validate it.
hostname string No The hostname the certificate is for. May start with *. for a wildcard certificate.
rate_limited_until string No If Let's Encrypt is rate-limiting certificate requests for the hostname, when that ends.
status string No Human-readable status: Ready, Awaiting certificates, Awaiting configuration, or a hint about what is misconfigured.
validation CertificateValidation No Which validation methods are currently possible.
validation_errors CertificateValidationError[] No Problems found by the most recent validation.
warning string No Set when no ACME certificates are configured for the hostname either, so it no longer has any certificate.

DNSRecords

Property Type Required Description
a string[] No A records found for the hostname.
aaaa string[] No AAAA records found for the hostname.
acme_challenge_cname string No Target of the _acme-challenge CNAME record, if found.
cname string[] No CNAME records found for the hostname.
ownership_txt string No Value of the _fly-ownership TXT record, if found.
resolved_addresses string[] No All addresses the hostname resolved to, after following CNAMEs.
soa string No Primary name server from the SOA record of the hostname's zone.

DNSRequirements

Property Type Required Description
a string[] No IPv4 addresses the hostname's A records can point to: the app's global IPv4 addresses and its shared IPv4 address.
aaaa string[] No IPv6 addresses the hostname's AAAA records can point to: the app's global IPv6 addresses.
acme_challenge AcmeChallenge No Record for DNS-01 validation.
cname string No Target the hostname can CNAME to instead of using A and AAAA records.
ownership OwnershipVerification No Record for proving ownership of the hostname.

enablePostgresExtensionRequest

Property Type Required Description
create_schema boolean No Create the schema first if it does not exist.
name string Yes Extension to enable.
schema string No Schema to install the extension into. Defaults to the database's default schema.

EncryptSecretkeyRequest

Property Type Required Description
associated_data string No Additional data to authenticate but not encrypt, base64-encoded. The same data must be passed when decrypting.
plaintext string No Data to encrypt, base64-encoded.

EncryptSecretkeyResponse

Property Type Required Description
ciphertext string No Encrypted data, base64-encoded.

ErrorResponse

Property Type Required Description
details object No Deprecated: details about some errors. Do not rely on its contents.
error string No Human-readable description of the error. Its wording may change; use status to tell errors apart.
status main.statusCode No Machine-readable error code, set for some errors, such as insufficient_capacity, volume_placement_capacity, name_taken, exec_request_too_large, or exec_output_too_large.

ExecResponse

Property Type Required Description
exit_code integer No The command's exit code.
exit_signal integer No The signal that terminated the command, or 0 if it exited normally.
stderr string No The command's standard error.
stdout string No The command's standard output.

ExtendVolumeRequest

Property Type Required Description
size_gb integer No New size of the volume in GiB. Must be larger than the current size and at most the organization's maximum (500 by default).

ExtendVolumeResponse

Property Type Required Description
needs_restart boolean No Whether the volume is attached to a running Machine that could not resize its filesystem while running. If true, restart the Machine for the filesystem to use the new size.
volume Volume No The extended volume.

fly.ContainerConfig

Property Type Required Description
cmd string[] No CmdOverride is used to override the default command of the image.
depends_on fly.ContainerDependency[] No DependsOn can be used to define dependencies between containers. The container will only be started after all of its dependent conditions have been satisfied.
entrypoint string[] No EntrypointOverride is used to override the default entrypoint of the image.
env map<string, string> No ExtraEnv is used to add additional environment variables to the container.
env_from fly.EnvFrom[] No EnvFrom can be provided to set environment variables from machine fields.
exec string[] No Image Config overrides - these fields are used to override the image configuration. If not provided, the image configuration will be used. ExecOverride is used to override the default command of the image.
files fly.File[] No Files are files that will be written to the container file system.
healthchecks fly.ContainerHealthcheck[] No Healthchecks determine the health of your containers. Healthchecks can use HTTP, TCP or an Exec command.
image string No Image is the docker image to run.
name string No Name is used to identify the container in the machine.
restart fly.MachineRestart No Restart is used to define the restart policy for the container.
secrets fly.MachineSecret[] No Secrets can be provided at the process level to explicitly indicate which secrets should be used for the process. If not provided, the secrets provided at the machine level will be used.
stop fly.StopConfig No Stop is used to define the signal and timeout for stopping the container.
user string No UserOverride is used to override the default user of the image.

fly.ContainerDependency

Property Type Required Description
condition fly.ContainerDependencyCondition No When the container can start: once the dependency has started, is healthy, or has exited_successfully
name string No Name of the container this one depends on

fly.ContainerDependencyCondition

Type: string

Enum: exited_successfully, healthy, started

fly.ContainerHealthcheck

Property Type Required Description
exec fly.ExecHealthcheck No Check that a command run in the container exits with status 0
failure_threshold integer No The number of times the check must fail before considering the container unhealthy.
grace_period integer No The time in seconds to wait after a container starts before checking its health.
http fly.HTTPHealthcheck No Check that an HTTP request succeeds
interval integer No The time in seconds between executing the defined check.
kind fly.ContainerHealthcheckKind No Kind of healthcheck (readiness, liveness)
name string No The name of the check. Must be unique within the container.
success_threshold integer No The number of times the check must succeeed before considering the container healthy.
tcp fly.TCPHealthcheck No Check that a TCP connection can be opened
timeout integer No The time in seconds to wait for the check to complete.
unhealthy fly.UnhealthyPolicy No Unhealthy policy that determines what action to take if a container is deemed unhealthy

fly.ContainerHealthcheckKind

Type: string

Enum: readiness, liveness

fly.ContainerHealthcheckScheme

Type: string

Enum: http, https

fly.DNSConfig

Property Type Required Description
dns_forward_rules fly.dnsForwardRule[] No Forward DNS queries for some domains to other DNS servers
hostname string No Hostname of the Machine. Defaults to the Machine ID. Also added to /etc/hosts with the Machine's 6PN address
hostname_fqdn string No Fully qualified domain name added to /etc/hosts for hostname
nameservers string[] No Nameservers to use instead of the default, Fly.io's private DNS server fdaa::3
options fly.dnsOption[] No Options for /etc/resolv.conf
searches string[] No Search domains for /etc/resolv.conf
skip_registration boolean No Currently has no effect

fly.dnsForwardRule

Property Type Required Description
addr string No Address and port of the DNS server to forward queries to over TCP, e.g. 10.0.0.1:53
basename string No Domain to forward queries for, including subdomains. Must end in a dot, e.g. example.com.

fly.dnsOption

Property Type Required Description
name string No Option name, e.g. ndots
value string No Option value, e.g. 5

fly.EnvFrom

EnvVar defines an environment variable to be populated from a machine field, env_var

Property Type Required Description
env_var string No EnvVar is required and is the name of the environment variable that will be set from the secret. It must be a valid environment variable name.
field_ref string No FieldRef selects a field of the Machine: supports id, version, app_name, private_ip, region, image. Enum: id, version, app_name, private_ip, region, image

fly.ExecHealthcheck

Property Type Required Description
command string[] No The command to run to check the health of the container (e.g. ["cat", "/tmp/healthy"])

fly.File

A file that will be written to the Machine. One of RawValue or SecretName must be set.

Property Type Required Description
guest_path string No GuestPath is the path on the machine where the file will be written and must be an absolute path. For example: /full/path/to/file.json
image_config string No The name of an image to use the OCI image config as the file contents.
mode integer No Mode bits used to set permissions on this file as accepted by chmod(2).
raw_value string No The base64 encoded string of the file contents.
secret_name string No The name of the secret that contains the base64 encoded file contents.

fly.HTTPHealthcheck

Property Type Required Description
headers fly.MachineHTTPHeader[] No Additional headers to send with the request
method string No The HTTP method to use to when making the request
path string No The path to send the request to
port integer No The port to connect to, often the same as internal_port
scheme fly.ContainerHealthcheckScheme No Whether to use http or https
tls_server_name string No If the protocol is https, the hostname to use for TLS certificate validation
tls_skip_verify boolean No If the protocol is https, whether or not to verify the TLS certificate

fly.HTTPOptions

Property Type Required Description
compress boolean No Compress response bodies. Defaults to true
h2_backend boolean No Use HTTP/2 to talk to the Machine
headers_read_timeout integer No Seconds Fly Proxy waits for a client to send request headers. Defaults to 5
idle_timeout integer No Seconds a client connection can be idle between requests before it's closed. Defaults to 300
replay_cache fly.ReplayCache[] No Cache fly-replay responses from the Machine: once a client is replayed, its further requests are replayed directly, keyed on a cookie or header, without asking the Machine again
response fly.HTTPResponseOptions No Changes Fly Proxy makes to responses

fly.HTTPResponseOptions

Property Type Required Description
headers map<string, object> No Response headers to set. A string sets the header, a list of strings sets it to multiple values, and false removes it
pristine boolean No Don't let Fly Proxy add or change any response headers

fly.MachineCacheDrive

Property Type Required Description
path string No Optional absolute guest mount path. When set, the device is formatted as ext4. Without a path, the device retains legacy raw block behavior. Contents survive same-host restarts and path changes, but are discarded on size or mode changes, relocation, recovery on another host, and cloning.
size_mb integer No Fixed size of the Machine-owned cache drive in MiB. At most 51200. With a path, at least 16 MiB is required; without a path, 0 disables the device.

fly.MachineCheck

Property Type Required Description
grace_period string No The time to wait after a VM starts before checking its health
headers fly.MachineHTTPHeader[] No For http checks, headers to send with the request
interval string No The time between connectivity checks
kind string No Kind of the check (informational, readiness) Enum: informational, readiness
method string No For http checks, the HTTP method to use to when making the request
path string No For http checks, the path to send the request to
port integer No The port to connect to, often the same as internal_port
protocol string No For http checks, whether to use http or https
timeout string No The maximum time a connection can take before being reported as failing its health check
tls_server_name string No If the protocol is https, the hostname to use for TLS certificate validation
tls_skip_verify boolean No For http checks with https protocol, whether or not to verify the TLS certificate
type string No tcp or http

fly.MachineConfig

Property Type Required Description
auto_destroy boolean No Optional boolean telling the Machine to destroy itself once it’s complete (default false)
cache_drive fly.MachineCacheDrive No Beta: a cache drive attached to the Machine. This field may be removed in the future
checks map<string, fly.MachineCheck> No An optional object that defines one or more named top-level checks. The key for each check is the check name.
containers fly.ContainerConfig[] No Containers are a list of containers that will run in the machine, each from its own image.
disable_machine_autostart boolean No Deprecated: use Service.Autostart instead
dns fly.DNSConfig No DNS settings for the Machine
env map<string, string> No An object filled with key/value pairs to be set as environment variables
files fly.File[] No Files to write into the Machine, from either a raw value or an app secret
guest fly.MachineGuest No The resources (CPUs, memory, etc.) allocated to the Machine
image string No The docker image to run
init fly.MachineInit No Arguments for init, Fly.io's footprint inside the Machine, which controls how your own code is run
metadata map<string, string> No Key/value pairs of Machine metadata. Fly.io uses metadata internally for routing, process groups, and clusters
metrics fly.MachineMetrics No An optional metrics endpoint for Prometheus on Fly.io to scrape
mounts fly.MachineMount[] No Persistent volumes to mount in the Machine. A Machine can mount at most one volume, which must be on the same host. The mounted volume cannot be changed by updating the Machine
processes fly.MachineProcess[] No Multiple processes to run within this one Machine, all from the Machine's image. Unrelated to the process groups in fly.toml, which run on separate Machines. To run processes from different images, use containers instead
restart fly.MachineRestart No Whether and how the Machine is restarted after its main process exits
rootfs fly.MachineRootfs No Beta: the size of the Machine's root filesystem and whether it persists. This field may be removed in the future
schedule string No Run the Machine at an interval: one of hourly, daily, weekly or monthly. The interval starts when the Machine is created
services fly.MachineService[] No Network services that Fly Proxy routes traffic to
size string No Deprecated: use Guest instead
spot fly.MachineSpot No Spot pricing settings for the Machine
standbys string[] No Standbys enable a machine to be a standby for another. In the event of a hardware failure, the standby machine will be started.
statics fly.Static[] No Static files to serve under a URL prefix. Fly Proxy routes matching requests to a file server inside the Machine, bypassing your application's own process; the Machine must be running. The files are read either from a path inside the Machine or from a Tigris bucket that belongs to the app; no bucket is created for you
stop_config fly.StopConfig No How the Machine is shut down gracefully: the signal sent to it and how long to wait before a hard shutdown

fly.MachineGuest

Property Type Required Description
cpu_kind string No Kind of CPU: shared or performance. Performance CPUs must be enabled for the organization. Defaults to shared when guest is omitted
cpus integer No Number of CPUs: 1, 2, 4, 6, 8, 10, 12, 14, 16, 32, 64 or 128, up to 8 for shared and 16 for performance CPUs unless the organization's limit is higher. Defaults to 1 when guest is omitted
gpu_kind string No No longer supported. Requests that set it are rejected
gpus integer No No longer supported. Requests that set it are rejected
host_dedication_id string No Place the Machine on hosts dedicated to the organization under this ID. Only available to organizations with dedicated hosts
kernel_args string[] No Extra arguments appended to the guest kernel command line
max_memory_mb integer No Memory in MiB that the Machine's memory limit can later be raised to without a restart, using the memory endpoints. Must be at least memory_mb and at most the per-CPU maximum. The Machine starts with a limit of memory_mb
memory_mb integer No Memory in MiB. Must be a multiple of 256 for shared and 1024 for performance CPUs, and between 256 and 2048 (shared) or 2048 and 8192 (performance) per CPU. Defaults to 256 when guest is omitted
persist_rootfs string No Deprecated: use MachineConfig.Rootfs instead Enum: never, always, restart
required_host_features string[] No Host features the Machine's host must have, such as storage-tier-1. At most 16, each made of lowercase letters, digits and dashes. Each feature must be enabled for the organization

fly.MachineHTTPHeader

For http checks, an array of objects with string field Name and array of strings field Values. The key/value pairs specify header and header values that will get passed with the check call.

Property Type Required Description
name string No The header name
values string[] No The header value

fly.MachineInit

Property Type Required Description
cmd string[] No Replaces the image's CMD. It's appended to the entrypoint
entrypoint string[] No Replaces the image's ENTRYPOINT
exec string[] No Command to run instead of the image's ENTRYPOINT and CMD. Takes precedence over entrypoint and cmd
kernel_args string[] No Currently has no effect. Use guest.kernel_args instead
swap_size_mb integer No Size in MiB of a swap device to give the Machine. Machines with swap cannot be suspended
tty boolean No Currently has no effect

fly.MachineMetrics

Property Type Required Description
https boolean No Scrape over HTTPS instead of HTTP
path string No HTTP path to scrape. Defaults to /
port integer No Port in the Machine to scrape metrics from

fly.MachineMount

Property Type Required Description
add_size_gb integer No With automatic extension, grow the volume by this many GB at a time. Between 1 and 100. Mutually exclusive with add_size_percent
add_size_percent integer No AddSizePercent grows by a percentage of the current size, rounded up to GiB. It is mutually exclusive with AddSizeGb.
encrypted boolean No Whether the volume is encrypted. Set by Fly.io; ignored in requests
extend_threshold_percent integer No Enable automatic volume extension: grow the volume when its usage exceeds this percentage. Between 50 and 99; 0 disables it
min_add_size_gb integer No MinAddSizeGb is the minimum proportional growth in GiB (default 1).
name string No Name of the volume. Set by Fly.io; ignored in requests
path string No Absolute path in the Machine to mount the volume at. Required
size_gb integer No Size of the volume in GB. Set by Fly.io; ignored in requests
size_gb_limit integer No With automatic extension, never grow the volume beyond this size in GB. At most the organization's maximum volume size
volume string No ID (vol_...) or name of the volume to mount. Required. With a name, any unattached volume of the app with that name in the Machine's region is used

fly.MachinePort

Property Type Required Description
end_port integer No Last public port of a range
force_https boolean No Redirect plain HTTP requests to HTTPS
handlers string[] No How Fly Proxy handles connections before forwarding them: tls terminates TLS, pg_tls terminates PostgreSQL TLS, http handles HTTP, proxy_proto adds a PROXY protocol header. Without handlers, raw TCP is forwarded
http_options fly.HTTPOptions No Options for the http handler
port integer No Public port. Use either port, or start_port and end_port
proxy_proto_options fly.ProxyProtoOptions No Options for the proxy_proto handler
start_port integer No First public port of a range
tls_options fly.TLSOptions No Options for the tls handler

fly.MachineProcess

Property Type Required Description
cmd string[] No Replaces the image's CMD for this process. It's appended to the entrypoint
entrypoint string[] No Replaces the image's ENTRYPOINT for this process
env map<string, string> No Environment variables for this process, in addition to the Machine's env
env_from fly.EnvFrom[] No EnvFrom can be provided to set environment variables from machine fields.
exec string[] No Command to run instead of the image's ENTRYPOINT and CMD. Takes precedence over entrypoint and cmd
ignore_app_secrets boolean No IgnoreAppSecrets can be set to true to ignore the secrets for the App the Machine belongs to and only use the secrets provided at the process level. The default/legacy behavior is to use the secrets provided at the App level.
secrets fly.MachineSecret[] No Secrets can be provided at the process level to explicitly indicate which secrets should be used for the process. If not provided, the secrets provided at the machine level will be used.
user string No User to run the process as, instead of the image's USER

fly.MachineRestart

The Machine restart policy defines whether and how flyd restarts a Machine after its main process exits. See https://fly.io/docs/machines/guides-examples/machine-restart-policy/.

Property Type Required Description
max_retries integer No When policy is on-failure, the maximum number of times to attempt to restart the Machine before letting it stop.
policy string No * no - Never try to restart a Machine automatically when its main process exits, whether that’s on purpose or on a crash. * always - Always restart a Machine automatically and never let it enter a stopped state, even when the main process exits cleanly. * on-failure - Try up to MaxRetries times to automatically restart the Machine if it exits with a non-zero exit code. Default when no explicit policy is set, and for Machines with schedules. Enum: no, always, on-failure

fly.MachineRootfs

Property Type Required Description
persist string No Whether changes to the root filesystem are kept. never (default): reset on every start. restart: kept across stops and restarts, reset when the Machine is updated. always: also kept across updates Enum: never, always, restart
size_gb integer No Size of the root filesystem in GB. At most 50; 0 uses the default

fly.MachineSecret

A Secret needing to be set in the environment of the Machine. env_var is required

Property Type Required Description
env_var string No EnvVar is required and is the name of the environment variable that will be set from the secret. It must be a valid environment variable name.
name string No Name is optional and when provided is used to reference a secret name where the EnvVar is different from what was set as the secret name.

fly.MachineService

Property Type Required Description
autostart boolean No Whether Fly Proxy starts stopped or suspended Machines when requests arrive. Defaults to true
autostop string No Accepts a string (new format) or a boolean (old format). For backward compatibility with older clients, the API continues to use booleans for "off" and "stop" in responses. * "off" or false - Do not autostop the Machine. * "stop" or true - Automatically stop the Machine. * "suspend" - Automatically suspend the Machine, falling back to a full stop if this is not possible. Enum: off, stop, suspend
checks fly.MachineServiceCheck[] No An optional list of service checks
concurrency fly.MachineServiceConcurrency No Load limits Fly Proxy uses to balance traffic across Machines
force_instance_description string No Currently has no effect
force_instance_key string No Currently has no effect
internal_port integer No Port in the Machine that Fly Proxy forwards traffic to. Defaults to 8080
min_machines_running integer No When autostop is on, the number of Machines Fly Proxy keeps running in the app's primary region (PRIMARY_REGION env var). Machines in other regions can all be stopped
ports fly.MachinePort[] No Public ports that Fly Proxy accepts traffic on
protocol string No Protocol: tcp or udp. Defaults to tcp

fly.MachineServiceCheck

Property Type Required Description
grace_period string No The time to wait after a VM starts before checking its health
headers fly.MachineHTTPHeader[] No For http checks, headers to send with the request
interval string No The time between connectivity checks
method string No For http checks, the HTTP method to use to when making the request
path string No For http checks, the path to send the request to
port integer No The port to connect to, often the same as internal_port
protocol string No For http checks, whether to use http or https
timeout string No The maximum time a connection can take before being reported as failing its health check
tls_server_name string No If the protocol is https, the hostname to use for TLS certificate validation
tls_skip_verify boolean No For http checks with https protocol, whether or not to verify the TLS certificate
type string No tcp or http

fly.MachineServiceConcurrency

Property Type Required Description
hard_limit integer No Fly Proxy sends no more than this many connections or requests to a Machine at once. 0 means no hard limit
soft_limit integer No Above this many connections or requests, Fly Proxy prefers other Machines. Defaults to 20, and is lowered to hard_limit if higher
type string No What to count: connections (default) or requests

fly.MachineSpot

Property Type Required Description
max_price_fraction number No MaxPriceFraction is the maximum fraction of the full Machine price you will pay for this Machine. Range: (0, 1.0]

fly.ProxyProtoOptions

Property Type Required Description
fly_src boolean No With version v2, add the Fly-Src header and its signature to the PROXY protocol header
version string No PROXY protocol version: v1 (default) or v2

fly.ReplayCache

Property Type Required Description
allow_bypass boolean No Let clients skip the cache by sending the fly-replay-cache-control: skip header
name string No Name of the cookie or header to key the cache on
path_prefix string No Requests whose path starts with this prefix use the rule. May start with a hostname, e.g. example.com/api/*
ttl_seconds integer No How long a cached replay is used, in seconds
type string No Currently either "cookie" or "header" Enum: cookie, header

fly.Static

Property Type Required Description
guest_path string Yes The path inside the Machine, or inside tigris_bucket when set, where the files to serve are located
index_document string No The document served for requests to the URL prefix or any of its subfolders. Only works with tigris_bucket
tigris_bucket string No An existing Tigris bucket belonging to the app to read the files from, instead of the Machine's filesystem. The files are still served through the Machine
url_prefix string Yes The URL prefix under which the files are served

fly.StopConfig

Property Type Required Description
signal string No Signal to send to the Machine's processes. Defaults to SIGINT Enum: SIGHUP, SIGINT, SIGQUIT, SIGKILL, SIGUSR1, SIGUSR2, SIGTERM
timeout string No How long to wait for the Machine to exit after sending the signal, before killing it. At most 5 minutes (1 minute for spot Machines). Defaults to 5s (60s for spot Machines)

fly.TCPHealthcheck

Property Type Required Description
port integer No The port to connect to, often the same as internal_port

fly.TLSOptions

Property Type Required Description
alpn string[] No ALPN protocols to offer, e.g. h2, http/1.1. Defaults to h2 and http/1.1
default_self_signed boolean No Use a self-signed certificate when there is no certificate for the requested hostname
versions string[] No TLS versions to accept: TLSv1.2, TLSv1.3. Defaults to both

fly.UnhealthyPolicy

Type: string

Enum: stop

flyio.Access

Property Type Required Description
action resset.Action No
app_feature string No
appid integer No
cluster string No
command string[] No
feature string No
machine string No
machine_feature string No
mutation string No
orgid integer No
sourceApp string No
sourceMachine string No
sourceOrganization string No
storage_object string No
volume string No

forkPostgresClusterRequest

Property Type Required Description
name string No Name for the forked cluster. Defaults to the source name with a -fork suffix.
plan string No Plan slug selecting CPU and memory sizing for the fork. Defaults to the source cluster's plan. Matched case-insensitively. Enum: basic, starter, launch, scale, Performance

getPostgresUserCredentialsResponse

Property Type Required Description
data PostgresUserCredentials No

ImageRef

Property Type Required Description
digest string No Content digest of the image (sha256:...).
labels map<string, string> No The image's OCI labels.
registry string No Registry host of the image, such as registry.fly.io.
repository string No Repository of the image within the registry, such as library/nginx.
tag string No Tag the image was referenced by, if any.

IPAssignment

Property Type Required Description
created_at string No When the address was assigned to the app, in RFC 3339 format. Null for the app's shared IPv4 address.
egress boolean No Whether this is an egress address, used for the app's outbound traffic rather than for receiving requests.
ip string No The IP address.
network IPAssignmentNetwork No
region string No Region the address is scoped to, or global for addresses announced in all regions. Empty for the app's shared IPv4 address.
service_name string No Name of the service the address is scoped to, if any.
shared boolean No Whether this is the app's shared IPv4 address, which other apps use too.

IPAssignmentNetwork

The 6PN network a Flycast (private_v6) address belongs to. Null for all other IP types.

Property Type Required Description
name string No Network name; empty for the organization's default network.
org_slug string No Slug of the organization the network belongs to.

IPAssignmentType

Type of IP address to allocate. "egress_pair" allocates both v4 and v6 egress IP addresses (recommended when using egress IPs).

Type: string

Enum: v4, v6, shared_v4, private_v6, egress_v4, egress_v6, egress_pair

IPPair

Property Type Required Description
v4 string No The egress IPv4 address.
v6 string No The egress IPv6 address.

IssuedCertificate

Property Type Required Description
certificate_authority string No The certificate authority that issued the certificate.
expires_at string No When the certificate expires.
type string No Key type of the certificate. Enum: rsa, ecdsa

Lease

Property Type Required Description
description string No Description or reason for the lease.
expires_at integer No When the lease expires, in Unix seconds.
nonce string No Unique ID generated for the lease. Pass it in the fly-machine-lease-nonce header to act on the leased Machine, refresh the lease, or release it.
owner string No Email address of the user who acquired the lease.
version string No ID of the Machine's version at the time of the request.

LeaseErrorResponse

Property Type Required Description
message string No What went wrong.
status string No Always error. Enum: error

LeaseOkResponse

Property Type Required Description
data OkResponse No
status string No Always success. Enum: success

LeaseResponse

Property Type Required Description
data Lease No The lease.
status string No Always success. Enum: success

ListAppsResponse

Property Type Required Description
apps App[] No The apps on this page, or all apps if limit was not provided.
next_cursor string No Pagination cursor for the next page. Absent when no more apps remain. Cursors expire 30 minutes after the first page was requested.
total_apps integer No The number of matching apps across all pages. Organization-wide listings retain the first page's count; scoped listings recount using the current token's permissions. Snapshot bounds exclude newer apps, and replication lag or deletion during traversal can make totals differ from rows seen.

listCertificatesResponse

Property Type Required Description
certificates CertificateSummary[] No The certificates on this page, ordered by when they were added.
next_cursor string No Pagination cursor for the next page. Absent when no more certificates remain.
total_count integer No Number of certificates matching filter (and after cursor, if given), across all pages.

ListenSocket

Property Type Required Description
address string No Local address and port the socket is bound to, such as 0.0.0.0:8080 or [::]:8080.
proto string No Protocol of the socket. Always tcp.

listIPAssignmentsResponse

Property Type Required Description
ips IPAssignment[] No The app's IP addresses, including its shared IPv4 address and egress addresses.

listPostgresActiveQueriesResponse

Property Type Required Description
data PostgresActiveQuery[] No

listPostgresBackupsResponse

Property Type Required Description
data PostgresBackup[] No

listPostgresClustersResponse

Property Type Required Description
data PostgresClusterSummary[] No

listPostgresDatabasesResponse

Property Type Required Description
data PostgresDatabase[] No

listPostgresExtensionsResponse

Property Type Required Description
data PostgresExtension[] No

listPostgresPlansResponse

Property Type Required Description
data PostgresPlan[] No

listPostgresSlowQueriesResponse

Property Type Required Description
data PostgresSlowQuery[] No

listPostgresUsersResponse

Property Type Required Description
data PostgresUser[] No

macaroon.CaveatSet

Property Type Required Description
caveats object[] No

macaroon.Nonce

Property Type Required Description
kid integer[] No
proof boolean No
rnd integer[] No

Machine

Property Type Required Description
checks CheckStatus[] No Status of each health check: the Machine's top-level checks and its services' checks.
config fly.MachineConfig No The Machine's configuration, as provided when it was created or last updated, with metadata and mounts reflecting their current values. Null when the host is not reachable (host_status is not ok) or summary=true was requested; see incomplete_config.
cordoned boolean No Whether the Machine is cordoned, meaning Fly Proxy does not route requests to it. See the Cordon Machine endpoint.
created_at string No When the Machine was created.
events MachineEvent[] No Up to 5 of the most recent events of the current Machine version, newest first. Use the List Events endpoint for more.
host_features string[] No Features of the Machine's host, for comparison with config.guest.required_host_features. Only returned when the request sets the fly-include-host-features: true header.
host_status string No Whether Fly.io could reach the Machine's host: ok if it could, unreachable if it could not, in which case the response is built from last known state. unknown if the host's status was not reported. Enum: ok, unknown, unreachable
id string No Unique ID of the Machine.
image_ref ImageRef No The image the Machine runs, as resolved when it was last created or updated.
incomplete_config fly.MachineConfig No Last known configuration, returned in place of config when the host could not be reached (host_status is not ok) or when listing Machines with summary=true. It comes from Fly.io's replicated state rather than the host, so it may be stale or lack fields.
instance_id string No Same value as version. Deprecated: use version.
lease StrippedLease No The lease currently held on the Machine. Only returned when include_leases=true was requested and a lease is held.
name string No Name of the Machine. Generated when not provided at creation. Names are not required to be unique.
nonce string No Nonce of the lease acquired on the Machine at creation. Only returned when creating a Machine with lease_ttl set. Pass it in the fly-machine-lease-nonce header to act on the Machine while the lease is held.
private_ip string No The Machine's address on the organization's private (6PN) IPv6 network.
region string No Code of the region the Machine runs in, such as iad.
state string No Current state of the Machine, taken from the status of its most recent event. One of created, starting, started, stopping, stopped, suspending, suspended, replacing, replaced, destroying, destroyed, failed, migrating, migrated, archived, or pending. See https://fly.io/docs/machines/machine-states/.
updated_at string No Time of the Machine's most recent event, truncated to whole seconds. The zero time (0001-01-01T00:00:00Z) if the host could not be reached. With summary=true, the time Fly.io last recorded a change to the Machine.
version string No Unique ID of this version of the Machine. Every update creates a new version. Pass it as current_version when updating the Machine to reject the update if the Machine has changed since this version.

MachineEvent

Property Type Required Description
id string No Unique ID of the event (a ULID).
request object No Details that depend on the event type. For example, exit events carry the exit code and whether the process was killed for running out of memory, and update events carry the new version.
source string No Who triggered the event: user for requests to this API, flyd for the host's Machine manager acting on its own (for example when a Machine exits or restarts), or proxy for Fly Proxy starting and stopping Machines.
status string No The state the Machine moved to with this event, such as created, started, or stopped. The Machine's state is the status of its latest event.
timestamp integer No When the event happened, in Unix milliseconds.
type string No What happened, such as launch, start, stop, exit, restart, update, suspension, cancel_suspension, migration, metadata_update, archive, or destroy.

MachineExecRequest

Property Type Required Description
cmd string No Command line to run, split into arguments like a shell would. Takes precedence over command. Deprecated: use command.
command string[] No Command to run, as the program followed by its arguments. It is run directly, not by a shell.
container string No Name of the container to run the command in, for Machines with containers.
machine boolean No Run the command in the Machine's own namespace instead of in a container. Mutually exclusive with container.
stdin string No Data to write to the command's standard input.
timeout integer No How long to let the command run, in seconds. Defaults to 10; at most 600.

MachineOverviewConfig

Property Type Required Description
guest fly.MachineGuest No The Machine's CPU, memory, and GPU configuration.
image string No The image reference the Machine was configured with.
metadata map<string, string> No The Machine's metadata key-value pairs.

MachineVersion

Property Type Required Description
user_config fly.MachineConfig No The configuration of that version, as provided by the create or update request.
version string No ID of the Machine version.

main.getPlacementsRequest

Property Type Required Description
compute fly.MachineGuest No Resource requirements for the Machine to simulate. Defaults to a performance-1x machine
count integer No Number of machines to simulate placement. Defaults to 0, which returns the org-specific limit for each region.
org_slug string Yes Slug of the organization to place Machines for, or personal. Required.
region string No Region expression for placement as a comma-delimited set of regions or aliases. Defaults to the API endpoint's local region. When count is greater than 0, any is added as a fallback.
volume_name string No Currently unused.
volume_size_bytes integer No Size of a volume each Machine will need, in bytes. Only hosts with room for it are considered.
weights placement.Weights No Optional weights to override default placement preferences.

main.getPlacementsResponse

Property Type Required Description
Regions placement.RegionPlacement[] No The regions Machines would be placed in. With count 0, every requested region with the organization's Machine limit in it.

main.memoryResponse

Property Type Required Description
available_mb integer No Highest limit, in MiB, that the Machine could currently be raised to: its configured memory (guest.max_memory_mb if set, else guest.memory_mb), capped by the host's free memory.
limit_mb integer No Memory, in MiB, the guest can currently use.

main.reclaimMemoryRequest

Property Type Required Description
amount_mb integer No Memory to reclaim, in MiB. Must be positive and at most the Machine's memory limit minus 128 MiB.

main.reclaimMemoryResponse

Property Type Required Description
actual_mb integer No Memory, in MiB, that the guest actually gave up. Can be less than requested.

main.regionResponse

Property Type Required Description
Regions main.regionRow[] No The regions available to the caller.
nearest string No Code of the region of the Fly.io edge that received the request, usually the one closest to the caller.

main.regionRow

Property Type Required Description
code string No Region code, such as iad, used to select the region in other requests.
deprecated boolean No Whether the region is deprecated. Avoid creating new resources in it.
gateway_available boolean No Whether the region has a WireGuard gateway that private network peers can connect to.
geo_region string No Geographic area the region belongs to. Enum: africa, asia_pacific, europe, north_america, south_america
latitude number No Latitude of the region's location.
longitude number No Longitude of the region's location.
mpg_available boolean No Whether Managed Postgres clusters can be created in the region.
name string No Human-readable name of the region, such as Ashburn, Virginia (US).
requires_paid_plan boolean No Whether only organizations on a paid plan can use the region.

main.setMemoryLimitRequest

Property Type Required Description
limit_mb integer No New limit in MiB. Must be at least 128 and at most the Machine's configured memory (guest.max_memory_mb if set, else guest.memory_mb).

main.statusCode

Type: string

Enum: unknown, insufficient_capacity, volume_placement_capacity, exec_request_too_large, exec_output_too_large, name_taken

main.TokenAccess

Property Type Required Description
action resset.Action No Action is the action being taken on the specified resource. This is the combination of individual action characters (e.g "rw") - r: read - w: write - c: create - d: delete - C: control
app_feature string No AppFeature is a named set of functionality associated with the app. If this is specified, the AppName field must be set. - images: images in the fly.io registry
app_name string No AppName is the name of the app being accessed.
command string[] No Command is the command being executed on a machine. If this is specified, the Machine must be set.
machine_feature string No MachineFeature is a named set of functionality associated with the machine. If this is specified, the Machine field must be set. - metadata: machine metadata service - oidc: OIDC tokens - kmstoken: Petsem tokens for KMS access
machine_id string No MachineID is the ID of the machine being accessed (e.g. 7811701f564258).
mutation string No Mutation is the GraphQL mutation being performed.
org_feature string No OrgFeature is a named set of functionality associated with the organization. If this is specified, the OrgSlug field must be set. - wg: WireGuard peers - builder: remote builders - addon: addons - membership: organization membership - billing: billing - litefs-cloud: LiteFS Cloud - authentication: authentication settings
org_slug string No OrgSlug is the slug of the organization being accessed.
source_machine string No SourceMachine is the machine ID of the actor attempting access.
storage_object string No StorageObject is the storage object being accessed. If this is specified, the OrgSlug must be set.
volume_id string No VolumeID is the encoded ID of the volume being accessed (e.g. vol_r1p6pln1k9m9j7zr).

main.tokenInfo

Property Type Required Description
apps string[] No Names of the apps the token is restricted to. Omitted if the token is not restricted to specific apps.
org_slug string No Slug of the organization the token is scoped to.
organization string No Name of the organization the token is scoped to.
restricted_to_machine string No ID of the Machine the token may only be used from. Omitted if the token is not restricted to a Machine.
source_machine_id string No Never set.
token_id string No ID of the token.
user string No Opaque identifier of the user the token belongs to: the first 7 hex characters of a hash of the user's ID. Omitted for tokens that do not belong to a user.

metadataValueResponse

Property Type Required Description
value string No Value of the metadata key.

OkResponse

Property Type Required Description
ok boolean No Always true.

OrganizationRef

Property Type Required Description
name string No Organization name.
slug string No Organization slug.

OrgMachine

Property Type Required Description
app_name string No Name of the app the Machine belongs to.
config MachineOverviewConfig No Subset of the Machine's configuration. Omitted when summary=true.
created_at string No When the Machine was created.
id string No Unique ID of the Machine.
name string No Name of the Machine.
private_ip string No The Machine's address on the organization's private (6PN) IPv6 network.
region string No Code of the region the Machine runs in.
state string No Current state of the Machine; see the state field of Machine.
updated_at string No When Fly.io last recorded a change to the Machine.
version string No ID of the Machine's current version.

OrgMachinesResponse

Property Type Required Description
error_regions string[] No Regions that could not be queried. Their Machines are missing from the response.
last_machine_id string No ID of the last Machine on this page.
last_updated_at string No updated_at of the last Machine on this page.
machines OrgMachine[] No The Machines on this page.
next_cursor string No Pagination cursor for the next page. Absent when no more Machines remain. Cursors expire 30 minutes after the first page was requested.

OrgVolume

Property Type Required Description
app_name string No Name of the app the volume belongs to.
attached_alloc_id string No Always null. Deprecated: volumes are no longer attached to Nomad allocations.
attached_machine_id string No ID of the Machine the volume is attached to, or null if it is not attached.
auto_backup_enabled boolean No Whether daily automatic snapshots are taken.
block_size integer No Size of a filesystem block, in bytes. See blocks.
blocks integer No 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 No Number of filesystem blocks available to unprivileged users. See blocks.
blocks_free integer No Number of free filesystem blocks, including blocks reserved for the root user. See blocks.
bytes_total integer No Size of the volume, in bytes. 0 if the host could not be reached or with summary=true.
bytes_used integer No 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 No When the volume was created.
encrypted boolean No Whether the volume is encrypted at rest.
fstype string No Filesystem the volume was formatted with: ext4, or raw for an unformatted block device.
host_features string[] No Features of the volume's host. Only returned when the request sets the fly-include-host-features: true header.
host_status string No 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. Enum: ok, unknown, unreachable
id string No Unique ID of the volume, such as vol_1234567890abcdef.
name string No Name of the volume. Several volumes of an app can share a name.
region string No Code of the region the volume is in.
required_host_features string[] No Host features the volume's host was required to have; see compute.required_host_features in the create request.
size_gb integer No Size of the volume, in GiB.
snapshot_retention integer No Number of days snapshots of the volume are kept.
state string No State of the volume, such as creating, created, extending, restoring, hydrating, scheduling_destroy, pending_destroy, destroying, destroyed, or failed.
type string No Kind of volume: local for regular volumes, or cache for volumes that hold disposable data and support neither snapshots nor restores. Enum: local, cache
updated_at string No When Fly.io last recorded a change to the volume.
zone string No Identifies the host the volume is on. Volumes with different zones are on different hosts.

OrgVolumesResponse

Property Type Required Description
last_updated_at string No updated_at of the last volume on this page.
last_volume_id string No ID of the last volume on this page.
next_cursor string No Pagination cursor for the next page. Absent when no more volumes remain.
volumes OrgVolume[] No The volumes on this page.

OwnershipVerification

Property Type Required Description
app_value string No TXT record value that proves ownership for this app.
name string No Name of the TXT record to create, such as _fly-ownership.example.com.
org_value string No TXT record value that proves ownership for every app in the organization.

placement.RegionPlacement

Property Type Required Description
Concurrency integer No Number of distinct hosts those Machines would be spread over. 0 when the request's count is 0.
Count integer No Number of Machines that would be placed in the region. When the request's count is 0, the organization's Machine limit for the region instead.
Region string No Code of the region.

placement.Weights

Type: map<string, integer>

PostgresActiveQuery

Property Type Required Description
application_name string No Application connected to the backend.
client string No Client address.
database string No Database name.
duration_seconds number No Query duration in seconds.
pid integer No Process ID of the backend running the query.
query string No Full query text.
state string No Current backend state.
state_duration_seconds number No Time spent in the current state, in seconds.
user string No User running the query.
wait_event string No Event the backend is waiting for.
wait_event_type string No Type of event the backend is waiting for.

PostgresAttachedApp

Property Type Required Description
name string No Attached Fly app name.

PostgresAttachment

Property Type Required Description
app_name string No Attached Fly app name.
attached_at string No RFC 3339 timestamp when the attachment was created.
postgres_cluster_id string No Cluster ID the app is attached to.

PostgresBackup

Property Type Required Description
finished_at string No RFC 3339 stop timestamp.
id string No Backup ID.
size_bytes integer No Backup size in bytes.
started_at string No RFC 3339 start timestamp.
status string No Backup status.
type string No Backup type. Enum: full, incr, diff

PostgresCluster

Property Type Required Description
attached_apps PostgresAttachedApp[] No Apps attached to the cluster.
cpu_kind string No CPU class. Enum: shared, performance
cpus integer No vCPUs per node.
created_at string No RFC 3339 creation timestamp.
disk_size_gb integer No Disk size in gigabytes, for one replica.
endpoints PostgresClusterEndpoints No Connection endpoints. Populated once the cluster is ready.
id string No Cluster ID.
memory_mb integer No Memory per node in megabytes.
name string No Cluster name.
organization OrganizationRef No
pg_major_version string No Postgres major version. Enum: 16, 17
plan string No Plan slug. Enum: basic, starter, launch, scale, Performance
postgis_enabled boolean No Whether PostGIS support is enabled.
region string No Fly region code.
replicas integer No Number of replicas.
status string No Current lifecycle status. Enum: creating, initializing, ready, deleting, deleted, failed
storage_provisioned_bytes integer No Storage provisioned, summed across the cluster's volumes and measured hourly. Null until first measured.
storage_used_bytes integer No Storage used, summed across the cluster's volumes and measured hourly. Null until first measured.

PostgresClusterEndpoints

Property Type Required Description
primary PostgresNodeEndpoints No Endpoints for connecting to the primary node.

PostgresClusterSummary

Property Type Required Description
attached_apps PostgresAttachedApp[] No Apps attached to the cluster.
created_at string No RFC 3339 creation timestamp.
deleted_at string No RFC 3339 deletion timestamp; present for deleted clusters.
id string No Cluster ID.
name string No Cluster name.
plan string No Plan slug. Enum: basic, starter, launch, scale, Performance
region string No Fly region code.
status string No Current lifecycle status. Enum: creating, initializing, ready, deleting, deleted, failed

PostgresDatabase

Property Type Required Description
name string No Database name.

postgresDatabaseResponse

Property Type Required Description
data PostgresDatabase No

PostgresEndpoint

Property Type Required Description
host string No Hostname to connect to.
port integer No TCP port.

PostgresErrorResponse

Property Type Required Description
error string No Human-readable error message.
status string No Optional machine-readable error status.

PostgresExtension

Property Type Required Description
default_version string No Default version installed when enabled.
description string No Human-readable description.
installed PostgresInstalledExtension No Installation details, or null when the extension is not installed.
name string No Extension name.
system boolean No Whether this is a system extension that cannot be disabled.

PostgresInstalledExtension

Property Type Required Description
schema string No Schema the extension is installed into.
version string No Installed version.

PostgresNodeEndpoints

Property Type Required Description
direct PostgresEndpoint No Unpooled connection to the cluster node.
pooler PostgresEndpoint No Pooled connection to the cluster node (through PgBouncer).

PostgresPlan

Property Type Required Description
cpu_kind string No CPU class. Enum: shared, performance
cpus integer No vCPUs per node.
memory_mb integer No Memory per node in megabytes.
monthly_price_usd integer No Base monthly price in US dollars.
plan string No Plan slug. Pass it as plan when creating or forking a cluster. Enum: basic, starter, launch, scale, Performance

PostgresQueryColumn

Property Type Required Description
name string No Column name as returned by Postgres.
type string No Postgres type name.

postgresQueryResponse

Property Type Required Description
columns PostgresQueryColumn[] No Columns of the final result set, in order.
row_count integer No Number of rows returned.
rows object[][] No Rows of the final result set; each row holds one JSON value per column, with NULL as null and json/jsonb as decoded JSON.

PostgresSlowQuery

Property Type Required Description
calls integer No Cumulative number of executions.
database string No Database name.
max_exec_time_seconds number No Maximum execution time in seconds.
mean_exec_time_seconds number No Mean execution time in seconds.
query string No Full query pattern.
query_id string No Query identifier.
total_exec_time_seconds number No Cumulative total execution time in seconds.
user string No User running the query.

PostgresUser

Property Type Required Description
role string No User role. Enum: schema_admin, writer, reader
username string No User name.

PostgresUserCredentials

Property Type Required Description
password string No User password.
username string No User name.

ProcessStat

Property Type Required Description
command string No The process's command line, with arguments separated by spaces.
cpu integer No Average CPU usage over the process's lifetime, in percent of one CPU. May exceed 100 on Machines with more than one CPU.
directory string No The process's working directory.
listen_sockets ListenSocket[] No TCP sockets the process is listening on.
pid integer No Process ID inside the Machine.
rss integer No Resident set size: the physical memory the process uses, in bytes.
rtime integer No How long the process has been running, in seconds.
stime integer No When the process started, in seconds since the Machine booted.

queryPostgresDatabaseRequest

Property Type Required Description
sql string Yes SQL to run, up to 102400 bytes. Multiple statements are allowed; only the last result set is returned.

resset.Action

Type: integer

Enum: 1, 2, 4, 8, 16, 31, 0

restorePostgresClusterRequest

Property Type Required Description
backup_id string No Backup label to restore from, as returned by the backups list. Mutually exclusive with pitr_time.
name string No Name for the restored cluster. Defaults to a generated name derived from the source cluster and backup/point in time when omitted or blank.
pitr_time string No Point in time to restore to, as an RFC3339 timestamp with an explicit offset from UTC (e.g. Z or +02:00). Normalized to UTC and must fall within the cluster's PITR recovery window. Mutually exclusive with backup_id.

root.VerifiedToken

Property Type Required Description
caveats macaroon.CaveatSet No
header string No
nonce macaroon.Nonce No
permission_token integer[] No

rotatePostgresPasswordRequest

Property Type Required Description
kill_sessions boolean No Terminate the user's existing sessions after rotating.

rotatePostgresPasswordResponse

Property Type Required Description
data PostgresUserCredentials No

SecretKey

Property Type Required Description
created_at string No When the key was first set.
name string No Name of the secret key.
public_key string No Public key of asymmetric keys (nacl_box, nacl_sign, es256), base64-encoded.
type string No Type of the key: hs256, hs384, hs512, xaes256gcm, nacl_auth, nacl_box, nacl_secretbox, nacl_sign, or es256.
updated_at string No When the key last changed.

SecretKeys

Property Type Required Description
secret_keys SecretKey[] No The app's secret keys. Key material is never returned.

SetAppSecretRequest

Property Type Required Description
value string No New value of the secret.

SetAppSecretResponse

Property Type Required Description
Version integer No Same value as version. Deprecated: use version.
created_at string No When the secret was first set. Only returned when reading secrets.
digest string No Short fingerprint of the value, to tell whether it changed without revealing it. Omitted for deleted secrets.
name string No Name of the secret.
updated_at string No When the secret's value last changed. Only returned when reading secrets.
value string No Value of the secret. Only returned with show_secrets=true, and when setting secrets.
version integer No The app's secrets version after this change. Pass it as min_secrets_version when creating or updating Machines so that they are guaranteed to see the change.

SetSecretkeyRequest

Property Type Required Description
type string No Type of the key: hs256, hs384, hs512, xaes256gcm, nacl_auth, nacl_box, nacl_secretbox, nacl_sign, or es256. Required.
value string No Key material, base64-encoded. Ignored when generating a key.

SetSecretkeyResponse

Property Type Required Description
Version integer No Same value as version. Deprecated: use version.
created_at string No When the key was first set.
name string No Name of the secret key.
public_key string No Public key of asymmetric keys (nacl_box, nacl_sign, es256), base64-encoded.
type string No Type of the key: hs256, hs384, hs512, xaes256gcm, nacl_auth, nacl_box, nacl_secretbox, nacl_sign, or es256.
updated_at string No When the key last changed.
version integer No The app's secrets version after this change. Pass it as min_version to read the change back.

showPostgresClusterResponse

Property Type Required Description
data PostgresCluster No

SignalRequest

Property Type Required Description
signal string No Signal to send to the Machine's main process. Enum: SIGABRT, SIGALRM, SIGFPE, SIGHUP, SIGILL, SIGINT, SIGKILL, SIGPIPE, SIGQUIT, SIGSEGV, SIGTERM, SIGTRAP, SIGUSR1, SIGUSR2

SignSecretkeyRequest

Property Type Required Description
plaintext string No Data to sign, base64-encoded.

SignSecretkeyResponse

Property Type Required Description
signature string No Signature or MAC of the data, base64-encoded.

StartMachineResponse

Property Type Required Description
migrated boolean No Whether the Machine was moved to another host to be started
new_host string No The host the Machine was moved to, if it was migrated
previous_state string No The state the Machine was in before it was started

StopRequest

Property Type Required Description
signal string No Signal to send to the Machine's main process. Defaults to config.stop_config.signal, or SIGINT. Enum: SIGHUP, SIGINT, SIGQUIT, SIGKILL, SIGUSR1, SIGUSR2, SIGTERM
timeout string No How long to wait for the Machine to exit after sending signal before killing it, as a Go duration string. Defaults to config.stop_config.timeout, or 5s.

StrippedLease

Property Type Required Description
description string No Description given when the lease was acquired.
expires_at integer No When the lease expires, in Unix seconds.
owner string No Email address of the user who acquired the lease.

UpdateMachineRequest

Property Type Required Description
config fly.MachineConfig No The new Machine configuration. It replaces the current one entirely.
current_version string No Optional optimistic-concurrency guard: the Machine's version, as returned by create, get or a previous update. When set and it is no longer the Machine's current version, the update is rejected with 409 Conflict and nothing changes. Omit it to update unconditionally.
lease_ttl integer No Ignored. Use the lease endpoints to lease an existing Machine.
min_secrets_version integer No The minimum version of the app's secrets the Machine must run with. Set it to the version returned by the endpoints that set or delete app secrets, so that the Machine is guaranteed to see those changes. This field belongs at the top level of the request body, not in config. If omitted, the app's current secrets version is looked up for you.
name string No Ignored.
region string No Not used to place the Machine: an update never moves it to another region or host.
skip_launch boolean No Apply the update without starting the Machine. It ends up stopped; start it with the Start Machine endpoint. Not allowed for spot Machines.
skip_secrets boolean No Don't look up the app's current secrets version. The Machine still gets the app's secrets, but may not see recent changes to them. Takes precedence over min_secrets_version.
skip_service_registration boolean No Ignored. Use the cordon and uncordon endpoints instead.

updateMetadataRequest

Property Type Required Description
machine_version string No Only apply the change if this is still the Machine's current version; otherwise fail with 412. Defaults to the current version.
metadata map<string, string> No Keys to change. A string value sets the key; null, an empty string or whitespace removes it. Keys and values have surrounding whitespace trimmed. Keys not listed are left alone. Must contain at least one key.
updated_at string No Time to record for the change in the Machine's metadata_update event. Defaults to now.

updatePostgresUserRoleRequest

Property Type Required Description
role string Yes New role for the user. Enum: schema_admin, writer, reader

UpdateVolumeRequest

Property Type Required Description
auto_backup_enabled boolean No Take daily automatic snapshots of the volume. Unchanged if omitted.
snapshot_retention integer No Number of days to keep snapshots of the volume, from 1 to 60. Unchanged if omitted.

upsertMetadataKeyRequest

Property Type Required Description
updated_at string No Time to record for the change in the Machine's metadata_update event. Defaults to now.
value string No Value to set. Must not be empty or whitespace only.

VerifySecretkeyRequest

Property Type Required Description
plaintext string No Data that was signed, base64-encoded.
signature string No Signature or MAC to check, base64-encoded.

Volume

Property Type Required Description
attached_alloc_id string No Always null. Deprecated: volumes are no longer attached to Nomad allocations.
attached_machine_id string No ID of the Machine the volume is attached to, or null if it is not attached.
auto_backup_enabled boolean No Whether daily automatic snapshots are taken.
block_size integer No Size of a filesystem block, in bytes. See blocks.
blocks integer No 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 No Number of filesystem blocks available to unprivileged users. See blocks.
blocks_free integer No Number of free filesystem blocks, including blocks reserved for the root user. See blocks.
bytes_total integer No Size of the volume, in bytes. 0 if the host could not be reached or with summary=true.
bytes_used integer No 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 No When the volume was created.
encrypted boolean No Whether the volume is encrypted at rest.
fstype string No Filesystem the volume was formatted with: ext4, or raw for an unformatted block device.
host_features string[] No Features of the volume's host. Only returned when the request sets the fly-include-host-features: true header.
host_status string No 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. Enum: ok, unknown, unreachable
id string No Unique ID of the volume, such as vol_1234567890abcdef.
name string No Name of the volume. Several volumes of an app can share a name.
region string No Code of the region the volume is in.
required_host_features string[] No Host features the volume's host was required to have; see compute.required_host_features in the create request.
size_gb integer No Size of the volume, in GiB.
snapshot_retention integer No Number of days snapshots of the volume are kept.
state string No State of the volume, such as creating, created, extending, restoring, hydrating, scheduling_destroy, pending_destroy, destroying, destroyed, or failed.
type string No Kind of volume: local for regular volumes, or cache for volumes that hold disposable data and support neither snapshots nor restores. Enum: local, cache
zone string No Identifies the host the volume is on. Volumes with different zones are on different hosts.

VolumeSnapshot

Property Type Required Description
created_at string No When the snapshot finished, in RFC 3339 format. The zero time (0001-01-01T00:00:00Z) while the snapshot is in progress.
digest string No Content digest of the snapshot. Empty while the snapshot is in progress.
id string No Unique ID of the snapshot. Pass it as snapshot_id when creating a volume to restore it.
retention_days integer No Number of days the snapshot is kept after it was created. Omitted while the snapshot is in progress.
size integer No Size of the stored snapshot, in bytes. 0 while the snapshot is in progress.
status string No created for completed snapshots; other values while the snapshot is in progress.
volume_size integer No Size of the volume the snapshot was taken of, in bytes.

WaitMachineResponse

Property Type Required Description
event_id string No ID of the event that moved the Machine into state. Pass it as from_event_id to wait for a later state change.
ok boolean No Always true.
state string No The state the Machine reached, one of the requested states.
version string No ID of the Machine version that reached state.