fly-io Apps API

openapi: 3.2.0
info:
  title: Machines Apps API
  description: This site hosts documentation generated from the Fly.io Machines API OpenAPI specification. Visit our complete Machines API docs for how to get started, more information about each endpoint, parameter descriptions, and examples.
  contact: {}
  license:
    name: Apache 2.0
    url: http://www.apache.org/licenses/LICENSE-2.0.html
  version: '1.0'
servers:
- url: https://api.machines.dev
security:
- FlyBearerAuth: []
tags:
- name: Apps
  description: This site hosts documentation generated from the Fly.io Machines API OpenAPI specification. Visit our complete Machines API docs for details about using the Apps resource.
paths:
  /v1/apps:
    get:
      tags:
      - Apps
      summary: List Apps
      description: List all apps with the ability to filter by organization slug.
      operationId: Apps_list
      parameters:
      - name: org_slug
        in: query
        description: The org slug, or 'personal', to filter apps
        required: true
        schema:
          type: string
      - name: app_role
        in: query
        description: Filter apps by role
        schema:
          type: string
      - name: limit
        in: query
        description: The number of apps to fetch (must be between 1 and 5000). Providing a limit enables pagination. Without it, all apps are returned in one response.
        schema:
          type: integer
      - name: cursor
        in: query
        description: Value of next_cursor from the previous page. Requires limit. Later pages only include apps that existed when the first page was requested. Apps created in the seconds before the first page was requested may be missing. Cursors expire 30 minutes after the first page was requested.
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListAppsResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    post:
      tags:
      - Apps
      summary: Create App
      description: Create an app with the specified details in the request body.
      operationId: Apps_create
      requestBody:
        description: App body
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateAppRequest'
        required: true
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateAppResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Rejected by validation. status is name_taken when the app name is already in use.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      x-codegen-request-body-name: request
  /v1/apps/{app_name}:
    get:
      tags:
      - Apps
      summary: Get App
      description: Retrieve details about a specific app by its name.
      operationId: Apps_show
      parameters:
      - name: app_name
        in: path
        description: Fly App Name
        required: true
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/App'
    delete:
      tags:
      - Apps
      summary: Destroy App
      description: Delete an app by its name.
      operationId: Apps_delete
      parameters:
      - name: app_name
        in: path
        description: Fly App Name
        required: true
        schema:
          type: string
      responses:
        '202':
          description: Accepted
          content: {}
  /v1/apps/{app_name}/deploy_token:
    post:
      tags:
      - Apps
      summary: Create App deploy token
      operationId: App_create_deploy_token
      parameters:
      - name: app_name
        in: path
        description: Fly App Name
        required: true
        schema:
          type: string
      requestBody:
        description: Request body
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateAppDeployTokenRequest'
        required: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateAppDeployTokenResponse'
      x-codegen-request-body-name: request
  /v1/apps/{app_name}/ip_assignments:
    get:
      tags:
      - Apps
      summary: List IP assignments for app
      operationId: App_IPAssignments_list
      parameters:
      - name: app_name
        in: path
        description: Fly App Name
        required: true
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/listIPAssignmentsResponse'
    post:
      tags:
      - Apps
      summary: Assign new IP address to app
      operationId: App_IPAssignments_create
      parameters:
      - name: app_name
        in: path
        description: Fly App Name
        required: true
        schema:
          type: string
      requestBody:
        description: Assign IP request
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/assignIPRequest'
        required: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AssignIPResponse'
      x-codegen-request-body-name: request
  /v1/apps/{app_name}/ip_assignments/{ip}:
    delete:
      tags:
      - Apps
      summary: Remove IP assignment from app
      operationId: App_IPAssignments_delete
      parameters:
      - name: app_name
        in: path
        description: Fly App Name
        required: true
        schema:
          type: string
      - name: ip
        in: path
        description: IP address
        required: true
        schema:
          type: string
      responses:
        '204':
          description: No Content
          content: {}
