Incus instances API

openapi: 3.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 Instances API
  version: '1.0'
tags:
- name: instances
paths:
  /1.0/instances:
    get:
      description: Returns a list of instances (URLs).
      operationId: instances_get
      parameters:
      - description: Project name
        example: default
        in: query
        name: project
        schema:
          type: string
      - description: Collection filter
        example: default
        in: query
        name: filter
        schema:
          type: string
      - description: Retrieve instances from all projects
        in: query
        name: all-projects
        schema:
          type: boolean
      responses:
        '200':
          description: API endpoints
          content:
            application/json:
              schema:
                description: Sync response
                properties:
                  metadata:
                    description: List of endpoints
                    example: "[\n  \"/1.0/instances/foo\",\n  \"/1.0/instances/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: '#/components/responses/Forbidden'
        '500':
          $ref: '#/components/responses/InternalServerError'
      summary: Get the instances
      tags:
      - instances
    post:
      description: 'Creates a new instance.

        Depending on the source, this can create an instance from an existing

        local image, remote image, existing local instance or snapshot, remote

        migration stream or backup file.'
      operationId: instances_post
      parameters:
      - description: Project name
        example: default
        in: query
        name: project
        schema:
          type: string
      - description: Cluster member
        example: default
        in: query
        name: target
        schema:
          type: string
      responses:
        '202':
          $ref: '#/components/responses/Operation'
        '400':
          $ref: '#/components/responses/BadRequest'
        '403':
          $ref: '#/components/responses/Forbidden'
        '500':
          $ref: '#/components/responses/InternalServerError'
      summary: Create a new instance
      tags:
      - instances
      requestBody:
        content:
          application/json:
            schema: {}
        description: Raw backup file
    put:
      description: Changes the running state of all instances.
      operationId: instances_put
      parameters:
      - description: Project name
        example: default
        in: query
        name: project
        schema:
          type: string
      responses:
        '202':
          $ref: '#/components/responses/Operation'
        '400':
          $ref: '#/components/responses/BadRequest'
        '403':
          $ref: '#/components/responses/Forbidden'
        '500':
          $ref: '#/components/responses/InternalServerError'
      summary: Bulk instance state update
      tags:
      - instances
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/InstancesPut'
        description: State
  /1.0/instances/{name}:
    delete:
      description: 'Deletes a specific instance.


        This also deletes anything owned by the instance such as snapshots and backups.'
      operationId: instance_delete
      parameters:
      - description: Instance name
        in: path
        name: name
        required: true
        schema:
          type: string
      - description: Project name
        example: default
        in: query
        name: project
        schema:
          type: string
      responses:
        '202':
          $ref: '#/components/responses/Operation'
        '400':
          $ref: '#/components/responses/BadRequest'
        '403':
          $ref: '#/components/responses/Forbidden'
        '500':
          $ref: '#/components/responses/InternalServerError'
      summary: Delete an instance
      tags:
      - instances
    get:
      description: Gets a specific instance (basic struct).
      operationId: instance_get
      parameters:
      - description: Instance name
        in: path
        name: name
        required: true
        schema:
          type: string
      - description: Project name
        example: default
        in: query
        name: project
        schema:
          type: string
      responses:
        '200':
          description: Instance
          content:
            application/json:
              schema:
                description: Sync response
                properties:
                  metadata:
                    $ref: '#/components/schemas/Instance'
                  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: '#/components/responses/Forbidden'
        '500':
          $ref: '#/components/responses/InternalServerError'
      summary: Get the instance
      tags:
      - instances
    patch:
      description: Updates a subset of the instance configuration
      operationId: instance_patch
      parameters:
      - description: Instance name
        in: path
        name: name
        required: true
        schema:
          type: string
      - description: Project name
        example: default
        in: query
        name: project
        schema:
          type: string
      responses:
        '200':
          $ref: '#/components/responses/EmptySyncResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '403':
          $ref: '#/components/responses/Forbidden'
        '500':
          $ref: '#/components/responses/InternalServerError'
      summary: Partially update the instance
      tags:
      - instances
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/InstancePut'
        description: Update request
    post:
      description: 'Renames, moves an instance between pools or migrates an instance to another server.


        The returned operation metadata will vary based on what''s requested.

        For rename or move within the same server, this is a simple background operation with progress data.

        For migration, in the push case, this will similarly be a background

        operation with progress data, for the pull case, it will be a websocket

        operation with a number of secrets to be passed to the target server.'
      operationId: instance_post
      parameters:
      - description: Instance name
        in: path
        name: name
        required: true
        schema:
          type: string
      - description: Project name
        example: default
        in: query
        name: project
        schema:
          type: string
      responses:
        '202':
          $ref: '#/components/responses/Operation'
        '400':
          $ref: '#/components/responses/BadRequest'
        '403':
          $ref: '#/components/responses/Forbidden'
        '500':
          $ref: '#/components/responses/InternalServerError'
      summary: Rename or move/migrate an instance
      tags:
      - instances
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/InstancePost'
        description: Migration request
    put:
      description: Updates the instance configuration or trigger a snapshot restore.
      operationId: instance_put
      parameters:
      - description: Instance name
        in: path
        name: name
        required: true
        schema:
          type: string
      - description: Project name
        example: default
        in: query
        name: project
        schema:
          type: string
      responses:
        '202':
          $ref: '#/components/responses/Operation'
        '400':
          $ref: '#/components/responses/BadRequest'
        '403':
          $ref: '#/components/responses/Forbidden'
        '500':
          $ref: '#/components/responses/InternalServerError'
      summary: Update the instance
      tags:
      - instances
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/InstancePut'
        description: Update request
  /1.0/instances/{name}/access:
    get:
      description: Gets the access information for the instance.
      operationId: instance_access
      parameters:
      - description: Instance name
        in: path
        name: name
        required: true
        schema:
          type: string
      - description: Project name
        in: query
        name: project
        schema:
          type: string
      responses:
        '200':
          description: Access
          content:
            application/json:
              schema:
                description: Sync response
                properties:
                  metadata:
                    $ref: '#/components/schemas/Access'
                  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
        '400':
          $ref: '#/components/responses/BadRequest'
        '403':
          $ref: '#/components/responses/Forbidden'
        '500':
          $ref: '#/components/responses/InternalServerError'
      summary: Get who has access to an instance
      tags:
      - instances
  /1.0/instances/{name}/backups:
    get:
      description: Returns a list of instance backups (URLs).
      operationId: instance_backups_get
      parameters:
      - description: Instance name
        in: path
        name: name
        required: true
        schema:
          type: string
      - description: Project name
        example: default
        in: query
        name: project
        schema:
          type: string
      responses:
        '200':
          description: API endpoints
          content:
            application/json:
              schema:
                description: Sync response
                properties:
                  metadata:
                    description: List of endpoints
                    example: "[\n  \"/1.0/instances/foo/backups/backup0\",\n  \"/1.0/instances/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: '#/components/responses/Forbidden'
        '500':
          $ref: '#/components/responses/InternalServerError'
      summary: Get the backups
      tags:
      - instances
    post:
      description: 'Creates a new 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: instance_backups_post
      parameters:
      - description: Instance name
        in: path
        name: name
        required: true
        schema:
          type: string
      - description: Project name
        example: default
        in: query
        name: project
        schema:
          type: string
      responses:
        '202':
          $ref: '#/components/responses/Operation'
        '400':
          $ref: '#/components/responses/BadRequest'
        '403':
          $ref: '#/components/responses/Forbidden'
        '500':
          $ref: '#/components/responses/InternalServerError'
      summary: Create a backup
      tags:
      - instances
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/InstanceBackupsPost'
        description: Backup request
  /1.0/instances/{name}/backups/{backup}:
    delete:
      description: Deletes the instance backup.
      operationId: instance_backup_delete
      parameters:
      - description: Instance name
        in: path
        name: name
        required: true
        schema:
          type: string
      - description: Backup name
        in: path
        name: backup
        required: true
        schema:
          type: string
      - description: Project name
        example: default
        in: query
        name: project
        schema:
          type: string
      responses:
        '202':
          $ref: '#/components/responses/Operation'
        '400':
          $ref: '#/components/responses/BadRequest'
        '403':
          $ref: '#/components/responses/Forbidden'
        '500':
          $ref: '#/components/responses/InternalServerError'
      summary: Delete a backup
      tags:
      - instances
    get:
      description: Gets a specific instance backup.
      operationId: instance_backup_get
      parameters:
      - description: Instance name
        in: path
        name: name
        required: true
        schema:
          type: string
      - description: Backup name
        in: path
        name: backup
        required: true
        schema:
          type: string
      - description: Project name
        example: default
        in: query
        name: project
        schema:
          type: string
      responses:
        '200':
          description: Instance backup
          content:
            application/json:
              schema:
                description: Sync response
                properties:
                  metadata:
                    $ref: '#/components/schemas/InstanceBackup'
                  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: '#/components/responses/Forbidden'
        '500':
          $ref: '#/components/responses/InternalServerError'
      summary: Get the backup
      tags:
      - instances
    post:
      description: Renames an instance backup.
      operationId: instance_backup_post
      parameters:
      - description: Instance name
        in: path
        name: name
        required: true
        schema:
          type: string
      - description: Backup name
        in: path
        name: backup
        required: true
        schema:
          type: string
      - description: Project name
        example: default
        in: query
        name: project
        schema:
          type: string
      responses:
        '202':
          $ref: '#/components/responses/Operation'
        '400':
          $ref: '#/components/responses/BadRequest'
        '403':
          $ref: '#/components/responses/Forbidden'
        '500':
          $ref: '#/components/responses/InternalServerError'
      summary: Rename a backup
      tags:
      - instances
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/InstanceBackupPost'
        description: Backup rename
  /1.0/instances/{name}/backups/{backup}/export:
    get:
      description: Download the raw backup file(s) from the server.
      operationId: instance_backup_export
      parameters:
      - description: Instance name
        in: path
        name: name
        required: true
        schema:
          type: string
      - description: Backup name
        in: path
        name: backup
        required: true
        schema:
          type: string
      - description: Project name
        example: default
        in: query
        name: project
        schema:
          type: string
      responses:
        '200':
          description: Raw image data
        '403':
          $ref: '#/components/responses/Forbidden'
        '500':
          $ref: '#/components/responses/InternalServerError'
      summary: Get the raw backup file(s)
      tags:
      - instances
  /1.0/instances/{name}/backups?recursion=1:
    get:
      description: Returns a list of instance backups (structs).
      operationId: instance_backups_get_recursion1
      parameters:
      - description: Instance name
        in: path
        name: name
        required: true
        schema:
          type: string
      - description: Project name
        example: default
        in: query
        name: project
        schema:
          type: string
      responses:
        '200':
          description: API endpoints
          content:
            application/json:
              schema:
                description: Sync response
                properties:
                  metadata:
                    description: List of instance backups
                    items:
                      $ref: '#/components/schemas/InstanceBackup'
                    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: '#/components/responses/Forbidden'
        '500':
          $ref: '#/components/responses/InternalServerError'
      summary: Get the backups
      tags:
      - instances
  /1.0/instances/{name}/bitmaps:
    post:
      description: Creates a new bitmap.
      operationId: instance_bitmaps_post
      parameters:
      - description: Instance name
        in: path
        name: name
        required: true
        schema:
          type: string
      - description: Project name
        example: default
        in: query
        name: project
        schema:
          type: string
      responses:
        '202':
          $ref: '#/components/responses/Operation'
        '400':
          $ref: '#/components/responses/BadRequest'
        '403':
          $ref: '#/components/responses/Forbidden'
        '500':
          $ref: '#/components/responses/InternalServerError'
      summary: Create a bitmap
      tags:
      - instances
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/StorageVolumeBitmapsPost'
        description: Bitmap request
  /1.0/instances/{name}/console:
    delete:
      description: Clears the console log buffer.
      operationId: instance_console_delete
      parameters:
      - description: Instance name
        in: path
        name: name
        required: true
        schema:
          type: string
      - description: Project name
        example: default
        in: query
        name: project
        schema:
          type: string
      responses:
        '200':
          $ref: '#/components/responses/EmptySyncResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
      summary: Clear the console log
      tags:
      - instances
    get:
      description: 'Gets the console output for the instance either as text log or as vga

        screendump.'
      operationId: instance_console_get
      parameters:
      - description: Instance name
        in: path
        name: name
        required: true
        schema:
          type: string
      - description: Project name
        example: default
        in: query
        name: project
        schema:
          type: string
      - description: Console type
        example: vga
        in: query
        name: type
        schema:
          type: string
          enum:
          - log
          - vga
          default: log
      responses:
        '200':
          description: 'Console output either as raw console log or as vga screendump in PNG

            format depending on the `type` parameter provided with the request.

            '
        '400':
          $ref: '#/components/responses/BadRequest'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
      summary: Get console output
      tags:
      - instances
    post:
      description: 'Connects to the console of an instance.


        The returned operation metadata will contain two websockets, one for data and one for control.'
      operationId: instance_console_post
      parameters:
      - description: Instance name
        in: path
        name: name
        required: true
        schema:
          type: string
      - description: Project name
        example: default
        in: query
        name: project
        schema:
          type: string
      responses:
        '202':
          $ref: '#/components/responses/Operation'
        '400':
          $ref: '#/components/responses/BadRequest'
        '403':
          $ref: '#/components/responses/Forbidden'
        '500':
          $ref: '#/components/responses/InternalServerError'
      summary: Connect to console
      tags:
      - instances
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/InstanceConsolePost'
        description: Console request
  /1.0/instances/{name}/debug/memory:
    get:
      description: 'Returns memory debug information of a running instance.

        Only supported for VMs.'
      operationId: instance_debug_memory_get
      parameters:
      - description: Instance name
        in: path
        name: name
        required: true
        schema:
          type: string
      - description: Project name
        example: default
        in: query
        name: project
        schema:
          type: string
      - description: Memory dump format
        example: elf
        in: query
        name: format
        schema:
          type: string
      responses:
        '200':
          description: Success
        '400':
          $ref: '#/components/responses/BadRequest'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
      summary: Get memory debug information of an instance
      tags:
      - instances
  /1.0/instances/{name}/debug/repair:
    get:
      description: Runs an internal repair action on the instance.
      operationId: instance_debug_repair_post
      parameters:
      - description: Instance name
        in: path
        name: name
        required: true
        schema:
          type: string
      - description: Project name
        example: default
        in: query
        name: project
        schema:
          type: string
      responses:
        '200':
          $ref: '#/components/responses/EmptySyncResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
      summary: Trigger a repair action on the instance.
      tags:
      - instances
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/InstanceDebugRepairPost'
        description: State
  /1.0/instances/{name}/exec:
    post:
      description: 'Executes a command inside an instance.


        The returned operation metadata will contain either 2 or 4 websockets.

        In non-interactive mode, you''ll get one websocket for each of stdin, stdout and stderr.

        In interactive mode, a single bi-directional websocket is used for stdin and stdout/stderr.


        An additional "control" socket is always added on top which can be used for out of band communications.

        This allows sending signals and window sizing information through.'
      operationId: instance_exec_post
      parameters:
      - description: Instance name
        in: path
        name: name
        required: true
        schema:
          type: string
      - description: Project name
        example: default
        in: query
        name: project
        schema:
          type: string
      responses:
        '202':
          $ref: '#/components/responses/Operation'
        '400':
          $ref: '#/components/responses/BadRequest'
        '403':
          $ref: '#/components/responses/Forbidden'
        '500':
          $ref: '#/components/responses/InternalServerError'
      summary: Run a command
      tags:
      - instances
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/InstanceExecPost'
        description: Exec request
  /1.0/instances/{name}/files:
    delete:
      description: Removes the file.
      operationId: instance_files_delete
      parameters:
      - description: Instance name
        in: path
        name: name
        required: true
        schema:
          type: string
      - description: Path to the file
        example: default
        in: query
        name: path
        schema:
          type: string
      - description: Project name
        example: default
        in: query
        name: project
        schema:
          type: string
      - description: Perform recursive deletion
        example: true
        in: header
        name: X-Incus-force
        schema:
          type: boolean
      responses:
        '200':
          $ref: '#/components/responses/EmptySyncResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
      summary: Delete a file
      tags:
      - instances
    get:
      description: Gets the file content. If it's a directory, a json list of files will be returned instead.
      operationId: instance_files_get
      parameters:
      - description: Instance name
        in: path
        name: name
        required: true
        schema:
          type: string
      - description: Path to the file
        example: default
        in: query
        name: path
        schema:
          type: string
      - description: Project name
        example: default
        in: query
        name: project
        schema:
          type: string
      responses:
        '200':
          description: Raw file or directory listing
          headers:
            X-Incus-gid:
              description: File owner GID
            X-Incus-mode:
              description: Mode mask
            X-Incus-modified:
              description: Last modified date
            X-Incus-type:
              description: Type of file (file, symlink or directory)
            X-Incus-uid:
              description: File owner UID
        '400':
          $ref: '#/components/responses/BadRequest'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
      summary: Get a file
      tags:
      - instances
    head:
      description: Gets the file or directory metadata.
      operationId: instance_files_head
      parameters:
      - description: Instance name
        in: path
        name: name
        required: true
        schema:
          type: string
      - description: Path to the file
        example: default
        in: query
        name: path
        schema:
          type: string
      - description: Project name
        example: default
        in: query
        name: project
        schema:
          type: string
      responses:
        '200':
          description: Raw file or directory listing
          headers:
            X-Incus-gid:
              description: File owner GID
            X-Incus-mode:
              description: Mode mask
            X-Incus-modified:
              description: Last modified date
            X-Incus-type:
              description: Type of file (file, symlink or directory)
            X-Incus-uid:
              description: File owner UID
        '400':
          $ref: '#/components/responses/BadRequest'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
      summary: Get metadata for a file
      tags:
      - instances
    post:
      description: Creates a new file in the instance.
      operationId: instance_files_post
      parameters:
      - description: Instance name
        in: path
        name: name
        required: true
        schema:
          type: string
      - description: Path to the file
        example: default
        in: query
        name: path
        schema:
          type: string
      - description: Project name
        example: default
        in: query
        name: project
        schema:
          type: string
      - description: File owner UID
        example: 1000
        in: header
        name: X-Incus-uid
        schema:
          type: integer
      - description: File owner GID
        example: 1000
        in: header
        name: X-Incus-gid
        schema:
          type: integer
      - description: File mode
        example: 420
        in: header
        name: X-Incus-mode
        schema:
          type: integer
      - description: Type of file (file, symlink or directory)
        example: file
        in: header
        name: X-Incus-type
        schema:
          type: string
      - description: Write mode (overwrite or append)
        example: overwrite
        in: header
        name: X-Incus-write
        schema:
          type: string
      responses:
        '200':
          $ref: '#/components/responses/EmptySyncResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '403':
          

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