Longhorn BackingImages API

openapi: 3.2.0
info:
  title: Longhorn Manager Backing Images API
  description: The Longhorn Manager REST API provides programmatic access to all Longhorn storage management operations.
  version: '1.11'
  contact:
    name: Longhorn Community
    url: https://longhorn.io/community/
servers:
- url: http://{longhornManagerHost}:{longhornManagerPort}
  description: Longhorn Manager API server (in-cluster via service or port-forward)
  variables:
    longhornManagerHost:
      default: longhorn-backend
      description: Hostname or service name for the Longhorn Manager.
    longhornManagerPort:
      default: '9500'
      description: Port on which Longhorn Manager serves the API.
security:
- bearerAuth: []
tags:
- name: BackingImages
  description: Backing image management for volumes that use pre-populated disk images as their base data. Backing images are immutable and can be shared across multiple volumes in the same namespace.
paths:
  /v1/backingimages:
    get:
      operationId: listBackingImages
      summary: Longhorn List backing images
      description: Returns a list of all backing images available in the cluster. Backing images are pre-populated disk images used as the base for new volumes.
      tags:
      - BackingImages
      responses:
        '200':
          description: Backing image list retrieved successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BackingImageCollection'
        '401':
          $ref: '#/components/responses/Unauthorized'
    post:
      operationId: createBackingImage
      summary: Longhorn Create a backing image
      description: Creates a new backing image by uploading or downloading an image file. The backing image is distributed to all nodes that need it for volume creation.
      tags:
      - BackingImages
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BackingImageCreateInput'
      responses:
        '200':
          description: Backing image created successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BackingImage'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
components:
  schemas:
    BackingImageCreateInput:
      type: object
      description: Input for creating a new backing image.
      required:
      - name
      - sourceType
      properties:
        name:
          type: string
          description: Unique name for the backing image.
        sourceType:
          type: string
          enum:
          - download
          - upload
          - export-from-volume
          description: Source type for the backing image data.
        parameters:
          type: object
          description: Source-specific parameters, such as the download URL.
          additionalProperties:
            type: string
        checksum:
          type: string
          description: Expected SHA512 checksum for verifying the backing image data.
    BackingImage:
      type: object
      description: A Longhorn backing image providing pre-populated base data for volumes.
      properties:
        id:
          type: string
          description: Unique identifier of the backing image.
        name:
          type: string
          description: Name of the backing image.
        sourceType:
          type: string
          enum:
          - download
          - upload
          - export-from-volume
          - restore
          - clone
          description: How the backing image data was sourced.
        size:
          type: integer
          description: Size of the backing image in bytes.
        checksum:
          type: string
          description: SHA512 checksum of the backing image data for integrity verification.
    APIError:
      type: object
      description: API error response.
      properties:
        type:
          type: string
          description: Error type identifier.
        status:
          type: integer
          description: HTTP status code.
        code:
          type: string
          description: Machine-readable error code.
        message:
          type: string
          description: Human-readable error message.
    BackingImageCollection:
      type: object
      description: A collection of backing image resources.
      properties:
        data:
          type: array
          description: List of backing image resources.
          items:
            $ref: '#/components/schemas/BackingImage'
  responses:
    BadRequest:
      description: The request was malformed or contained invalid parameters.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/APIError'
    Unauthorized:
      description: Authentication credentials are missing or invalid.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/APIError'
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: Kubernetes service account token for authenticating with the Longhorn Manager API. Typically passed via the Kubernetes API proxy.
externalDocs:
  description: Longhorn Documentation
  url: https://longhorn.io/docs/