openapi: 3.1.0
info:
  title: Longhorn Manager BackingImages Nodes 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/
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: 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.
paths:
  /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'
components:
  responses:
    NotFound:
      description: The requested resource was not found.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/APIError'
    Unauthorized:
      description: Authentication credentials are missing or invalid.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/APIError'
    BadRequest:
      description: The request was malformed or contained invalid parameters.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/APIError'
  schemas:
    NodeCollection:
      type: object
      description: A collection of Longhorn node resources.
      properties:
        data:
          type: array
          description: List of node resources.
          items:
            $ref: '#/components/schemas/Node'
    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
    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.
    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
    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
    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
  parameters:
    nodeId:
      name: nodeId
      in: path
      required: true
      description: Identifier of the Longhorn node (typically the Kubernetes node name).
      schema:
        type: string
  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/