openapi: 3.1.0
info:
  title: Longhorn Manager API
  description: >-
    The Longhorn Manager REST API provides programmatic access to all Longhorn
    storage management operations. The API follows the Rancher REST API
    specification and is served by the Longhorn Manager service, typically
    accessible within a Kubernetes cluster at port 9500 or via the
    longhorn-backend service. It provides full lifecycle management for volumes,
    snapshots, backups, nodes, disks, engine images, recurring jobs, and system
    settings. The API is used by the Longhorn UI and can be accessed directly
    for automation and integration. The schema is discoverable at /v1/schemas.
  version: '1.11'
  contact:
    name: Longhorn Community
    url: https://longhorn.io/community/
externalDocs:
  description: Longhorn Documentation
  url: https://longhorn.io/docs/
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.
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.
  - name: Backups
    description: >-
      Backup operations for storing volume snapshots to external storage targets
      such as S3-compatible storage or NFS. Backups can be restored to new
      volumes for disaster recovery.
  - name: EngineImages
    description: >-
      Engine image management for the Longhorn storage engine. Engine images
      are OCI images containing the Longhorn engine binary and are used to
      upgrade or manage storage engine versions.
  - name: Nodes
    description: >-
      Node management for the Longhorn storage cluster including listing nodes,
      updating disk configurations, enabling or disabling scheduling, and
      managing node tags for workload placement.
  - name: RecurringJobs
    description: >-
      Recurring job management for scheduling automated snapshot and backup
      operations on a cron-based schedule. Recurring jobs can be applied to
      individual volumes or all volumes via groups.
  - name: Settings
    description: >-
      System-wide Longhorn settings management including backup targets,
      replica counts, node scheduling policies, data locality settings,
      and storage over-provisioning configuration.
  - name: Snapshots
    description: >-
      Snapshot operations for volumes including creating, listing, deleting,
      reverting to, and purging snapshots. Snapshots capture the state of a
      volume at a point in time and can be used as the basis for backups.
  - name: SystemBackups
    description: >-
      System-level backup and restore operations for the entire Longhorn
      configuration including all volumes, settings, and resource definitions.
  - name: Volumes
    description: >-
      Volume lifecycle management including creating, attaching, detaching,
      expanding, and deleting volumes. Also includes volume actions such as
      activating, canceling expansion, and managing replicas.
security:
  - bearerAuth: []
