openapi: 3.1.0
info:
title: Fly.io Extensions Apps Machines API
description: The Fly.io Extensions API is a provider-facing HTTP interface that enables third-party services to integrate with the Fly.io platform as extension providers. When a Fly.io user provisions an extension via the flyctl CLI, Fly.io forwards the provisioning request to the provider's API with details about the requesting organization and user, and the provider responds with environment variable configuration that is attached to the target application. Providers must also support single sign-on login flows using OAuth, daily billing detail endpoints, and webhook delivery for resource lifecycle events. Extensions currently available through this program include Sentry, Supabase, Tigris object storage, Upstash Redis and Vector, and others.
version: '1.0'
contact:
name: Fly.io Extensions Program
url: https://fly.io/docs/reference/extensions_api/
termsOfService: https://fly.io/legal/terms-of-service/
servers:
- url: https://{provider_base_url}
description: Provider-hosted API server. Each extension provider hosts their own implementation of this API at a URL they register with Fly.io.
variables:
provider_base_url:
default: api.example.com
description: The base URL registered by the extension provider with Fly.io.
- url: https://api.fly.io
description: Fly.io platform server for OAuth and webhook endpoints.
security:
- flySharedSecret: []
tags:
- name: Machines
description: Core operations for creating, reading, updating, starting, stopping, suspending, and deleting Fly Machines. Machines are fast-booting virtual machines deployed on Fly.io's global edge infrastructure.
paths:
/v1/apps/{app_name}/machines:
get:
operationId: listMachines
summary: List machines in an app
description: Returns a list of all Fly Machines belonging to the specified app, including their current state, region, configuration, and private IP addresses.
tags:
- Machines
parameters:
- $ref: '#/components/parameters/appName'
responses:
'200':
description: A list of machines in the app.
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/Machine'
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
post:
operationId: createMachine
summary: Create a Fly Machine
description: Creates and optionally starts a new Fly Machine within the specified app. The only required configuration field is the container image path. Additional configuration controls compute resources, networking, environment variables, health checks, mounts, and restart policies. Machines are private by default; expose them publicly by allocating an IP address and configuring services with port handlers.
tags:
- Machines
parameters:
- $ref: '#/components/parameters/appName'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CreateMachineRequest'
responses:
'200':
description: Machine created successfully.
content:
application/json:
schema:
$ref: '#/components/schemas/Machine'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
/v1/apps/{app_name}/machines/{machine_id}:
get:
operationId: getMachine
summary: Get a Fly Machine
description: Retrieves the current state and full configuration of a specific Fly Machine by its ID, including its instance ID, private IP, region, and applied configuration object.
tags:
- Machines
parameters:
- $ref: '#/components/parameters/appName'
- $ref: '#/components/parameters/machineId'
responses:
'200':
description: Machine details.
content:
application/json:
schema:
$ref: '#/components/schemas/Machine'
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
post:
operationId: updateMachine
summary: Update a Fly Machine
description: Updates the configuration of an existing Fly Machine. The Machine is updated in place and a new instance_id is assigned upon successful update. The same configuration schema used for creation applies here.
tags:
- Machines
parameters:
- $ref: '#/components/parameters/appName'
- $ref: '#/components/parameters/machineId'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CreateMachineRequest'
responses:
'200':
description: Machine updated successfully.
content:
application/json:
schema:
$ref: '#/components/schemas/Machine'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
delete:
operationId: deleteMachine
summary: Delete a Fly Machine
description: Permanently destroys a Fly Machine. The Machine must be in a stopped or suspended state before it can be deleted. Once deleted, the Machine and its ephemeral disk are gone; only attached volumes persist.
tags:
- Machines
parameters:
- $ref: '#/components/parameters/appName'
- $ref: '#/components/parameters/machineId'
responses:
'200':
description: Machine deleted successfully.
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
/v1/apps/{app_name}/machines/{machine_id}/start:
post:
operationId: startMachine
summary: Start a Fly Machine
description: Starts a stopped or suspended Fly Machine. The Machine boots from its current configuration and transitions to the started state. This endpoint returns immediately; use the wait endpoint to block until the Machine reaches the started state.
tags:
- Machines
parameters:
- $ref: '#/components/parameters/appName'
- $ref: '#/components/parameters/machineId'
responses:
'200':
description: Machine start initiated.
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
/v1/apps/{app_name}/machines/{machine_id}/stop:
post:
operationId: stopMachine
summary: Stop a Fly Machine
description: Stops a running Fly Machine by sending a signal to its init process. The Machine transitions to the stopped state. By default, SIGINT is sent; use the signal and timeout fields to customize graceful shutdown behavior.
tags:
- Machines
parameters:
- $ref: '#/components/parameters/appName'
- $ref: '#/components/parameters/machineId'
requestBody:
required: false
content:
application/json:
schema:
type: object
properties:
signal:
type: string
description: Signal to send to the Machine's init process. Defaults to SIGINT.
example: SIGTERM
timeout:
type: integer
description: Seconds to wait for the Machine to stop gracefully before forcing termination.
example: 30
responses:
'200':
description: Machine stop initiated.
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
/v1/apps/{app_name}/machines/{machine_id}/suspend:
post:
operationId: suspendMachine
summary: Suspend a Fly Machine
description: Suspends a running Fly Machine by taking a memory snapshot and halting execution. Suspended Machines can be resumed quickly because they restore from the snapshot rather than booting from scratch. This enables very fast wake times for workloads that are idle.
tags:
- Machines
parameters:
- $ref: '#/components/parameters/appName'
- $ref: '#/components/parameters/machineId'
responses:
'200':
description: Machine suspension initiated.
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
/v1/apps/{app_name}/machines/{machine_id}/wait:
get:
operationId: waitForMachineState
summary: Wait for a Machine to reach a state
description: Blocks until the specified Fly Machine reaches the desired state, or until the timeout elapses. Use this endpoint after starting, stopping, or suspending a Machine to confirm the state transition has completed before proceeding.
tags:
- Machines
parameters:
- $ref: '#/components/parameters/appName'
- $ref: '#/components/parameters/machineId'
- name: state
in: query
description: The target Machine state to wait for. Valid values are started, stopped, suspended, and destroyed.
required: false
schema:
type: string
enum:
- started
- stopped
- suspended
- destroyed
- name: timeout
in: query
description: Maximum number of seconds to wait for the state transition. Defaults to 60 seconds.
required: false
schema:
type: integer
minimum: 1
maximum: 300
- name: instance_id
in: query
description: Wait for a specific Machine instance version to reach the target state. Use the instance_id from a Machine update response to confirm that particular deployment is live.
required: false
schema:
type: string
responses:
'200':
description: Machine reached the desired state.
'408':
description: Timeout elapsed before the Machine reached the desired state.
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
/v1/apps/{app_name}/machines/{machine_id}/cordon:
post:
operationId: cordonMachine
summary: Cordon a Fly Machine
description: Marks a Fly Machine as cordoned, which removes it from load balancer rotation so it stops receiving new traffic. Existing connections are not interrupted. Use this endpoint for blue-green deployments or when draining a Machine before maintenance.
tags:
- Machines
parameters:
- $ref: '#/components/parameters/appName'
- $ref: '#/components/parameters/machineId'
responses:
'200':
description: Machine cordoned successfully.
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
/v1/apps/{app_name}/machines/{machine_id}/uncordon:
post:
operationId: uncordonMachine
summary: Uncordon a Fly Machine
description: Restores a cordoned Fly Machine to the load balancer rotation, allowing it to receive new traffic again. Use this endpoint after maintenance or to complete a blue-green deployment cutover.
tags:
- Machines
parameters:
- $ref: '#/components/parameters/appName'
- $ref: '#/components/parameters/machineId'
responses:
'200':
description: Machine uncordoned successfully.
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
/v1/apps/{app_name}/machines/{machine_id}/metadata/{key}:
get:
operationId: getMachineMetadata
summary: Get a Machine metadata value
description: Retrieves the value of a specific metadata key from a Fly Machine. Machine metadata consists of arbitrary key-value string pairs that can be used for internal routing, cluster membership, or application configuration.
tags:
- Machines
parameters:
- $ref: '#/components/parameters/appName'
- $ref: '#/components/parameters/machineId'
- $ref: '#/components/parameters/metadataKey'
responses:
'200':
description: Metadata value.
content:
application/json:
schema:
type: string
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
post:
operationId: setMachineMetadata
summary: Set a Machine metadata value
description: Creates or updates a metadata key-value pair on a Fly Machine. Metadata can be used for service discovery, internal routing with fly-prefer-region headers, and cluster configuration.
tags:
- Machines
parameters:
- $ref: '#/components/parameters/appName'
- $ref: '#/components/parameters/machineId'
- $ref: '#/components/parameters/metadataKey'
requestBody:
required: true
content:
application/json:
schema:
type: string
description: The value to set for the metadata key.
responses:
'204':
description: Metadata set successfully.
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
delete:
operationId: deleteMachineMetadata
summary: Delete a Machine metadata value
description: Removes a specific metadata key-value pair from a Fly Machine. Once deleted, the key no longer appears in the Machine's metadata and cannot be used for routing or configuration until it is re-added.
tags:
- Machines
parameters:
- $ref: '#/components/parameters/appName'
- $ref: '#/components/parameters/machineId'
- $ref: '#/components/parameters/metadataKey'
responses:
'204':
description: Metadata deleted successfully.
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
components:
schemas:
MachinePort:
type: object
description: An external port mapping for a Machine service.
properties:
port:
type: integer
description: The external port number.
handlers:
type: array
description: Protocol handlers to apply to traffic on this port (e.g., http, tls).
items:
type: string
enum:
- http
- tls
- tcp
- proxy_proto
force_https:
type: boolean
description: When true, HTTP traffic is redirected to HTTPS.
MachineInit:
type: object
description: Startup process configuration for a Fly Machine.
properties:
exec:
type: array
description: Command to execute as the Machine's init process.
items:
type: string
entrypoint:
type: array
description: Override the container image's entrypoint.
items:
type: string
cmd:
type: array
description: Override the container image's default command.
items:
type: string
tty:
type: boolean
description: When true, allocates a pseudo-TTY for the Machine's init process.
MachineServiceConcurrency:
type: object
description: Concurrency-based load balancing configuration for a service.
properties:
type:
type: string
description: Concurrency metric type.
enum:
- connections
- requests
soft_limit:
type: integer
description: Soft connection/request limit. The load balancer deprioritizes this Machine above this threshold.
hard_limit:
type: integer
description: Hard connection/request limit. No new traffic is routed to this Machine above this threshold.
MachineRestart:
type: object
description: Restart policy configuration for a Fly Machine.
properties:
policy:
type: string
description: When to restart the Machine after it exits. no disables restarts; on-failure restarts only on non-zero exit codes; always restarts unconditionally.
enum:
- false
- on-failure
- always
ErrorResponse:
type: object
description: A standard error response returned by the API on failure.
properties:
error:
type: string
description: Human-readable error message describing what went wrong.
status:
type: integer
description: HTTP status code.
MachineService:
type: object
description: A network service definition for exposing a Machine to external traffic.
properties:
protocol:
type: string
description: Transport protocol for this service.
enum:
- tcp
- udp
internal_port:
type: integer
description: The port the application listens on inside the Machine.
ports:
type: array
description: List of external port mappings for this service.
items:
$ref: '#/components/schemas/MachinePort'
concurrency:
$ref: '#/components/schemas/MachineServiceConcurrency'
MachineConfig:
type: object
description: Configuration for a Fly Machine.
required:
- image
properties:
image:
type: string
description: The container registry path for the image that defines this Machine.
example: registry-1.docker.io/library/ubuntu:latest
guest:
$ref: '#/components/schemas/MachineGuest'
env:
type: object
description: Environment variables to inject into the Machine at runtime.
additionalProperties:
type: string
services:
type: array
description: Network service definitions for exposing this Machine externally.
items:
$ref: '#/components/schemas/MachineService'
checks:
type: object
description: Named health check definitions. Keys are check names; values are check configuration objects.
additionalProperties:
$ref: '#/components/schemas/MachineCheck'
mounts:
type: array
description: Persistent volume mount definitions.
items:
$ref: '#/components/schemas/MachineMount'
init:
$ref: '#/components/schemas/MachineInit'
restart:
$ref: '#/components/schemas/MachineRestart'
schedule:
type: string
description: Run this Machine on a recurring schedule. Valid values are hourly, daily, weekly, and monthly.
enum:
- hourly
- daily
- weekly
- monthly
auto_destroy:
type: boolean
description: When true, the Machine is automatically destroyed after it exits.
metadata:
type: object
description: Arbitrary key-value metadata for internal routing and configuration.
additionalProperties:
type: string
Machine:
type: object
description: A Fly Machine is a fast-booting virtual machine deployed on Fly.io's global edge infrastructure.
properties:
id:
type: string
description: Stable unique identifier for this Machine.
name:
type: string
description: Human-readable name for this Machine.
state:
type: string
description: Current lifecycle state of the Machine.
enum:
- started
- stopped
- suspended
- destroyed
- replacing
region:
type: string
description: The three-letter region code where this Machine is deployed.
example: iad
instance_id:
type: string
description: Version identifier for the current Machine configuration. Changes each time the Machine is updated.
private_ip:
type: string
description: The Machine's 6PN private IPv6 address on the Fly.io WireGuard network.
created_at:
type: string
format: date-time
description: Timestamp when the Machine was created.
updated_at:
type: string
format: date-time
description: Timestamp when the Machine was last updated.
config:
$ref: '#/components/schemas/MachineConfig'
CreateMachineRequest:
type: object
description: Request body for creating or updating a Fly Machine.
required:
- config
properties:
name:
type: string
description: Optional human-readable name for the Machine.
region:
type: string
description: The three-letter region code where the Machine should be deployed. If omitted, Fly.io chooses the nearest available region.
example: iad
config:
$ref: '#/components/schemas/MachineConfig'
skip_service_registration:
type: boolean
description: When true, the Machine is created without being added to the load balancer. Useful for blue-green deployments.
MachineMount:
type: object
description: A volume mount definition for a Fly Machine.
properties:
volume:
type: string
description: The ID of the Fly Volume to mount.
path:
type: string
description: Filesystem path inside the Machine where the volume is mounted.
size_gb:
type: integer
description: Size of the volume in gigabytes.
MachineGuest:
type: object
description: Compute resource specification for a Fly Machine.
properties:
cpus:
type: integer
description: Number of vCPU cores to allocate. Defaults to 1.
default: 1
memory_mb:
type: integer
description: Memory in megabytes, must be a multiple of 256. Defaults to 256.
default: 256
multipleOf: 256
cpu_kind:
type: string
description: Type of vCPU to use. shared provides burstable performance; performance provides dedicated cores.
enum:
- shared
- performance
MachineCheck:
type: object
description: A health check definition for a Fly Machine.
properties:
type:
type: string
description: Check protocol type.
enum:
- tcp
- http
port:
type: integer
description: Port to run the health check against.
interval:
type: string
description: How often to run the check (e.g., 10s, 1m).
timeout:
type: string
description: Maximum time to wait for the check to respond.
grace_period:
type: string
description: Time to wait after Machine start before running checks.
path:
type: string
description: HTTP path for http-type checks.
method:
type: string
description: HTTP method for http-type checks. Defaults to GET.
parameters:
machineId:
name: machine_id
in: path
description: The unique identifier of the Fly Machine.
required: true
schema:
type: string
appName:
name: app_name
in: path
description: The name of the Fly App.
required: true
schema:
type: string
metadataKey:
name: key
in: path
description: The metadata key to get, set, or delete.
required: true
schema:
type: string
responses:
NotFound:
description: The requested resource was not found.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
Unauthorized:
description: Missing or invalid API token.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
BadRequest:
description: Bad request due to invalid parameters or request body.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
securitySchemes:
flySharedSecret:
type: http
scheme: bearer
description: Shared secret provided by Fly.io to the extension provider. Fly.io includes this secret in an Authorization Bearer header on all requests to the provider's API for verification.
oauthBearerAuth:
type: http
scheme: bearer
description: Fly.io OAuth access token obtained from the token exchange endpoint.
webhookHmac:
type: apiKey
in: header
name: X-Fly-Signature
description: HMAC-SHA256 signature of the raw request body, computed using the webhook signing secret. Recipients must verify this signature before processing the payload.
externalDocs:
description: Fly.io Extensions API Documentation
url: https://fly.io/docs/reference/extensions_api/