Incus instances 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 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
        type: string
      - description: Collection filter
        example: default
        in: query
        name: filter
        type: string
      - description: Retrieve instances from all projects
        in: query
        name: all-projects
        type: boolean
      produces:
      - application/json
      responses:
        '200':
          description: API endpoints
          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: '#/responses/Forbidden'
        '500':
          $ref: '#/responses/InternalServerError'
      summary: Get the instances
      tags:
      - instances
    post:
      consumes:
      - application/json
      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
        type: string
      - description: Cluster member
        example: default
        in: query
        name: target
        type: string
      - description: Instance request
        in: body
        name: instance
        schema:
          $ref: '#/definitions/InstancesPost'
      - description: Raw backup file
        in: body
        name: raw_backup
      produces:
      - application/json
      responses:
        '202':
          $ref: '#/responses/Operation'
        '400':
          $ref: '#/responses/BadRequest'
        '403':
          $ref: '#/responses/Forbidden'
        '500':
          $ref: '#/responses/InternalServerError'
      summary: Create a new instance
      tags:
      - instances
    put:
      consumes:
      - application/json
      description: Changes the running state of all instances.
      operationId: instances_put
      parameters:
      - description: Project name
        example: default
        in: query
        name: project
        type: string
      - description: State
        in: body
        name: state
        schema:
          $ref: '#/definitions/InstancesPut'
      produces:
      - application/json
      responses:
        '202':
          $ref: '#/responses/Operation'
        '400':
          $ref: '#/responses/BadRequest'
        '403':
          $ref: '#/responses/Forbidden'
        '500':
          $ref: '#/responses/InternalServerError'
      summary: Bulk instance state update
      tags:
      - instances
  /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
        type: string
      - description: Project name
        example: default
        in: query
        name: project
        type: string
      produces:
      - application/json
      responses:
        '202':
          $ref: '#/responses/Operation'
        '400':
          $ref: '#/responses/BadRequest'
        '403':
          $ref: '#/responses/Forbidden'
        '500':
          $ref: '#/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
        type: string
      - description: Project name
        example: default
        in: query
        name: project
        type: string
      produces:
      - application/json
      responses:
        '200':
          description: Instance
          schema:
            description: Sync response
            properties:
              metadata:
                $ref: '#/definitions/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: '#/responses/Forbidden'
        '500':
          $ref: '#/responses/InternalServerError'
      summary: Get the instance
      tags:
      - instances
    patch:
      consumes:
      - application/json
      description: Updates a subset of the instance configuration
      operationId: instance_patch
      parameters:
      - description: Instance name
        in: path
        name: name
        required: true
        type: string
      - description: Project name
        example: default
        in: query
        name: project
        type: string
      - description: Update request
        in: body
        name: instance
        schema:
          $ref: '#/definitions/InstancePut'
      produces:
      - application/json
      responses:
        '200':
          $ref: '#/responses/EmptySyncResponse'
        '400':
          $ref: '#/responses/BadRequest'
        '403':
          $ref: '#/responses/Forbidden'
        '500':
          $ref: '#/responses/InternalServerError'
      summary: Partially update the instance
      tags:
      - instances
    post:
      consumes:
      - application/json
      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
        type: string
      - description: Project name
        example: default
        in: query
        name: project
        type: string
      - description: Migration request
        in: body
        name: migration
        schema:
          $ref: '#/definitions/InstancePost'
      produces:
      - application/json
      responses:
        '202':
          $ref: '#/responses/Operation'
        '400':
          $ref: '#/responses/BadRequest'
        '403':
          $ref: '#/responses/Forbidden'
        '500':
          $ref: '#/responses/InternalServerError'
      summary: Rename or move/migrate an instance
      tags:
      - instances
    put:
      consumes:
      - application/json
      description: Updates the instance configuration or trigger a snapshot restore.
      operationId: instance_put
      parameters:
      - description: Instance name
        in: path
        name: name
        required: true
        type: string
      - description: Project name
        example: default
        in: query
        name: project
        type: string
      - description: Update request
        in: body
        name: instance
        schema:
          $ref: '#/definitions/InstancePut'
      produces:
      - application/json
      responses:
        '202':
          $ref: '#/responses/Operation'
        '400':
          $ref: '#/responses/BadRequest'
        '403':
          $ref: '#/responses/Forbidden'
        '500':
          $ref: '#/responses/InternalServerError'
      summary: Update the instance
      tags:
      - instances
  /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
        type: string
      - description: Project name
        in: query
        name: project
        type: string
      produces:
      - application/json
      responses:
        '200':
          description: Access
          schema:
            description: Sync response
            properties:
              metadata:
                $ref: '#/definitions/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: '#/responses/BadRequest'
        '403':
          $ref: '#/responses/Forbidden'
        '500':
          $ref: '#/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
        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/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: '#/responses/Forbidden'
        '500':
          $ref: '#/responses/InternalServerError'
      summary: Get the backups
      tags:
      - instances
    post:
      consumes:
      - application/json
      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
        type: string
      - description: Project name
        example: default
        in: query
        name: project
        type: string
      - description: Backup request
        in: body
        name: backup
        schema:
          $ref: '#/definitions/InstanceBackupsPost'
      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 backup
      tags:
      - instances
  /1.0/instances/{name}/backups/{backup}:
    delete:
      consumes:
      - application/json
      description: Deletes the instance backup.
      operationId: instance_backup_delete
      parameters:
      - description: Instance name
        in: path
        name: name
        required: true
        type: string
      - description: Backup name
        in: path
        name: backup
        required: true
        type: string
      - description: Project name
        example: default
        in: query
        name: project
        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 backup
      tags:
      - instances
    get:
      description: Gets a specific instance backup.
      operationId: instance_backup_get
      parameters:
      - description: Instance name
        in: path
        name: name
        required: true
        type: string
      - description: Backup name
        in: path
        name: backup
        required: true
        type: string
      - description: Project name
        example: default
        in: query
        name: project
        type: string
      produces:
      - application/json
      responses:
        '200':
          description: Instance backup
          schema:
            description: Sync response
            properties:
              metadata:
                $ref: '#/definitions/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: '#/responses/Forbidden'
        '500':
          $ref: '#/responses/InternalServerError'
      summary: Get the backup
      tags:
      - instances
    post:
      consumes:
      - application/json
      description: Renames an instance backup.
      operationId: instance_backup_post
      parameters:
      - description: Instance name
        in: path
        name: name
        required: true
        type: string
      - description: Backup name
        in: path
        name: backup
        required: true
        type: string
      - description: Project name
        example: default
        in: query
        name: project
        type: string
      - description: Backup rename
        in: body
        name: backup
        schema:
          $ref: '#/definitions/InstanceBackupPost'
      produces:
      - application/json
      responses:
        '202':
          $ref: '#/responses/Operation'
        '400':
          $ref: '#/responses/BadRequest'
        '403':
          $ref: '#/responses/Forbidden'
        '500':
          $ref: '#/responses/InternalServerError'
      summary: Rename a backup
      tags:
      - instances
  /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
        type: string
      - description: Backup name
        in: path
        name: backup
        required: true
        type: string
      - description: Project name
        example: default
        in: query
        name: project
        type: string
      produces:
      - application/octet-stream
      responses:
        '200':
          description: Raw image data
        '403':
          $ref: '#/responses/Forbidden'
        '500':
          $ref: '#/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
        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 instance backups
                items:
                  $ref: '#/definitions/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: '#/responses/Forbidden'
        '500':
          $ref: '#/responses/InternalServerError'
      summary: Get the backups
      tags:
      - instances
  /1.0/instances/{name}/bitmaps:
    post:
      consumes:
      - application/json
      description: Creates a new bitmap.
      operationId: instance_bitmaps_post
      parameters:
      - description: Instance name
        in: path
        name: name
        required: true
        type: string
      - description: Project name
        example: default
        in: query
        name: project
        type: string
      - description: Bitmap request
        in: body
        name: bitmap
        schema:
          $ref: '#/definitions/StorageVolumeBitmapsPost'
      produces:
      - application/json
      responses:
        '202':
          $ref: '#/responses/Operation'
        '400':
          $ref: '#/responses/BadRequest'
        '403':
          $ref: '#/responses/Forbidden'
        '500':
          $ref: '#/responses/InternalServerError'
      summary: Create a bitmap
      tags:
      - instances
  /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
        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'
        '404':
          $ref: '#/responses/NotFound'
        '500':
          $ref: '#/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
        type: string
      - description: Project name
        example: default
        in: query
        name: project
        type: string
      - default: log
        description: Console type
        enum:
        - log
        - vga
        example: vga
        in: query
        name: type
        type: string
      produces:
      - application/json
      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: '#/responses/BadRequest'
        '403':
          $ref: '#/responses/Forbidden'
        '404':
          $ref: '#/responses/NotFound'
        '500':
          $ref: '#/responses/InternalServerError'
      summary: Get console output
      tags:
      - instances
    post:
      consumes:
      - application/json
      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
        type: string
      - description: Project name
        example: default
        in: query
        name: project
        type: string
      - description: Console request
        in: body
        name: console
        schema:
          $ref: '#/definitions/InstanceConsolePost'
      produces:
      - application/json
      responses:
        '202':
          $ref: '#/responses/Operation'
        '400':
          $ref: '#/responses/BadRequest'
        '403':
          $ref: '#/responses/Forbidden'
        '500':
          $ref: '#/responses/InternalServerError'
      summary: Connect to console
      tags:
      - instances
  /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
        type: string
      - description: Project name
        example: default
        in: query
        name: project
        type: string
      - description: Memory dump format
        example: elf
        in: query
        name: format
        type: string
      responses:
        '200':
          description: Success
        '400':
          $ref: '#/responses/BadRequest'
        '403':
          $ref: '#/responses/Forbidden'
        '404':
          $ref: '#/responses/NotFound'
        '500':
          $ref: '#/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
        type: string
      - description: Project name
        example: default
        in: query
        name: project
        type: string
      - description: State
        in: body
        name: state
        schema:
          $ref: '#/definitions/InstanceDebugRepairPost'
      responses:
        '200':
          $ref: '#/responses/EmptySyncResponse'
        '400':
          $ref: '#/responses/BadRequest'
        '403':
          $ref: '#/responses/Forbidden'
        '404':
          $ref: '#/responses/NotFound'
        '500':
          $ref: '#/responses/InternalServerError'
      summary: Trigger a repair action on the instance.
      tags:
      - instances
  /1.0/instances/{name}/exec:
    post:
      consumes:
      - application/json
      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
        type: string
      - description: Project name
        example: default
        in: query
        name: project
        type: string
      - description: Exec request
        in: body
        name: exec
        schema:
          $ref: '#/definitions/InstanceExecPost'
      produces:
      - application/json
      responses:
        '202':
          $ref: '#/responses/Operation'
        '400':
          $ref: '#/responses/BadRequest'
        '403':
          $ref: '#/responses/Forbidden'
        '500':
          $ref: '#/responses/InternalServerError'
      summary: Run a command
      tags:
      - instances
  /1.0/instances/{name}/files:
    delete:
      description: Removes the file.
      operationId: instance_files_delete
      parameters:
      - description: Instance name
        in: path
        name: name
        required: true
        type: string
      - description: Path to the file
        example: default
        in: query
        name: path
        type: string
      - description: Project name
        example: default
        in: query
        name: project
        type: string
      - description: Perform recursive deletion
        example: true
        in: header
        name: X-Incus-force
        schema:
          type: boolean
      produces:
      - application/json
      responses:
        '200':
          $ref: '#/responses/EmptySyncResponse'
        '400':
          $ref: '#/responses/BadRequest'
        '403':
          $ref: '#/responses/Forbidden'
        '404':
          $ref: '#/responses/NotFound'
        '500':
          $ref: '#/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
        type: string
      - description: Path to the file
        example: default
        in: query
        name: path
        type: string
      - description: Project name
        example: default
        in: query
        name: project
        type: string
      produces:
      - application/json
      - application/octet-stream
      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: '#/responses/BadRequest'
        '403':
          $ref: '#/responses/Forbidden'
        '404':
          $ref: '#/responses/NotFound'
        '500':
          $ref: '#/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
        type: string
      - description: Path to the file
        example: default
        in: query
        name: path
        type: string
      - description: Project name
        example: default
        in: query
        name: project
        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: '#/responses/BadRequest'
        '403':
          $ref: '#/responses/Forbidden'
        '404':
          $ref: '#/responses/NotFound'
        '500':
          $ref: '#/responses/InternalServerError'
      summary: Get metadata for a file
      tags:
      - instances
    post:
      consumes:
      - application/octet-stream
      description: Creates a new file in the instance.
      operationId: instance_files_post
      parameters:
      - description: Instance name
        in: path
        name: name
        required: true
        type: string
      - description: Path to the file
        example: default
        in: query
        name: path
        type: string
      - description: Project name
        example: default
        in: query
        name: project
        type: string
      - description: Raw file content
        in: body
        name: raw_file
      - 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
      produces:
      - application/json
      responses:
        '200':
          $ref: '#/responses/EmptySyncResponse'
        '400':
          $ref: '#/responses/BadRequest'
        '403':
          $ref: '#/responses/Forbidden'
        '404':
          $ref: '#/responses/NotFound'
        '500':
          $ref: '#/responses/InternalServerError'
      summary: Create or replace a file
      tags:
      - instances
  /1.0/instances/{name}/logs:
    get:
      description: Returns a list of log files (URLs).
      operationId: instance_logs_get
      parameters:
      - description: Instance name
        in: path
        name: name
        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/instances/foo/logs/lxc.log\"\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'
        '404':
          $ref: '#/responses/NotFound'
        '500':
          $ref: '#/responses/InternalServerError'
      summary: Get the log files
      tags:
      - instances
  /1.0/instances/{name}/logs

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