openapi: 3.1.0
info:
  title: Fly.io Extensions Apps Volumes 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: 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.
paths:
  /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'
components:
  schemas:
    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
    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.
    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.
    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).
  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'
  parameters:
    volumeId:
      name: volume_id
      in: path
      description: The unique identifier of the Fly Volume.
      required: true
      schema:
        type: string
    appName:
      name: app_name
      in: path
      description: The name of the Fly App.
      required: true
      schema:
        type: string
  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/