openapi: 3.1.0
info:
  title: Fly.io Machines API
  description: >-
    The Fly.io Machines API is a low-level REST interface for provisioning and
    managing Fly Machines, which are fast-booting virtual machines that run on
    Fly.io's global edge infrastructure. It provides endpoints for creating,
    starting, stopping, and destroying Machines, as well as managing Fly Apps,
    Fly Volumes, and TLS certificates. The API is accessible publicly at
    https://api.machines.dev or internally within the Fly.io private WireGuard
    network at http://_api.internal:4280. All requests require bearer token
    authentication using a Fly.io API token, which can be obtained via the
    flyctl CLI.
  version: 'v1'
  contact:
    name: Fly.io Support
    url: https://fly.io/docs/machines/api/
  termsOfService: https://fly.io/legal/terms-of-service/
externalDocs:
  description: Fly.io Machines API Documentation
  url: https://fly.io/docs/machines/api/
servers:
  - url: https://api.machines.dev
    description: Public Production Server
  - url: http://_api.internal:4280
    description: Internal WireGuard Network Server
tags:
  - name: Apps
    description: >-
      Operations for creating, listing, and deleting Fly Apps. Every Fly Machine
      belongs to a Fly App, which groups related Machines together.
  - 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.
  - name: Tokens
    description: >-
      Operations for requesting OpenID Connect (OIDC) tokens from third-party
      services, enabling Fly Machines to authenticate to external systems using
      workload identity.
  - name: Volumes
    description: >-
      Operations for managing persistent storage volumes that can be attached to
      Fly Machines. Volumes provide durable block storage that persists across
      Machine restarts.
security:
  - bearerAuth: []
