Incus storage API

swagger: '2.0'
info:
  contact:
    email: lxc-devel@lists.linuxcontainers.org
    name: Incus upstream
    url: https://github.com/lxc/incus
  description: 'This is the REST API used by all Incus clients.

    Internal endpoints aren''t included in this documentation.


    The Incus API is available over both a local unix+http and remote https API.

    Authentication for local users relies on group membership and access to the unix socket.

    For remote users, the default authentication method is TLS client

    certificates.'
  license:
    name: Apache-2.0
    url: https://www.apache.org/licenses/LICENSE-2.0
  title: Incus external REST certificates storage API
  version: '1.0'
tags:
- name: storage
paths:
  /1.0/storage-pools:
    get:
      description: Returns a list of storage pools (URLs).
      operationId: storage_pools_get
      parameters:
      - description: Project name
        example: default
        in: query
        name: project
        type: string
      - description: Collection filter
        example: default
        in: query
        name: filter
        type: string
      produces:
      - application/json
      responses:
        '200':
          description: API endpoints
          schema:
            description: Sync response
            properties:
              metadata:
                description: List of endpoints
                example: "[\n  \"/1.0/storage-pools/local\",\n  \"/1.0/storage-pools/remote\"\n]"
                items:
                  type: string
                type: array
              status:
                description: Status description
                example: Success
                type: string
              status_code:
                description: Status code
                example: 200
                type: integer
              type:
                description: Response type
                example: sync
                type: string
            type: object
        '403':
          $ref: '#/responses/Forbidden'
        '500':
          $ref: '#/responses/InternalServerError'
      summary: Get the storage pools
      tags:
      - storage
    post:
      consumes:
      - application/json
      description: 'Creates a new storage pool.

        When clustered, storage pools require individual POST for each cluster member prior to a global POST.'
      operationId: storage_pools_post
      parameters:
      - description: Project name
        example: default
        in: query
        name: project
        type: string
      - description: Cluster member name
        example: server01
        in: query
        name: target
        type: string
      - description: Storage pool
        in: body
        name: storage
        required: true
        schema:
          $ref: '#/definitions/StoragePoolsPost'
      produces:
      - application/json
      responses:
        '200':
          $ref: '#/responses/EmptySyncResponse'
        '400':
          $ref: '#/responses/BadRequest'
        '403':
          $ref: '#/responses/Forbidden'
        '500':
          $ref: '#/responses/InternalServerError'
      summary: Add a storage pool
      tags:
      - storage
  /1.0/storage-pools/{name}/buckets/{bucketName}:
    delete:
      description: Removes the storage bucket.
      operationId: storage_pool_bucket_delete
      parameters:
      - description: Resource name
        in: path
        name: name
        required: true
        type: string
      - description: Storage bucket name
        in: path
        name: bucketName
        required: true
        type: string
      - description: Project name
        example: default
        in: query
        name: project
        type: string
      - description: Cluster member name
        example: server01
        in: query
        name: target
        type: string
      produces:
      - application/json
      responses:
        '200':
          $ref: '#/responses/EmptySyncResponse'
        '400':
          $ref: '#/responses/BadRequest'
        '403':
          $ref: '#/responses/Forbidden'
        '500':
          $ref: '#/responses/InternalServerError'
      summary: Delete the storage bucket
      tags:
      - storage
    patch:
      consumes:
      - application/json
      description: Updates a subset of the storage bucket configuration.
      operationId: storage_pool_bucket_patch
      parameters:
      - description: Resource name
        in: path
        name: name
        required: true
        type: string
      - description: Storage bucket name
        in: path
        name: bucketName
        required: true
        type: string
      - description: Project name
        example: default
        in: query
        name: project
        type: string
      - description: Cluster member name
        example: server01
        in: query
        name: target
        type: string
      - description: Storage bucket configuration
        in: body
        name: storage bucket
        required: true
        schema:
          $ref: '#/definitions/StorageBucketPut'
      produces:
      - application/json
      responses:
        '200':
          $ref: '#/responses/EmptySyncResponse'
        '400':
          $ref: '#/responses/BadRequest'
        '403':
          $ref: '#/responses/Forbidden'
        '412':
          $ref: '#/responses/PreconditionFailed'
        '500':
          $ref: '#/responses/InternalServerError'
      summary: Partially update the storage bucket.
      tags:
      - storage
    put:
      consumes:
      - application/json
      description: Updates the entire storage bucket configuration.
      operationId: storage_pool_bucket_put
      parameters:
      - description: Resource name
        in: path
        name: name
        required: true
        type: string
      - description: Storage bucket name
        in: path
        name: bucketName
        required: true
        type: string
      - description: Project name
        example: default
        in: query
        name: project
        type: string
      - description: Cluster member name
        example: server01
        in: query
        name: target
        type: string
      - description: Storage bucket configuration
        in: body
        name: storage bucket
        required: true
        schema:
          $ref: '#/definitions/StorageBucketPut'
      produces:
      - application/json
      responses:
        '200':
          $ref: '#/responses/EmptySyncResponse'
        '400':
          $ref: '#/responses/BadRequest'
        '403':
          $ref: '#/responses/Forbidden'
        '412':
          $ref: '#/responses/PreconditionFailed'
        '500':
          $ref: '#/responses/InternalServerError'
      summary: Update the storage bucket
      tags:
      - storage
  /1.0/storage-pools/{name}/buckets/{bucketName}/keys/{keyName}:
    delete:
      description: Removes the storage bucket key.
      operationId: storage_pool_bucket_key_delete
      parameters:
      - description: Resource name
        in: path
        name: name
        required: true
        type: string
      - description: Storage bucket name
        in: path
        name: bucketName
        required: true
        type: string
      - description: Storage bucket key name
        in: path
        name: keyName
        required: true
        type: string
      - description: Project name
        example: default
        in: query
        name: project
        type: string
      - description: Cluster member name
        example: server01
        in: query
        name: target
        type: string
      produces:
      - application/json
      responses:
        '200':
          $ref: '#/responses/EmptySyncResponse'
        '400':
          $ref: '#/responses/BadRequest'
        '403':
          $ref: '#/responses/Forbidden'
        '500':
          $ref: '#/responses/InternalServerError'
      summary: Delete the storage bucket key
      tags:
      - storage
    put:
      consumes:
      - application/json
      description: Updates the entire storage bucket key configuration.
      operationId: storage_pool_bucket_key_put
      parameters:
      - description: Resource name
        in: path
        name: name
        required: true
        type: string
      - description: Storage bucket name
        in: path
        name: bucketName
        required: true
        type: string
      - description: Storage bucket key name
        in: path
        name: keyName
        required: true
        type: string
      - description: Project name
        example: default
        in: query
        name: project
        type: string
      - description: Cluster member name
        example: server01
        in: query
        name: target
        type: string
      - description: Storage bucket key configuration
        in: body
        name: storage bucket
        required: true
        schema:
          $ref: '#/definitions/StorageBucketKeyPut'
      produces:
      - application/json
      responses:
        '200':
          $ref: '#/responses/EmptySyncResponse'
        '400':
          $ref: '#/responses/BadRequest'
        '403':
          $ref: '#/responses/Forbidden'
        '412':
          $ref: '#/responses/PreconditionFailed'
        '500':
          $ref: '#/responses/InternalServerError'
      summary: Update the storage bucket key
      tags:
      - storage
  /1.0/storage-pools/{name}/resources:
    get:
      description: Gets the usage information for the storage pool.
      operationId: storage_pool_resources
      parameters:
      - description: Resource name
        in: path
        name: name
        required: true
        type: string
      - description: Cluster member name
        example: server01
        in: query
        name: target
        type: string
      produces:
      - application/json
      responses:
        '200':
          description: Hardware resources
          schema:
            description: Sync response
            properties:
              metadata:
                $ref: '#/definitions/ResourcesStoragePool'
              status:
                description: Status description
                example: Success
                type: string
              status_code:
                description: Status code
                example: 200
                type: integer
              type:
                description: Response type
                example: sync
                type: string
            type: object
        '403':
          $ref: '#/responses/Forbidden'
        '500':
          $ref: '#/responses/InternalServerError'
      summary: Get storage pool resources information
      tags:
      - storage
  /1.0/storage-pools/{poolName}:
    delete:
      description: Removes the storage pool.
      operationId: storage_pools_delete
      parameters:
      - description: Storage pool name
        in: path
        name: poolName
        required: true
        type: string
      - description: Project name
        example: default
        in: query
        name: project
        type: string
      produces:
      - application/json
      responses:
        '200':
          $ref: '#/responses/EmptySyncResponse'
        '400':
          $ref: '#/responses/BadRequest'
        '403':
          $ref: '#/responses/Forbidden'
        '500':
          $ref: '#/responses/InternalServerError'
      summary: Delete the storage pool
      tags:
      - storage
    get:
      description: Gets a specific storage pool.
      operationId: storage_pool_get
      parameters:
      - description: Storage pool name
        in: path
        name: poolName
        required: true
        type: string
      - description: Project name
        example: default
        in: query
        name: project
        type: string
      - description: Cluster member name
        example: server01
        in: query
        name: target
        type: string
      produces:
      - application/json
      responses:
        '200':
          description: Storage pool
          schema:
            description: Sync response
            properties:
              metadata:
                $ref: '#/definitions/StoragePool'
              status:
                description: Status description
                example: Success
                type: string
              status_code:
                description: Status code
                example: 200
                type: integer
              type:
                description: Response type
                example: sync
                type: string
            type: object
        '403':
          $ref: '#/responses/Forbidden'
        '500':
          $ref: '#/responses/InternalServerError'
      summary: Get the storage pool
      tags:
      - storage
    patch:
      consumes:
      - application/json
      description: Updates a subset of the storage pool configuration.
      operationId: storage_pool_patch
      parameters:
      - description: Storage pool name
        in: path
        name: poolName
        required: true
        type: string
      - description: Project name
        example: default
        in: query
        name: project
        type: string
      - description: Cluster member name
        example: server01
        in: query
        name: target
        type: string
      - description: Storage pool configuration
        in: body
        name: storage pool
        required: true
        schema:
          $ref: '#/definitions/StoragePoolPut'
      produces:
      - application/json
      responses:
        '200':
          $ref: '#/responses/EmptySyncResponse'
        '400':
          $ref: '#/responses/BadRequest'
        '403':
          $ref: '#/responses/Forbidden'
        '412':
          $ref: '#/responses/PreconditionFailed'
        '500':
          $ref: '#/responses/InternalServerError'
      summary: Partially update the storage pool
      tags:
      - storage
    put:
      consumes:
      - application/json
      description: Updates the entire storage pool configuration.
      operationId: storage_pool_put
      parameters:
      - description: Storage pool name
        in: path
        name: poolName
        required: true
        type: string
      - description: Project name
        example: default
        in: query
        name: project
        type: string
      - description: Cluster member name
        example: server01
        in: query
        name: target
        type: string
      - description: Storage pool configuration
        in: body
        name: storage pool
        required: true
        schema:
          $ref: '#/definitions/StoragePoolPut'
      produces:
      - application/json
      responses:
        '200':
          $ref: '#/responses/EmptySyncResponse'
        '400':
          $ref: '#/responses/BadRequest'
        '403':
          $ref: '#/responses/Forbidden'
        '412':
          $ref: '#/responses/PreconditionFailed'
        '500':
          $ref: '#/responses/InternalServerError'
      summary: Update the storage pool
      tags:
      - storage
  /1.0/storage-pools/{poolName}/buckets:
    get:
      description: Returns a list of storage pool buckets (URLs).
      operationId: storage_pool_buckets_get
      parameters:
      - description: Storage pool name
        in: path
        name: poolName
        required: true
        type: string
      - description: Project name
        example: default
        in: query
        name: project
        type: string
      - description: Retrieve storage pool buckets from all projects
        example: true
        in: query
        name: all-projects
        type: boolean
      - description: Collection filter
        example: default
        in: query
        name: filter
        type: string
      produces:
      - application/json
      responses:
        '200':
          description: API endpoints
          schema:
            description: Sync response
            properties:
              metadata:
                description: List of endpoints
                example: "[\n  \"/1.0/storage-pools/default/buckets/foo\",\n  \"/1.0/storage-pools/default/buckets/bar\",\n]"
                items:
                  type: string
                type: array
              status:
                description: Status description
                example: Success
                type: string
              status_code:
                description: Status code
                example: 200
                type: integer
              type:
                description: Response type
                example: sync
                type: string
            type: object
        '403':
          $ref: '#/responses/Forbidden'
        '500':
          $ref: '#/responses/InternalServerError'
      summary: Get the storage pool buckets
      tags:
      - storage
    post:
      consumes:
      - application/json
      description: Creates a new storage pool bucket.
      operationId: storage_pool_bucket_post
      parameters:
      - description: Storage pool name
        in: path
        name: poolName
        required: true
        type: string
      - description: Project name
        example: default
        in: query
        name: project
        type: string
      - description: Bucket
        in: body
        name: bucket
        required: true
        schema:
          $ref: '#/definitions/StorageBucketsPost'
      produces:
      - application/json
      responses:
        '200':
          $ref: '#/definitions/StorageBucketKey'
        '400':
          $ref: '#/responses/BadRequest'
        '403':
          $ref: '#/responses/Forbidden'
        '500':
          $ref: '#/responses/InternalServerError'
      summary: Add a storage pool bucket.
      tags:
      - storage
  /1.0/storage-pools/{poolName}/buckets/{bucketName}:
    get:
      description: Gets a specific storage pool bucket.
      operationId: storage_pool_bucket_get
      parameters:
      - description: Storage pool name
        in: path
        name: poolName
        required: true
        type: string
      - description: Storage bucket name
        in: path
        name: bucketName
        required: true
        type: string
      - description: Project name
        example: default
        in: query
        name: project
        type: string
      produces:
      - application/json
      responses:
        '200':
          description: Storage pool bucket
          schema:
            description: Sync response
            properties:
              metadata:
                $ref: '#/definitions/StorageBucket'
              status:
                description: Status description
                example: Success
                type: string
              status_code:
                description: Status code
                example: 200
                type: integer
              type:
                description: Response type
                example: sync
                type: string
            type: object
        '403':
          $ref: '#/responses/Forbidden'
        '500':
          $ref: '#/responses/InternalServerError'
      summary: Get the storage pool bucket
      tags:
      - storage
  /1.0/storage-pools/{poolName}/buckets/{bucketName}/backups:
    get:
      description: Returns a list of storage bucket backups (URLs).
      operationId: storage_pool_buckets_backups_get
      parameters:
      - description: Storage pool name
        in: path
        name: poolName
        required: true
        type: string
      - description: Storage bucket name
        in: path
        name: bucketName
        required: true
        type: string
      - description: Project name
        example: default
        in: query
        name: project
        type: string
      - description: Cluster member name
        example: server01
        in: query
        name: target
        type: string
      produces:
      - application/json
      responses:
        '200':
          description: API endpoints
          schema:
            description: Sync response
            properties:
              metadata:
                description: List of endpoints
                example: "[\n  \"/1.0/storage-pools/local/buckets/foo/backups/backup0\",\n  \"/1.0/storage-pools/local/buckets/foo/backups/backup1\"\n]"
                items:
                  type: string
                type: array
              status:
                description: Status description
                example: Success
                type: string
              status_code:
                description: Status code
                example: 200
                type: integer
              type:
                description: Response type
                example: sync
                type: string
            type: object
        '403':
          $ref: '#/responses/Forbidden'
        '500':
          $ref: '#/responses/InternalServerError'
      summary: Get the storage bucket backups
      tags:
      - storage
    post:
      consumes:
      - application/json
      description: 'Creates a new storage bucket backup.


        If the `Accept` header is set to `application/octet-stream`, this directly streams the backup

        tarball to the client without any intermediate operation.'
      operationId: storage_pool_buckets_backups_post
      parameters:
      - description: Storage pool name
        in: path
        name: poolName
        required: true
        type: string
      - description: Storage bucket name
        in: path
        name: bucketName
        required: true
        type: string
      - description: Project name
        example: default
        in: query
        name: project
        type: string
      - description: Cluster member name
        example: server01
        in: query
        name: target
        type: string
      - description: Storage bucket backup
        in: body
        name: bucket
        required: true
        schema:
          $ref: '#/definitions/StorageBucketBackupsPost'
      produces:
      - application/json
      - application/octet-stream
      responses:
        '202':
          $ref: '#/responses/Operation'
        '400':
          $ref: '#/responses/BadRequest'
        '403':
          $ref: '#/responses/Forbidden'
        '500':
          $ref: '#/responses/InternalServerError'
      summary: Create a storage bucket backup
      tags:
      - storage
  /1.0/storage-pools/{poolName}/buckets/{bucketName}/backups/{backupName}:
    delete:
      consumes:
      - application/json
      description: Deletes a new storage bucket backup.
      operationId: storage_pool_buckets_backup_delete
      parameters:
      - description: Storage pool name
        in: path
        name: poolName
        required: true
        type: string
      - description: Storage bucket name
        in: path
        name: bucketName
        required: true
        type: string
      - description: Backup name
        in: path
        name: backupName
        required: true
        type: string
      - description: Project name
        example: default
        in: query
        name: project
        type: string
      - description: Cluster member name
        example: server01
        in: query
        name: target
        type: string
      produces:
      - application/json
      responses:
        '202':
          $ref: '#/responses/Operation'
        '400':
          $ref: '#/responses/BadRequest'
        '403':
          $ref: '#/responses/Forbidden'
        '500':
          $ref: '#/responses/InternalServerError'
      summary: Delete a storage bucket backup
      tags:
      - storage
    get:
      description: Gets a specific storage bucket backup.
      operationId: storage_pool_buckets_backup_get
      parameters:
      - description: Storage pool name
        in: path
        name: poolName
        required: true
        type: string
      - description: Storage bucket name
        in: path
        name: bucketName
        required: true
        type: string
      - description: Backup name
        in: path
        name: backupName
        required: true
        type: string
      - description: Project name
        example: default
        in: query
        name: project
        type: string
      - description: Cluster member name
        example: server01
        in: query
        name: target
        type: string
      produces:
      - application/json
      responses:
        '200':
          description: Storage bucket backup
          schema:
            description: Sync response
            properties:
              metadata:
                $ref: '#/definitions/StorageBucketBackup'
              status:
                description: Status description
                example: Success
                type: string
              status_code:
                description: Status code
                example: 200
                type: integer
              type:
                description: Response type
                example: sync
                type: string
            type: object
        '403':
          $ref: '#/responses/Forbidden'
        '500':
          $ref: '#/responses/InternalServerError'
      summary: Get the storage bucket backup
      tags:
      - storage
    post:
      consumes:
      - application/json
      description: Renames a storage bucket backup.
      operationId: storage_pool_buckets_backup_post
      parameters:
      - description: Storage pool name
        in: path
        name: poolName
        required: true
        type: string
      - description: Storage bucket name
        in: path
        name: bucketName
        required: true
        type: string
      - description: Backup name
        in: path
        name: backupName
        required: true
        type: string
      - description: Project name
        example: default
        in: query
        name: project
        type: string
      - description: Cluster member name
        example: server01
        in: query
        name: target
        type: string
      - description: Storage bucket backup
        in: body
        name: bucket rename
        required: true
        schema:
          $ref: '#/definitions/StorageBucketBackupPost'
      produces:
      - application/json
      responses:
        '202':
          $ref: '#/responses/Operation'
        '400':
          $ref: '#/responses/BadRequest'
        '403':
          $ref: '#/responses/Forbidden'
        '500':
          $ref: '#/responses/InternalServerError'
      summary: Rename a storage bucket backup
      tags:
      - storage
  /1.0/storage-pools/{poolName}/buckets/{bucketName}/backups/{backupName}/export:
    get:
      description: Download the raw backup file from the server.
      operationId: storage_pool_buckets_backup_export_get
      parameters:
      - description: Storage pool name
        in: path
        name: poolName
        required: true
        type: string
      - description: Storage bucket name
        in: path
        name: bucketName
        required: true
        type: string
      - description: Backup name
        in: path
        name: backupName
        required: true
        type: string
      - description: Project name
        example: default
        in: query
        name: project
        type: string
      - description: Cluster member name
        example: server01
        in: query
        name: target
        type: string
      produces:
      - application/octet-stream
      responses:
        '200':
          description: Raw backup data
        '403':
          $ref: '#/responses/Forbidden'
        '500':
          $ref: '#/responses/InternalServerError'
      summary: Get the raw backup file
      tags:
      - storage
  /1.0/storage-pools/{poolName}/buckets/{bucketName}/backups?recursion=1:
    get:
      description: Returns a list of storage bucket backups (structs).
      operationId: storage_pool_buckets_backups_get_recursion1
      parameters:
      - description: Storage pool name
        in: path
        name: poolName
        required: true
        type: string
      - description: Storage bucket name
        in: path
        name: bucketName
        required: true
        type: string
      - description: Project name
        example: default
        in: query
        name: project
        type: string
      - description: Cluster member name
        example: server01
        in: query
        name: target
        type: string
      produces:
      - application/json
      responses:
        '200':
          description: API endpoints
          schema:
            description: Sync response
            properties:
              metadata:
                description: List of storage bucket backups
                items:
                  $ref: '#/definitions/StorageBucketBackup'
                type: array
              status:
                description: Status description
                example: Success
                type: string
              status_code:
                description: Status code
                example: 200
                type: integer
              type:
                description: Response type
                example: sync
                type: string
            type: object
        '403':
          $ref: '#/responses/Forbidden'
        '500':
          $ref: '#/responses/InternalServerError'
      summary: Get the storage bucket backups
      tags:
      - storage
  /1.0/storage-pools/{poolName}/buckets/{bucketName}/keys:
    get:
      description: Returns a list of storage pool bucket keys (URLs).
      operationId: storage_pool_bucket_keys_get
      parameters:
      - description: Storage pool name
        in: path
        name: poolName
        required: true
        type: string
      - description: Storage bucket name
        in: path
        name: bucketName
        required: true
        type: string
      - description: Project name
        example: default
        in: query
        name: project
        type: string
      produces:
      - application/json
      responses:
        '200':
          description: API endpoints
          schema:
            description: Sync response
            properties:
              metadata:
                description: List of endpoints
                example: "[\n  \"/1.0/storage-pools/default/buckets/foo/keys/my-read-only-key\",\n  \"/1.0/storage-pools/default/buckets/bar/keys/admin\",\n]"
                items:
                  type: string
                type: array
              status:
                description: Status description
                example: Success
                type: string
              status_code:
                description: Status code
                example: 200
                type: integer
              type:
                description: Response type
                example: sync
                type: string
            type: object
        '403':
          $ref: '#/responses/Forbidden'
        '500':
          $ref: '#/responses/InternalServerError'
      summary: Get the storage pool bucket keys
      tags:
      - storage
    post:
      consumes:
      - application/json
      description: Creates a new storage pool bucket key.
      operationId: storage_pool_bucket_key_post
      parameters:
      - description: Storage pool name
        in: path
        name: poolName
        required: true
        type: string
      - description: Storage bucket name
        in: path
        name: bucketName
        required: true
        type: string
      - description: Project name
        example: default
        in: query
        name: project
        type: string
      - description: Bucket
        in: body
        name: bucket
        required: true
        schema:
          $ref: '#/definitions/StorageBucketKeysPost'
      produces:
      - application/json
      responses:
        '200':
          $ref: '#/definitions/StorageBucketKey'
        '400':
          $ref: '#/responses/BadRequest'
        '403':
          $ref: '#/responses/Forbidden'
        '500':
          $ref: '#/responses/InternalServerError'
      summary: Add a storage pool bucket key.
      tags:
      - storage
  /1.0/storage-pools/{poolName}/buckets/{bucketName}/keys/{keyName}:
    get:
      description: Gets a specific storage pool bucket key.
      operationId: storage_pool_bucket_key_get
      parameters:
      - description: Storage pool name
        in: path
        name: poolName
        required: true
        type: string
      - description: Storage bucket name
        in: path
        name: bucketName
        required: true
        type: string
      - description: Stora

# --- truncated at 32 KB (139 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/incus/refs/heads/main/openapi/incus-storage-api-openapi.yml