paths:
  /v1/volumes:
    get:
      operationId: listVolumes
      summary: Longhorn List volumes
      description: >-
        Returns a list of all Longhorn volumes in the cluster. Each volume
        entry includes its name, size, replication configuration, state,
        access mode, attached node, snapshot count, and associated recurring jobs.
      tags:
        - Volumes
      responses:
        '200':
          description: Volume list retrieved successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VolumeCollection'
        '401':
          $ref: '#/components/responses/Unauthorized'
    post:
      operationId: createVolume
      summary: Longhorn Create a volume
      description: >-
        Creates a new Longhorn volume with the specified configuration. The
        volume will be created in a detached state. It must be attached to a
        node before data can be written. Longhorn creates the specified number
        of replicas distributed across available nodes.
      tags:
        - Volumes
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/VolumeCreateInput'
      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/volumes/{volumeName}:
    get:
      operationId: getVolume
      summary: Longhorn Get a volume
      description: >-
        Returns detailed information about a specific volume including its
        state, replicas, engine, size, access mode, recurring jobs, and
        current operation status.
      tags:
        - Volumes
      parameters:
        - $ref: '#/components/parameters/volumeName'
      responses:
        '200':
          description: Volume details retrieved successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Volume'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    delete:
      operationId: deleteVolume
      summary: Longhorn Delete a volume
      description: >-
        Deletes a Longhorn volume and all of its replicas. The volume must be
        in a detached state before it can be deleted. All snapshots and backups
        associated with the volume will also be deleted.
      tags:
        - Volumes
      parameters:
        - $ref: '#/components/parameters/volumeName'
      responses:
        '204':
          description: Volume deleted successfully.
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /v1/volumes/{volumeName}?action=attach:
    post:
      operationId: attachVolume
      summary: Longhorn Attach a volume to a node
      description: >-
        Attaches a Longhorn volume to the specified node, making it available
        as a block device. The volume must be detached before it can be
        attached to a different node.
      tags:
        - Volumes
      parameters:
        - $ref: '#/components/parameters/volumeName'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/VolumeAttachInput'
      responses:
        '200':
          description: Volume attachment initiated.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Volume'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /v1/volumes/{volumeName}?action=detach:
    post:
      operationId: detachVolume
      summary: Longhorn Detach a volume from its node
      description: >-
        Detaches a Longhorn volume from the node it is currently attached to.
        The volume's data is preserved and it can be reattached to the same
        or a different node afterward.
      tags:
        - Volumes
      parameters:
        - $ref: '#/components/parameters/volumeName'
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              properties:
                hostId:
                  type: string
                  description: Node ID to detach from. If omitted, detaches from the current node.
      responses:
        '200':
          description: Volume detachment initiated.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Volume'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /v1/volumes/{volumeName}?action=expand:
    post:
      operationId: expandVolume
      summary: Longhorn Expand a volume
      description: >-
        Expands a Longhorn volume to a new, larger size. The size must be
        greater than the current volume size. Online expansion is supported
        for volumes attached to nodes; the file system may need to be
        resized separately after the volume is expanded.
      tags:
        - Volumes
      parameters:
        - $ref: '#/components/parameters/volumeName'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - size
              properties:
                size:
                  type: string
                  description: New size for the volume in bytes as a string, e.g. "10737418240" for 10 GiB.
      responses:
        '200':
          description: Volume expansion initiated.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Volume'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /v1/volumes/{volumeName}?action=snapshotCreate:
    post:
      operationId: createSnapshot
      summary: Longhorn Create a snapshot
      description: >-
        Creates a point-in-time snapshot of a Longhorn volume. The volume
        must be attached when the snapshot is created. Snapshots are stored
        in the volume's replica data directories and consume incremental
        space for changed blocks.
      tags:
        - Snapshots
      parameters:
        - $ref: '#/components/parameters/volumeName'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SnapshotCreateInput'
      responses:
        '200':
          description: Snapshot created successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Snapshot'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /v1/volumes/{volumeName}?action=snapshotList:
    get:
      operationId: listSnapshots
      summary: Longhorn List snapshots for a volume
      description: >-
        Returns a list of all snapshots for the specified volume. Each entry
        includes the snapshot name, creation time, size, parent, labels,
        and whether it has been removed or backed up.
      tags:
        - Snapshots
      parameters:
        - $ref: '#/components/parameters/volumeName'
      responses:
        '200':
          description: Snapshot list retrieved successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SnapshotListOutput'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /v1/volumes/{volumeName}?action=snapshotDelete:
    post:
      operationId: deleteSnapshot
      summary: Longhorn Delete a snapshot
      description: >-
        Marks a snapshot for deletion. The snapshot data is reclaimed
        asynchronously. Deleting a snapshot merges its changed blocks with
        the next snapshot in the chain. The volume must be attached.
      tags:
        - Snapshots
      parameters:
        - $ref: '#/components/parameters/volumeName'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - name
              properties:
                name:
                  type: string
                  description: Name of the snapshot to delete.
      responses:
        '200':
          description: Snapshot deletion initiated.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Snapshot'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /v1/volumes/{volumeName}?action=snapshotRevert:
    post:
      operationId: revertSnapshot
      summary: Longhorn Revert a volume to a snapshot
      description: >-
        Reverts the contents of a volume to the state captured in a specific
        snapshot. The volume must be detached before a revert operation.
        All data written after the snapshot was created will be lost.
      tags:
        - Snapshots
      parameters:
        - $ref: '#/components/parameters/volumeName'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - name
              properties:
                name:
                  type: string
                  description: Name of the snapshot to revert to.
      responses:
        '200':
          description: Volume revert initiated.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Snapshot'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /v1/volumes/{volumeName}?action=snapshotBackup:
    post:
      operationId: backupSnapshot
      summary: Longhorn Back up a snapshot
      description: >-
        Triggers a backup of a specific snapshot to the configured external
        backup target (S3 or NFS). The backup is asynchronous; monitor the
        backup resource to track progress.
      tags:
        - Backups
      parameters:
        - $ref: '#/components/parameters/volumeName'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BackupInput'
      responses:
        '200':
          description: Backup initiated.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Volume'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /v1/backupvolumes:
    get:
      operationId: listBackupVolumes
      summary: Longhorn List backup volumes
      description: >-
        Returns a list of all backup volumes in the configured backup target.
        A backup volume contains one or more backups of a Longhorn volume.
        This endpoint queries the external backup store.
      tags:
        - Backups
      responses:
        '200':
          description: Backup volume list retrieved successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BackupVolumeCollection'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /v1/backupvolumes/{backupVolumeName}:
    get:
      operationId: getBackupVolume
      summary: Longhorn Get a backup volume
      description: >-
        Returns details of a specific backup volume from the backup store
        including the list of available backups and their metadata.
      tags:
        - Backups
      parameters:
        - $ref: '#/components/parameters/backupVolumeName'
      responses:
        '200':
          description: Backup volume details retrieved successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BackupVolume'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /v1/backupvolumes/{backupVolumeName}/backups:
    get:
      operationId: listBackups
      summary: Longhorn List backups for a backup volume
      description: >-
        Returns a list of all backups stored for a specific backup volume.
        Each backup corresponds to a snapshot of the source Longhorn volume
        at the time the backup was created.
      tags:
        - Backups
      parameters:
        - $ref: '#/components/parameters/backupVolumeName'
      responses:
        '200':
          description: Backup list retrieved successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BackupCollection'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /v1/nodes:
    get:
      operationId: listNodes
      summary: Longhorn List nodes
      description: >-
        Returns a list of all nodes in the Longhorn storage cluster. Each
        node entry includes its scheduling eligibility, disk configurations,
        conditions, tags, and current state.
      tags:
        - Nodes
      responses:
        '200':
          description: Node list retrieved successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NodeCollection'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /v1/nodes/{nodeId}:
    get:
      operationId: getNode
      summary: Longhorn Get a node
      description: >-
        Returns detailed information about a specific node including all
        configured disks, their storage capacity, scheduling status, tags,
        and health conditions.
      tags:
        - Nodes
      parameters:
        - $ref: '#/components/parameters/nodeId'
      responses:
        '200':
          description: Node details retrieved successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Node'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    put:
      operationId: updateNode
      summary: Longhorn Update a node
      description: >-
        Updates a node's configuration including scheduling eligibility,
        disk configurations, eviction status, and node tags for workload
        placement affinity.
      tags:
        - Nodes
      parameters:
        - $ref: '#/components/parameters/nodeId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/NodeUpdateInput'
      responses:
        '200':
          description: Node updated successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Node'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /v1/engineimages:
    get:
      operationId: listEngineImages
      summary: Longhorn List engine images
      description: >-
        Returns a list of all Longhorn engine images installed in the cluster.
        Engine images contain the Longhorn storage engine binary and are used
        to manage volume upgrade and compatibility.
      tags:
        - EngineImages
      responses:
        '200':
          description: Engine image list retrieved successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EngineImageCollection'
        '401':
          $ref: '#/components/responses/Unauthorized'
    post:
      operationId: createEngineImage
      summary: Longhorn Create an engine image
      description: >-
        Deploys a new Longhorn engine image to the cluster by specifying
        an OCI image reference. Longhorn deploys the engine binary from this
        image to all nodes via a DaemonSet.
      tags:
        - EngineImages
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - image
              properties:
                image:
                  type: string
                  description: OCI image reference for the Longhorn engine image.
      responses:
        '200':
          description: Engine image deployment initiated.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EngineImage'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /v1/engineimages/{engineImageName}:
    get:
      operationId: getEngineImage
      summary: Longhorn Get an engine image
      description: >-
        Returns details of a specific engine image including its deployment
        state, CLI API version, controller API version, and which nodes
        have the image deployed.
      tags:
        - EngineImages
      parameters:
        - $ref: '#/components/parameters/engineImageName'
      responses:
        '200':
          description: Engine image details retrieved successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EngineImage'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    delete:
      operationId: deleteEngineImage
      summary: Longhorn Delete an engine image
      description: >-
        Removes an engine image from the cluster. The default engine image
        and images currently in use by volumes cannot be deleted.
      tags:
        - EngineImages
      parameters:
        - $ref: '#/components/parameters/engineImageName'
      responses:
        '204':
          description: Engine image deleted successfully.
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /v1/recurringjobs:
    get:
      operationId: listRecurringJobs
      summary: Longhorn List recurring jobs
      description: >-
        Returns a list of all recurring snapshot and backup jobs configured
        in Longhorn. Recurring jobs can be assigned to individual volumes or
        to groups that apply to multiple volumes.
      tags:
        - RecurringJobs
      responses:
        '200':
          description: Recurring job list retrieved successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RecurringJobCollection'
        '401':
          $ref: '#/components/responses/Unauthorized'
    post:
      operationId: createRecurringJob
      summary: Longhorn Create a recurring job
      description: >-
        Creates a new recurring job for automated snapshot or backup operations.
        The job runs on the specified cron schedule and applies to all volumes
        that have this job in their recurring job list or that belong to the
        job's group.
      tags:
        - RecurringJobs
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RecurringJobCreateInput'
      responses:
        '200':
          description: Recurring job created successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RecurringJob'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /v1/recurringjobs/{recurringJobName}:
    get:
      operationId: getRecurringJob
      summary: Longhorn Get a recurring job
      description: >-
        Returns details of a specific recurring job including its schedule,
        task type, retention policy, labels, and group assignments.
      tags:
        - RecurringJobs
      parameters:
        - $ref: '#/components/parameters/recurringJobName'
      responses:
        '200':
          description: Recurring job details retrieved successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RecurringJob'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    put:
      operationId: updateRecurringJob
      summary: Longhorn Update a recurring job
      description: >-
        Updates a recurring job's configuration including schedule, retention
        count, concurrency, and group assignments.
      tags:
        - RecurringJobs
      parameters:
        - $ref: '#/components/parameters/recurringJobName'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RecurringJobCreateInput'
      responses:
        '200':
          description: Recurring job updated successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RecurringJob'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
    delete:
      operationId: deleteRecurringJob
      summary: Longhorn Delete a recurring job
      description: >-
        Deletes a recurring job. Volumes assigned to this job will no longer
        have automated snapshots or backups created by this schedule.
      tags:
        - RecurringJobs
      parameters:
        - $ref: '#/components/parameters/recurringJobName'
      responses:
        '204':
          description: Recurring job deleted successfully.
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /v1/settings:
    get:
      operationId: listSettings
      summary: Longhorn List all settings
      description: >-
        Returns a list of all Longhorn system settings including backup target,
        default replica count, data locality, storage over-provisioning
        percentage, and all other configurable system parameters.
      tags:
        - Settings
      responses:
        '200':
          description: Settings list retrieved successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SettingCollection'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /v1/settings/{settingName}:
    get:
      operationId: getSetting
      summary: Longhorn Get a setting
      description: >-
        Returns the current value and metadata for a specific Longhorn setting.
        Settings include backup targets, replica counts, CPU and memory limits,
        node scheduling policies, and many other system parameters.
      tags:
        - Settings
      parameters:
        - $ref: '#/components/parameters/settingName'
      responses:
        '200':
          description: Setting retrieved successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Setting'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    put:
      operationId: updateSetting
      summary: Longhorn Update a setting
      description: >-
        Updates the value of a specific Longhorn system setting. Changes take
        effect immediately without requiring a restart.
      tags:
        - Settings
      parameters:
        - $ref: '#/components/parameters/settingName'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - value
              properties:
                value:
                  type: string
                  description: New value for the setting.
      responses:
        '200':
          description: Setting updated successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Setting'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /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'
  /v1/systembackups:
    get:
      operationId: listSystemBackups
      summary: Longhorn List system backups
      description: >-
        Returns a list of all system-level backups. System backups capture
        the entire Longhorn configuration including all CRDs, settings, and
        metadata to enable full cluster restoration.
      tags:
        - SystemBackups
      responses:
        '200':
          description: System backup list retrieved successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SystemBackupCollection'
        '401':
          $ref: '#/components/responses/Unauthorized'
    post:
      operationId: createSystemBackup
      summary: Longhorn Create a system backup
      description: >-
        Creates a new system-level backup of the Longhorn configuration.
        The backup is stored in the configured backup target and can be used
        to restore the entire Longhorn installation.
      tags:
        - SystemBackups
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                  description: Optional name for the system backup.
      responses:
        '200':
          description: System backup initiated.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SystemBackup'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