paths:
  /v1/apps:
    get:
      operationId: listApps
      summary: List apps in an organization
      description: >-
        Returns a list of all Fly Apps belonging to the specified organization.
        Results include the app name, machine count, volume count, and network
        configuration for each app.
      tags:
        - Apps
      parameters:
        - $ref: '#/components/parameters/orgSlug'
      responses:
        '200':
          description: A list of apps in the organization.
          content:
            application/json:
              schema:
                type: object
                properties:
                  total_apps:
                    type: integer
                    description: Total number of apps in the organization.
                  apps:
                    type: array
                    description: Array of app objects.
                    items:
                      $ref: '#/components/schemas/App'
        '401':
          $ref: '#/components/responses/Unauthorized'
    post:
      operationId: createApp
      summary: Create a Fly App
      description: >-
        Creates a new Fly App under the specified organization. An app is a
        logical grouping of Fly Machines that share a name, network, and
        routing configuration. Machines must belong to an app before they
        can be created.
      tags:
        - Apps
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateAppRequest'
      responses:
        '201':
          description: App created successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/App'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /v1/apps/{app_name}:
    get:
      operationId: getApp
      summary: Get a Fly App
      description: >-
        Retrieves details about a specific Fly App by its name, including
        the app status, organization, and associated network configuration.
      tags:
        - Apps
      parameters:
        - $ref: '#/components/parameters/appName'
      responses:
        '200':
          description: App details.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/App'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    delete:
      operationId: deleteApp
      summary: Delete a Fly App
      description: >-
        Permanently deletes a Fly App and all of its associated Machines,
        volumes, and IP addresses. This operation is irreversible. Use the
        force query parameter to stop all running Machines before deletion.
      tags:
        - Apps
      parameters:
        - $ref: '#/components/parameters/appName'
        - name: force
          in: query
          description: >-
            When true, all running Machines in the app are stopped before
            deletion proceeds. Without this flag, deletion fails if any
            Machines are running.
          required: false
          schema:
            type: boolean
      responses:
        '202':
          description: App deletion accepted.
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /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'
  /v1/apps/{app_name}/volumes:
    get:
      operationId: listVolumes
      summary: List volumes in an app
      description: >-
        Returns a list of all Fly Volumes belonging to the specified app,
        including their size, region, encryption status, attachment state,
        and snapshot retention settings.
      tags:
        - Volumes
      parameters:
        - $ref: '#/components/parameters/appName'
      responses:
        '200':
          description: A list of volumes.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Volume'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    post:
      operationId: createVolume
      summary: Create a volume
      description: >-
        Creates a new Fly Volume in the specified app for use as persistent
        storage attached to a Fly Machine. Volumes are region-specific and
        are encrypted by default. Specify unique_zones_only to distribute
        redundant volumes across separate physical hardware for higher
        availability.
      tags:
        - Volumes
      parameters:
        - $ref: '#/components/parameters/appName'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateVolumeRequest'
      responses:
        '200':
          description: Volume created successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Volume'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /v1/apps/{app_name}/volumes/{volume_id}:
    get:
      operationId: getVolume
      summary: Get a volume
      description: >-
        Retrieves the current state and configuration of a specific Fly Volume
        by its ID, including size, region, filesystem type, encryption status,
        and attachment information.
      tags:
        - Volumes
      parameters:
        - $ref: '#/components/parameters/appName'
        - $ref: '#/components/parameters/volumeId'
      responses:
        '200':
          description: Volume details.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Volume'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    put:
      operationId: updateVolume
      summary: Update a volume
      description: >-
        Updates the configuration of an existing Fly Volume, such as adjusting
        the snapshot retention period. Volume size can only be increased via
        the extend endpoint; it cannot be reduced.
      tags:
        - Volumes
      parameters:
        - $ref: '#/components/parameters/appName'
        - $ref: '#/components/parameters/volumeId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                snapshot_retention:
                  type: integer
                  description: >-
                    Number of days to retain snapshots. Minimum 1, maximum 60.
                  minimum: 1
                  maximum: 60
      responses:
        '200':
          description: Volume updated successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Volume'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    delete:
      operationId: deleteVolume
      summary: Delete a volume
      description: >-
        Permanently deletes a Fly Volume. The volume must not be currently
        attached to a running Machine. Deleting a volume also removes all
        snapshots associated with it. This operation is irreversible.
      tags:
        - Volumes
      parameters:
        - $ref: '#/components/parameters/appName'
        - $ref: '#/components/parameters/volumeId'
      responses:
        '200':
          description: Volume deleted successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Volume'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /v1/apps/{app_name}/volumes/{volume_id}/extend:
    put:
      operationId: extendVolume
      summary: Extend a volume
      description: >-
        Increases the size of a Fly Volume without downtime or data loss.
        Volume size can only be increased; shrinking a volume is not supported.
        The Machine attached to the volume may need to be restarted for the
        operating system to recognize the additional space.
      tags:
        - Volumes
      parameters:
        - $ref: '#/components/parameters/appName'
        - $ref: '#/components/parameters/volumeId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - size_gb
              properties:
                size_gb:
                  type: integer
                  description: >-
                    The new size of the volume in gigabytes. Must be larger
                    than the current size.
                  minimum: 1
      responses:
        '200':
          description: Volume extended successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Volume'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /v1/apps/{app_name}/volumes/{volume_id}/snapshots:
    get:
      operationId: listVolumeSnapshots
      summary: List volume snapshots
      description: >-
        Returns a list of all snapshots for a specific Fly Volume. Snapshots
        are created automatically on a daily schedule and can also be created
        on-demand. They are retained according to the volume's snapshot
        retention setting.
      tags:
        - Volumes
      parameters:
        - $ref: '#/components/parameters/appName'
        - $ref: '#/components/parameters/volumeId'
      responses:
        '200':
          description: A list of volume snapshots.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/VolumeSnapshot'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    post:
      operationId: createVolumeSnapshot
      summary: Create a volume snapshot
      description: >-
        Creates an on-demand snapshot of a Fly Volume. Snapshots capture the
        current state of the volume and can be used to restore data or create
        new volumes from a known-good state.
      tags:
        - Volumes
      parameters:
        - $ref: '#/components/parameters/appName'
        - $ref: '#/components/parameters/volumeId'
      responses:
        '200':
          description: Snapshot creation initiated.
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /v1/tokens/oidc:
    post:
      operationId: getOidcToken
      summary: Get an OIDC token
      description: >-
        Requests an OpenID Connect (OIDC) token for the calling Fly Machine.
        The token can be used to authenticate to third-party services that
        support OIDC workload identity, such as AWS, GCP, or Vault. The
        optional aud field controls the audience claim embedded in the JWT.
      tags:
        - Tokens
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              properties:
                aud:
                  type: string
                  description: >-
                    The audience claim for the OIDC token. Specifies the
                    recipient service that will accept this token, such as
                    https://fly.io/my-org-slug.
                  example: https://fly.io/my-org-slug
      responses:
        '200':
          description: OIDC token as a raw JWT string.
          content:
            application/json:
              schema:
                type: string
                description: A signed JWT OIDC token.
        '401':
          $ref: '#/components/responses/Unauthorized'
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: >-
        Fly.io API token obtained via the flyctl CLI using `flyctl auth token`.
        Include it in all requests as: Authorization: Bearer <fly_api_token>.
  parameters:
    appName:
      name: app_name
      in: path
      description: The name of the Fly App.
      required: true
      schema:
        type: string
    machineId:
      name: machine_id
      in: path
      description: The unique identifier of the Fly Machine.
      required: true
      schema:
        type: string
    volumeId:
      name: volume_id
      in: path
      description: The unique identifier of the Fly Volume.
      required: true
      schema:
        type: string
    metadataKey:
      name: key
      in: path
      description: The metadata key to get, set, or delete.
      required: true
      schema:
        type: string
    orgSlug:
      name: org_slug
      in: query
      description: The organization slug to filter apps by.
      required: true
      schema:
        type: string
  responses:
    BadRequest:
      description: Bad request due to invalid parameters or request body.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    Unauthorized:
      description: Missing or invalid API token.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    NotFound:
      description: The requested resource was not found.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
  schemas:
    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.
    App:
      type: object
      description: A Fly App, which is a logical grouping of related Fly Machines.
      properties:
        id:
          type: string
          description: Unique identifier for the app.
        name:
          type: string
          description: The app name, used in routing and DNS.
        status:
          type: string
          description: Current status of the app (e.g., running, suspended).
        machine_count:
          type: integer
          description: Number of Machines currently in the app.
        volume_count:
          type: integer
          description: Number of Volumes currently in the app.
        network:
          type: string
          description: The private network name this app is attached to.
        organization:
          $ref: '#/components/schemas/Organization'
    Organization:
      type: object
      description: A Fly.io organization that owns apps and resources.
      properties:
        name:
          type: string
          description: The organization name.
        slug:
          type: string
          description: The organization's URL-safe identifier slug.
    CreateAppRequest:
      type: object
      description: Request body for creating a new Fly App.
      required:
        - app_name
        - org_slug
      properties:
        app_name:
          type: string
          description: The unique name for the new app.
        org_slug:
          type: string
          description: The slug of the organization that will own this app.
        enable_subdomains:
          type: boolean
          description: >-
            When true, enables wildcard subdomain routing for this app.
        network:
          type: string
          description: >-
            Name of the private WireGuard network to attach this app to.
            If omitted, the organization's default network is used.
    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'
    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
    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]
    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'
    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.
    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.
    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.
    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.
    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.
    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: [no, on-failure, always]
    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.
    Volume:
      type: object
      description: A Fly Volume providing persistent block storage for Fly Machines.
      properties:
        id:
          type: string
          description: Unique identifier for this volume.
        name:
          type: string
          description: Human-readable name for the volume.
        state:
          type: string
          description: Current state of the volume (e.g., created, hydrating, available).
        size_gb:
          type: integer
          description: Volume size in gigabytes.
        region:
          type: string
          description: The region where this volume is provisioned.
        zone:
          type: string
          description: The availability zone within the region.
        encrypted:
          type: boolean
          description: Whether the volume is encrypted at rest. Enabled by default.
        attached_machine_id:
          type: string
          description: The ID of the Machine this volume is currently attached to, if any.
        attached_alloc_id:
          type: string
          description: The allocation ID of the Machine this volume is attached to.
        filesystem_type:
          type: string
          description: The filesystem type of the volume (e.g., ext4).
        snapshot_retention:
          type: integer
          description: Number of days snapshots are retained. Defaults to 5.
          minimum: 1
          maximum: 60
        created_at:
          type: string
          format: date-time
          description: Timestamp when the volume was created.
    CreateVolumeRequest:
      type: object
      description: Request body for creating a new Fly Volume.
      required:
        - name
        - size_gb
        - region
      properties:
        name:
          type: string
          description: Human-readable name for the volume.
        size_gb:
          type: integer
          description: Size of the volume in gigabytes.
          minimum: 1
        region:
          type: string
          description: The region code where the volume should be created.
          example: iad
        encrypted:
          type: boolean
          description: Whether to encrypt the volume at rest. Defaults to true.
          default: true
        unique_zones_only:
          type: boolean
          description: >-
            When true, ensures this volume is placed in a separate availability
            zone from other volumes with the same name in the app.
        snapshot_id:
          type: string
          description: >-
            Restore the volume from this snapshot ID during creation.
        snapshot_retention:
          type: integer
          description: Number of days to retain snapshots. Defaults to 5.
          minimum: 1
          maximum: 60
    VolumeSnapshot:
      type: object
      description: A point-in-time snapshot of a Fly Volume.
      properties:
        id:
          type: string
          description: Unique identifier for this snapshot.
        size:
          type: integer
          description: Snapshot size in bytes.
        digest:
          type: string
          description: Content digest of the snapshot for integrity verification.
        created_at:
          type: string
          format: date-time
          description: Timestamp when the snapshot was created.
        status:
          type: string
          description: Status of the snapshot (e.g., created).