components:
  schemas:
    App:
      type: object
      properties:
        id:
          type: string
        internal_numeric_id:
          type: integer
        machine_count:
          type: integer
        name:
          type: string
        network:
          type: string
        network_cidr:
          type: string
        organization:
          $ref: '#/components/schemas/AppOrganizationInfo'
        status:
          type: string
        volume_count:
          type: integer
    IPAssignmentType:
      type: string
      description: Type of IP address to allocate. "egress-pair" allocates both v4 and v6 egress IP addresses (recommended when using egress IPs).
      enum:
      - v4
      - v6
      - shared_v4
      - private_v6
      - egress_v4
      - egress_v6
      - egress_pair
      x-enum-varnames:
      - IPAssignmentType_v4
      - IPAssignmentType_v6
      - IPAssignmentType_shared_v4
      - IPAssignmentType_private_v6
      - IPAssignmentType_egress_v4
      - IPAssignmentType_egress_v6
      - IPAssignmentType_egress_pair
    IPAssignmentNetwork:
      type: object
      properties:
        name:
          type: string
          description: Network name; empty for the organization's default network.
        org_slug:
          type: string
      description: The 6PN network a Flycast (private_v6) address belongs to. Null for all other IP types.
    listIPAssignmentsResponse:
      type: object
      properties:
        ips:
          type: array
          items:
            $ref: '#/components/schemas/IPAssignment'
    CreateAppRequest:
      type: object
      properties:
        enable_subdomains:
          type: boolean
        idempotency_key:
          type: string
          description: '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:
          type: string
        network:
          type: string
        org_slug:
          type: string
    assignIPRequest:
      type: object
      properties:
        network:
          type: string
        org_slug:
          type: string
        region:
          type: string
        service_name:
          type: string
        type:
          $ref: '#/components/schemas/IPAssignmentType'
    main.statusCode:
      type: string
      enum:
      - unknown
      - insufficient_capacity
      - volume_placement_capacity
      - name_taken
      x-enum-varnames:
      - unknown
      - capacityErr
      - volumePlacementCapacityErr
      - nameTakenErr
    CreateAppDeployTokenResponse:
      type: object
      properties:
        token:
          type: string
    CreateAppResponse:
      type: object
      properties:
        created_at:
          type: integer
        id:
          type: string
    ListAppsResponse:
      type: object
      properties:
        apps:
          type: array
          items:
            $ref: '#/components/schemas/App'
        next_cursor:
          type: string
          description: 'Pagination cursor for the next page. Absent when no more apps remain.

            Cursors expire 30 minutes after the first page was requested.'
        total_apps:
          type: integer
          description: 'The number of apps matching the request, across all pages. When

            paginating, it is counted once when the first page is requested and not

            updated afterwards, so it may differ slightly from the number of apps

            returned: it excludes apps created later and includes apps deleted while

            paginating. Apps created in the seconds before the first page may also be

            counted but missing from the pages.'
    IPAssignment:
      type: object
      properties:
        created_at:
          type: string
        egress:
          type: boolean
        ip:
          type: string
        network:
          $ref: '#/components/schemas/IPAssignmentNetwork'
        region:
          type: string
        service_name:
          type: string
        shared:
          type: boolean
    CreateAppDeployTokenRequest:
      type: object
      properties:
        expiry:
          type: string
    ErrorResponse:
      type: object
      properties:
        details:
          type: object
          description: Deprecated
        error:
          type: string
        status:
          $ref: '#/components/schemas/main.statusCode'
    AppOrganizationInfo:
      type: object
      properties:
        internal_numeric_id:
          type: integer
        name:
          type: string
        slug:
          type: string
    IPPair:
      type: object
      properties:
        v4:
          type: string
        v6:
          type: string
    AssignIPResponse:
      type: object
      properties:
        created_at:
          type: string
        egress:
          type: boolean
        ip:
          type: string
        ip_pair:
          type: object
          description: ip_pair is returned when "egress-pair" IP type is requested; in this case, ip is null.
          allOf:
          - $ref: '#/components/schemas/IPPair'
        network:
          $ref: '#/components/schemas/IPAssignmentNetwork'
        region:
          type: string
        service_name:
          type: string
        shared:
          type: boolean
  securitySchemes:
    FlyBearerAuth:
      type: http
      scheme: bearer
      description: 'A Fly API token with access to the requested organization or resource. Send it as `Authorization: Bearer <Fly API token>`.'
externalDocs:
  url: https://fly.io/docs/machines/working-with-machines/
x-original-swagger-version: '2.0'
x-provenance:
  method: harvested
  publisher: Fly Io
  source: https://fly.io/openapi.json
  note: split by refine-openapis from the provider's own published document, verified by fetch (openapi/_original/*.fetch.json);
    stamped by stamp-openapi-provenance.py (roadmap#793)