components:
  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.
  parameters:
    volumeName:
      name: volumeName
      in: path
      required: true
      description: Name of the Longhorn volume.
      schema:
        type: string
    nodeId:
      name: nodeId
      in: path
      required: true
      description: Identifier of the Longhorn node (typically the Kubernetes node name).
      schema:
        type: string
    backupVolumeName:
      name: backupVolumeName
      in: path
      required: true
      description: Name of the backup volume in the backup store.
      schema:
        type: string
    engineImageName:
      name: engineImageName
      in: path
      required: true
      description: Name of the engine image resource.
      schema:
        type: string
    recurringJobName:
      name: recurringJobName
      in: path
      required: true
      description: Name of the recurring job.
      schema:
        type: string
    settingName:
      name: settingName
      in: path
      required: true
      description: Key name of the Longhorn setting.
      schema:
        type: string
  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'
    NotFound:
      description: The requested resource was not found.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/APIError'
  schemas:
    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.
    Volume:
      type: object
      description: >-
        A Longhorn volume representing a block storage device that can be
        attached to Kubernetes nodes. Longhorn creates a dedicated storage
        controller and the configured number of replicas across nodes.
      properties:
        id:
          type: string
          description: Unique name/identifier of the volume.
        name:
          type: string
          description: Name of the volume.
        size:
          type: string
          description: Size of the volume in bytes as a string.
        numberOfReplicas:
          type: integer
          description: Number of replicas maintained for this volume.
        state:
          type: string
          enum:
            - creating
            - attached
            - detached
            - attaching
            - detaching
            - deleting
          description: Current state of the volume.
        robustness:
          type: string
          enum:
            - healthy
            - degraded
            - faulted
            - unknown
          description: Health state of the volume based on replica status.
        frontend:
          type: string
          enum:
            - blockdev
            - iscsi
            - nvmf
          description: Frontend type used to expose the volume to workloads.
        accessMode:
          type: string
          enum:
            - rwo
            - rwx
          description: Volume access mode. rwo is ReadWriteOnce; rwx is ReadWriteMany.
        migratable:
          type: boolean
          description: Whether the volume can be migrated live between nodes.
        encrypted:
          type: boolean
          description: Whether the volume data is encrypted at rest.
        dataLocality:
          type: string
          enum:
            - disabled
            - best-effort
            - strict-local
          description: Data locality policy controlling replica placement relative to the attached node.
        snapshotDataIntegrity:
          type: string
          description: Setting for snapshot data integrity checking.
        replicaAutoBalance:
          type: string
          description: Auto-balance policy for replica placement.
        currentImage:
          type: string
          description: Engine image currently in use by this volume.
        baseImage:
          type: string
          description: Backing image used as the base for this volume, if any.
        conditions:
          type: object
          description: Health conditions for the volume.
          additionalProperties:
            type: object
        replicas:
          type: array
          description: List of replica instances for this volume.
          items:
            $ref: '#/components/schemas/Replica'
        recurringJobSelector:
          type: array
          description: Recurring jobs assigned to this volume.
          items:
            type: object
            properties:
              name:
                type: string
                description: Name of the recurring job.
              isGroup:
                type: boolean
                description: Whether this is a group reference.
        kubernetesStatus:
          type: object
          description: Kubernetes PVC/PV binding status for this volume.
    VolumeCollection:
      type: object
      description: A paginated collection of Volume resources.
      properties:
        type:
          type: string
          const: collection
          description: Collection type identifier.
        resourceType:
          type: string
          const: volume
          description: Resource type for items in this collection.
        data:
          type: array
          description: List of volume resources.
          items:
            $ref: '#/components/schemas/Volume'
    VolumeCreateInput:
      type: object
      description: Input for creating a new Longhorn volume.
      required:
        - name
        - size
      properties:
        name:
          type: string
          description: Unique name for the new volume.
          minLength: 1
          maxLength: 63
        size:
          type: string
          description: Size of the volume in bytes as a string, e.g. "10737418240" for 10 GiB.
        numberOfReplicas:
          type: integer
          minimum: 1
          description: Number of replicas to maintain. Defaults to the system default (typically 3).
        dataLocality:
          type: string
          enum:
            - disabled
            - best-effort
            - strict-local
          description: Data locality policy for replica placement.
        accessMode:
          type: string
          enum:
            - rwo
            - rwx
          description: Access mode for the volume.
        encrypted:
          type: boolean
          description: Whether to encrypt the volume data at rest.
        backingImage:
          type: string
          description: Name of a backing image to use as base data for this volume.
        nodeSelector:
          type: array
          description: Node tags to restrict which nodes host replicas.
          items:
            type: string
        diskSelector:
          type: array
          description: Disk tags to restrict which disks host replicas.
          items:
            type: string
        recurringJobSelector:
          type: array
          description: Recurring jobs to assign to this volume.
          items:
            type: object
            properties:
              name:
                type: string
                description: Name of the recurring job or group.
              isGroup:
                type: boolean
                description: Whether this references a group.
    VolumeAttachInput:
      type: object
      description: Input for attaching a volume to a node.
      required:
        - hostId
      properties:
        hostId:
          type: string
          description: Kubernetes node name to attach the volume to.
        disableFrontend:
          type: boolean
          description: Whether to attach without exposing a frontend device. Used for backup operations.
        attachedBy:
          type: string
          description: Identifier of the entity requesting the attachment.
    Replica:
      type: object
      description: A Longhorn replica instance storing a copy of volume data on a node.
      properties:
        name:
          type: string
          description: Unique name of the replica.
        hostId:
          type: string
          description: Node where this replica is located.
        diskID:
          type: string
          description: Disk on the node where this replica stores data.
        diskPath:
          type: string
          description: File system path on the disk for this replica's data.
        dataPath:
          type: string
          description: Full path to the replica data directory.
        mode:
          type: string
          enum:
            - RW
            - WO
            - ERR
          description: Replica mode. RW is read-write; WO is write-only during rebuild; ERR is error state.
        running:
          type: boolean
          description: Whether the replica process is currently running.
        failedAt:
          type: string
          description: Timestamp when the replica last failed, if applicable.
    Snapshot:
      type: object
      description: A point-in-time snapshot of a Longhorn volume.
      properties:
        id:
          type: string
          description: Snapshot identifier.
        name:
          type: string
          description: Name of the snapshot.
        created:
          type: string
          description: Timestamp when the snapshot was created.
        size:
          type: string
          description: Size of data stored in this snapshot in bytes.
        parent:
          type: string
          description: Name of the parent snapshot in the chain.
        children:
          type: object
          description: Map of child snapshot names.
        removed:
          type: boolean
          description: Whether this snapshot has been marked for removal.
        usercreated:
          type: boolean
          description: Whether this snapshot was manually created (vs. system-created).
        labels:
          type: object
          description: Labels attached to this snapshot.
          additionalProperties:
            type: string
    SnapshotListOutput:
      type: object
      description: Output from listing snapshots of a volume.
      properties:
        data:
          type: array
          description: List of snapshot objects.
          items:
            $ref: '#/components/schemas/Snapshot'
    SnapshotCreateInput:
      type: object
      description: Input for creating a volume snapshot.
      properties:
        name:
          type: string
          description: Optional explicit name for the snapshot. Generated if omitted.
        labels:
          type: object
          description: Labels to apply to the new snapshot.
          additionalProperties:
            type: string
    BackupInput:
      type: object
      description: Input for backing up a snapshot to external storage.
      required:
        - name
      properties:
        name:
          type: string
          description: Name of the snapshot to back up.
        labels:
          type: object
          description: Labels to apply to the backup.
          additionalProperties:
            type: string
    BackupVolume:
      type: object
      description: A backup volume in the external backup store corresponding to a Longhorn volume.
      properties:
        id:
          type: string
          description: Identifier of the backup volume, typically matching the source volume name.
        name:
          type: string
          description: Name of the backup volume.
        size:
          type: string
          description: Total size of all backups in this backup volume.
        created:
          type: string
          description: Timestamp of the first backup.
        lastBackupName:
          type: string
          description: Name of the most recent backup.
        lastBackupAt:
          type: string
          description: Timestamp of the most recent backup.
        backingImageName:
          type: string
          description: Name of the backing image used by the source volume, if any.
    BackupVolumeCollection:
      type: object
      description: A collection of backup volumes.
      properties:
        data:
          type: array
          description: List of backup volume resources.
          items:
            $ref: '#/components/schemas/BackupVolume'
    Backup:
      type: object
      description: A backup stored in the external backup target for a Longhorn volume snapshot.
      properties:
        id:
          type: string
          description: Unique identifier of the backup.
        name:
          type: string
          description: Name of the backup.
        snapshotName:
          type: string
          description: Name of the snapshot this backup was created from.
        snapshotCreated:
          type: string
          description: Timestamp when the source snapshot was created.
        created:
          type: string
          description: Timestamp when the backup was completed.
        size:
          type: string
          description: Size of the backup data in bytes.
        labels:
          type: object
          description: Labels associated with this backup.
          additionalProperties:
            type: string
        url:
          type: string
          description: URL of this backup in the backup store.
    BackupCollection:
      type: object
      description: A collection of backup resources.
      properties:
        data:
          type: array
          description: List of backup resources.
          items:
            $ref: '#/components/schemas/Backup'
    Node:
      type: object
      description: A Longhorn storage node with configured disks and scheduling settings.
      properties:
        id:
          type: string
          description: Node identifier, matching the Kubernetes node name.
        name:
          type: string
          description: Name of the node.
        allowScheduling:
          type: boolean
          description: Whether new replicas can be scheduled on this node.
        evictionRequested:
          type: boolean
          description: Whether replica eviction has been requested for this node.
        disks:
          type: object
          description: Map of disk configurations on this node keyed by disk name.
          additionalProperties:
            $ref: '#/components/schemas/DiskSpec'
        diskStatus:
          type: object
          description: Status of each disk on the node.
          additionalProperties:
            $ref: '#/components/schemas/DiskStatus'
        tags:
          type: array
          description: Tags applied to this node for workload placement affinity.
          items:
            type: string
        conditions:
          type: object
          description: Node health conditions.
          additionalProperties:
            type: object
    NodeCollection:
      type: object
      description: A collection of Longhorn node resources.
      properties:
        data:
          type: array
          description: List of node resources.
          items:
            $ref: '#/components/schemas/Node'
    NodeUpdateInput:
      type: object
      description: Input for updating a Longhorn node.
      properties:
        allowScheduling:
          type: boolean
          description: Whether to allow new replicas to be scheduled on this node.
        evictionRequested:
          type: boolean
          description: Whether to request eviction of all replicas from this node.
        disks:
          type: object
          description: Updated disk configurations for the node.
          additionalProperties:
            $ref: '#/components/schemas/DiskSpec'
        tags:
          type: array
          description: Updated list of node tags.
          items:
            type: string
    DiskSpec:
      type: object
      description: Configuration for a disk on a Longhorn node.
      properties:
        path:
          type: string
          description: File system path to the disk or directory used for Longhorn storage.
        allowScheduling:
          type: boolean
          description: Whether new replicas can be scheduled on this disk.
        evictionRequested:
          type: boolean
          description: Whether eviction of replicas from this disk has been requested.
        storageReserved:
          type: integer
          description: Amount of storage reserved on this disk in bytes, not available for Longhorn.
        tags:
          type: array
          description: Tags for this disk used in replica placement affinity.
          items:
            type: string
    DiskStatus:
      type: object
      description: Observed status of a disk on a Longhorn node.
      properties:
        storageAvailable:
          type: integer
          description: Available storage on this disk in bytes.
        storageMaximum:
          type: integer
          description: Total capacity of this disk in bytes.
        storageScheduled:
          type: integer
          description: Storage allocated to replicas on this disk in bytes.
        conditions:
          type: object
          description: Health conditions for this disk.
          additionalProperties:
            type: object
    EngineImage:
      type: object
      description: A Longhorn engine image providing the storage engine binary.
      properties:
        id:
          type: string
          description: Unique identifier for the engine image resource.
        name:
          type: string
          description: Name of the engine image resource.
        image:
          type: string
          description: OCI image reference for this engine image.
        state:
          type: string
          enum:
            - deploying
            - ready
            - incompatible
            - error
          description: Current deployment state of the engine image.
        default:
          type: boolean
          description: Whether this is the default engine image used for new volumes.
        cliAPIVersion:
          type: integer
          description: CLI API version supported by this engine image.
        cliAPIMinVersion:
          type: integer
          description: Minimum CLI API version supported by this engine image.
        controllerAPIVersion:
          type: integer
          description: Controller API version supported by this engine image.
        nodesDeployed:
          type: array
          description: List of nodes where this engine image is deployed.
          items:
            type: string
    EngineImageCollection:
      type: object
      description: A collection of engine image resources.
      properties:
        data:
          type: array
          description: List of engine image resources.
          items:
            $ref: '#/components/schemas/EngineImage'
    RecurringJob:
      type: object
      description: A Longhorn recurring job for automated snapshot and backup scheduling.
      properties:
        id:
          type: string
          description: Unique identifier of the recurring job.
        name:
          type: string
          description: Name of the recurring job.
        task:
          type: string
          enum:
            - snapshot
            - snapshot-force-create
            - snapshot-cleanup
            - snapshot-delete
            - backup
            - backup-force-create
            - filesystem-trim
          description: Type of task to perform when the job fires.
        cron:
          type: string
          description: Cron expression for the job schedule, e.g. "0 2 * * *" for 2am daily.
        retain:
          type: integer
          minimum: 0
          description: Number of snapshots or backups to retain. Older ones are deleted.
        concurrency:
          type: integer
          minimum: 1
          description: Maximum number of volumes processed simultaneously.
        labels:
          type: object
          description: Labels applied to snapshots or backups created by this job.
          additionalProperties:
            type: string
        groups:
          type: array
          description: Group names this recurring job belongs to.
          items:
            type: string
    RecurringJobCollection:
      type: object
      description: A collection of recurring job resources.
      properties:
        data:
          type: array
          description: List of recurring job resources.
          items:
            $ref: '#/components/schemas/RecurringJob'
    RecurringJobCreateInput:
      type: object
      description: Input for creating or updating a recurring job.
      required:
        - name
        - task
        - cron
        - retain
      properties:
        name:
          type: string
          description: Unique name for the recurring job.
        task:
          type: string
          enum:
            - snapshot
            - snapshot-force-create
            - snapshot-cleanup
            - snapshot-delete
            - backup
            - backup-force-create
            - filesystem-trim
          description: Type of task to perform.
        cron:
          type: string
          description: Cron expression for the schedule.
        retain:
          type: integer
          minimum: 0
          description: Number of items to retain.
        concurrency:
          type: integer
          minimum: 1
          description: Number of concurrent volumes to process.
        labels:
          type: object
          description: Labels to apply to created snapshots or backups.
          additionalProperties:
            type: string
        groups:
          type: array
          description: Group names for this job.
          items:
            type: string
    Setting:
      type: object
      description: A Longhorn system setting with its current value and metadata.
      properties:
        id:
          type: string
          description: Setting key identifier.
        name:
          type: string
          description: Display name of the setting.
        value:
          type: string
          description: Current value of the setting.
        definition:
          type: object
          description: Setting definition including description, type, and constraints.
          properties:
            description:
              type: string
              description: Human-readable description of the setting.
            type:
              type: string
              description: Data type of the setting value.
            required:
              type: boolean
              description: Whether this setting is required.
            readOnly:
              type: boolean
              description: Whether this setting is read-only.
            options:
              type: array
              description: Allowed values for enum-type settings.
              items:
                type: string
    SettingCollection:
      type: object
      description: A collection of Longhorn settings.
      properties:
        data:
          type: array
          description: List of setting resources.
          items:
            $ref: '#/components/schemas/Setting'
    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.
    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'
    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.
    SystemBackup:
      type: object
      description: A system-level backup of the entire Longhorn configuration.
      properties:
        id:
          type: string
          description: Unique identifier of the system backup.
        name:
          type: string
          description: Name of the system backup.
        state:
          type: string
          enum:
            - generating
            - uploading
            - ready
            - error
            - deleting
          description: Current state of the system backup.
        version:
          type: string
          description: Longhorn version at the time this backup was created.
        managerImage:
          type: string
          description: Longhorn Manager image used when this backup was created.
        createdAt:
          type: string
          description: Timestamp when the system backup was created.
    SystemBackupCollection:
      type: object
      description: A collection of system backup resources.
      properties:
        data:
          type: array
          description: List of system backup resources.
          items:
            $ref: '#/components/schemas/SystemBackup'