Incus external REST API — instances

naftiko: 1.0.0-alpha2
info:
  label: Incus external REST API — instances
  description: 'Incus external REST API — instances. 54 operations. Lead operation: Get the instances. Self-contained Naftiko
    capability covering one Incus business surface.'
  tags:
  - Incus
  - instances
  created: '2026-05-19'
  modified: '2026-05-19'
binds:
- namespace: env
  keys:
    INCUS_API_KEY: INCUS_API_KEY
capability:
  consumes:
  - type: http
    namespace: incus-instances
    baseUri: ''
    description: Incus external REST API — instances business capability. Self-contained, no shared references.
    resources:
    - name: 1.0-instances
      path: /1.0/instances
      operations:
      - name: instancesget
        method: GET
        description: Get the instances
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: project
          in: query
          type: string
          description: Project name
        - name: filter
          in: query
          type: string
          description: Collection filter
        - name: all-projects
          in: query
          type: boolean
          description: Retrieve instances from all projects
      - name: instancespost
        method: POST
        description: Create a new instance
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: project
          in: query
          type: string
          description: Project name
        - name: target
          in: query
          type: string
          description: Cluster member
        - name: instance
          in: body
          type: string
          description: Instance request
        - name: raw_backup
          in: body
          type: string
          description: Raw backup file
      - name: instancesput
        method: PUT
        description: Bulk instance state update
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: project
          in: query
          type: string
          description: Project name
        - name: state
          in: body
          type: string
          description: State
    - name: 1.0-instances-name
      path: /1.0/instances/{name}
      operations:
      - name: instancedelete
        method: DELETE
        description: Delete an instance
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: name
          in: path
          type: string
          description: Instance name
          required: true
        - name: project
          in: query
          type: string
          description: Project name
      - name: instanceget
        method: GET
        description: Get the instance
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: name
          in: path
          type: string
          description: Instance name
          required: true
        - name: project
          in: query
          type: string
          description: Project name
      - name: instancepatch
        method: PATCH
        description: Partially update the instance
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: name
          in: path
          type: string
          description: Instance name
          required: true
        - name: project
          in: query
          type: string
          description: Project name
        - name: instance
          in: body
          type: string
          description: Update request
      - name: instancepost
        method: POST
        description: Rename or move/migrate an instance
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: name
          in: path
          type: string
          description: Instance name
          required: true
        - name: project
          in: query
          type: string
          description: Project name
        - name: migration
          in: body
          type: string
          description: Migration request
      - name: instanceput
        method: PUT
        description: Update the instance
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: name
          in: path
          type: string
          description: Instance name
          required: true
        - name: project
          in: query
          type: string
          description: Project name
        - name: instance
          in: body
          type: string
          description: Update request
    - name: 1.0-instances-name-access
      path: /1.0/instances/{name}/access
      operations:
      - name: instanceaccess
        method: GET
        description: Get who has access to an instance
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: name
          in: path
          type: string
          description: Instance name
          required: true
        - name: project
          in: query
          type: string
          description: Project name
    - name: 1.0-instances-name-backups
      path: /1.0/instances/{name}/backups
      operations:
      - name: instancebackupsget
        method: GET
        description: Get the backups
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: name
          in: path
          type: string
          description: Instance name
          required: true
        - name: project
          in: query
          type: string
          description: Project name
      - name: instancebackupspost
        method: POST
        description: Create a backup
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: name
          in: path
          type: string
          description: Instance name
          required: true
        - name: project
          in: query
          type: string
          description: Project name
        - name: backup
          in: body
          type: string
          description: Backup request
    - name: 1.0-instances-name-backups-backup
      path: /1.0/instances/{name}/backups/{backup}
      operations:
      - name: instancebackupdelete
        method: DELETE
        description: Delete a backup
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: name
          in: path
          type: string
          description: Instance name
          required: true
        - name: backup
          in: path
          type: string
          description: Backup name
          required: true
        - name: project
          in: query
          type: string
          description: Project name
      - name: instancebackupget
        method: GET
        description: Get the backup
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: name
          in: path
          type: string
          description: Instance name
          required: true
        - name: backup
          in: path
          type: string
          description: Backup name
          required: true
        - name: project
          in: query
          type: string
          description: Project name
      - name: instancebackuppost
        method: POST
        description: Rename a backup
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: name
          in: path
          type: string
          description: Instance name
          required: true
        - name: backup
          in: path
          type: string
          description: Backup name
          required: true
        - name: project
          in: query
          type: string
          description: Project name
        - name: backup
          in: body
          type: string
          description: Backup rename
    - name: 1.0-instances-name-backups-backup-export
      path: /1.0/instances/{name}/backups/{backup}/export
      operations:
      - name: instancebackupexport
        method: GET
        description: Get the raw backup file(s)
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: name
          in: path
          type: string
          description: Instance name
          required: true
        - name: backup
          in: path
          type: string
          description: Backup name
          required: true
        - name: project
          in: query
          type: string
          description: Project name
    - name: 1.0-instances-name-backups?recursion=1
      path: /1.0/instances/{name}/backups?recursion=1
      operations:
      - name: instancebackupsgetrecursion1
        method: GET
        description: Get the backups
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: name
          in: path
          type: string
          description: Instance name
          required: true
        - name: project
          in: query
          type: string
          description: Project name
    - name: 1.0-instances-name-bitmaps
      path: /1.0/instances/{name}/bitmaps
      operations:
      - name: instancebitmapspost
        method: POST
        description: Create a bitmap
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: name
          in: path
          type: string
          description: Instance name
          required: true
        - name: project
          in: query
          type: string
          description: Project name
        - name: bitmap
          in: body
          type: string
          description: Bitmap request
    - name: 1.0-instances-name-console
      path: /1.0/instances/{name}/console
      operations:
      - name: instanceconsoledelete
        method: DELETE
        description: Clear the console log
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: name
          in: path
          type: string
          description: Instance name
          required: true
        - name: project
          in: query
          type: string
          description: Project name
      - name: instanceconsoleget
        method: GET
        description: Get console output
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: name
          in: path
          type: string
          description: Instance name
          required: true
        - name: project
          in: query
          type: string
          description: Project name
        - name: type
          in: query
          type: string
          description: Console type
      - name: instanceconsolepost
        method: POST
        description: Connect to console
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: name
          in: path
          type: string
          description: Instance name
          required: true
        - name: project
          in: query
          type: string
          description: Project name
        - name: console
          in: body
          type: string
          description: Console request
    - name: 1.0-instances-name-debug-memory
      path: /1.0/instances/{name}/debug/memory
      operations:
      - name: instancedebugmemoryget
        method: GET
        description: Get memory debug information of an instance
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: name
          in: path
          type: string
          description: Instance name
          required: true
        - name: project
          in: query
          type: string
          description: Project name
        - name: format
          in: query
          type: string
          description: Memory dump format
    - name: 1.0-instances-name-debug-repair
      path: /1.0/instances/{name}/debug/repair
      operations:
      - name: instancedebugrepairpost
        method: GET
        description: Trigger a repair action on the instance.
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: name
          in: path
          type: string
          description: Instance name
          required: true
        - name: project
          in: query
          type: string
          description: Project name
        - name: state
          in: body
          type: string
          description: State
    - name: 1.0-instances-name-exec
      path: /1.0/instances/{name}/exec
      operations:
      - name: instanceexecpost
        method: POST
        description: Run a command
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: name
          in: path
          type: string
          description: Instance name
          required: true
        - name: project
          in: query
          type: string
          description: Project name
        - name: exec
          in: body
          type: string
          description: Exec request
    - name: 1.0-instances-name-files
      path: /1.0/instances/{name}/files
      operations:
      - name: instancefilesdelete
        method: DELETE
        description: Delete a file
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: name
          in: path
          type: string
          description: Instance name
          required: true
        - name: path
          in: query
          type: string
          description: Path to the file
        - name: project
          in: query
          type: string
          description: Project name
        - name: X-Incus-force
          in: header
          type: boolean
          description: Perform recursive deletion
      - name: instancefilesget
        method: GET
        description: Get a file
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: name
          in: path
          type: string
          description: Instance name
          required: true
        - name: path
          in: query
          type: string
          description: Path to the file
        - name: project
          in: query
          type: string
          description: Project name
      - name: instancefileshead
        method: HEAD
        description: Get metadata for a file
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: name
          in: path
          type: string
          description: Instance name
          required: true
        - name: path
          in: query
          type: string
          description: Path to the file
        - name: project
          in: query
          type: string
          description: Project name
      - name: instancefilespost
        method: POST
        description: Create or replace a file
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: name
          in: path
          type: string
          description: Instance name
          required: true
        - name: path
          in: query
          type: string
          description: Path to the file
        - name: project
          in: query
          type: string
          description: Project name
        - name: raw_file
          in: body
          type: string
          description: Raw file content
        - name: X-Incus-uid
          in: header
          type: integer
          description: File owner UID
        - name: X-Incus-gid
          in: header
          type: integer
          description: File owner GID
        - name: X-Incus-mode
          in: header
          type: integer
          description: File mode
        - name: X-Incus-type
          in: header
          type: string
          description: Type of file (file, symlink or directory)
        - name: X-Incus-write
          in: header
          type: string
          description: Write mode (overwrite or append)
    - name: 1.0-instances-name-logs
      path: /1.0/instances/{name}/logs
      operations:
      - name: instancelogsget
        method: GET
        description: Get the log files
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: name
          in: path
          type: string
          description: Instance name
          required: true
        - name: project
          in: query
          type: string
          description: Project name
    - name: 1.0-instances-name-logs-exec-output
      path: /1.0/instances/{name}/logs/exec-output
      operations:
      - name: instanceexecoutputsget
        method: GET
        description: Get the exec record-output files
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: name
          in: path
          type: string
          description: Instance name
          required: true
        - name: project
          in: query
          type: string
          description: Project name
    - name: 1.0-instances-name-logs-exec-output-filename
      path: /1.0/instances/{name}/logs/exec-output/{filename}
      operations:
      - name: instanceexecoutputdelete
        method: DELETE
        description: Delete the exec record-output file
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: name
          in: path
          type: string
          description: Instance name
          required: true
        - name: filename
          in: path
          type: string
          description: Log file name
          required: true
        - name: project
          in: query
          type: string
          description: Project name
      - name: instanceexecoutputget
        method: GET
        description: Get the exec-output log file
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: name
          in: path
          type: string
          description: Instance name
          required: true
        - name: filename
          in: path
          type: string
          description: Log file name
          required: true
        - name: project
          in: query
          type: string
          description: Project name
    - name: 1.0-instances-name-logs-filename
      path: /1.0/instances/{name}/logs/{filename}
      operations:
      - name: instancelogdelete
        method: DELETE
        description: Delete the log file
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: name
          in: path
          type: string
          description: Instance name
          required: true
        - name: filename
          in: path
          type: string
          description: Log file name
          required: true
        - name: project
          in: query
          type: string
          description: Project name
      - name: instancelogget
        method: GET
        description: Get the log file
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: name
          in: path
          type: string
          description: Instance name
          required: true
        - name: filename
          in: path
          type: string
          description: Log file name
          required: true
        - name: project
          in: query
          type: string
          description: Project name
    - name: 1.0-instances-name-metadata
      path: /1.0/instances/{name}/metadata
      operations:
      - name: instancemetadataget
        method: GET
        description: Get the instance image metadata
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: name
          in: path
          type: string
          description: Instance name
          required: true
        - name: project
          in: query
          type: string
          description: Project name
      - name: instancemetadatapatch
        method: PATCH
        description: Partially update the image metadata
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: name
          in: path
          type: string
          description: Instance name
          required: true
        - name: project
          in: query
          type: string
          description: Project name
        - name: metadata
          in: body
          type: string
          description: Image metadata
          required: true
      - name: instancemetadataput
        method: PUT
        description: Update the image metadata
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: name
          in: path
          type: string
          description: Instance name
          required: true
        - name: project
          in: query
          type: string
          description: Project name
        - name: metadata
          in: body
          type: string
          description: Image metadata
          required: true
    - name: 1.0-instances-name-metadata-templates
      path: /1.0/instances/{name}/metadata/templates
      operations:
      - name: instancemetadatatemplatesdelete
        method: DELETE
        description: Delete a template file
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: name
          in: path
          type: string
          description: Instance name
          required: true
        - name: path
          in: query
          type: string
          description: Template name
        - name: project
          in: query
          type: string
          description: Project name
      - name: instancemetadatatemplatesget
        method: GET
        description: Get the template file names or a specific
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: name
          in: path
          type: string
          description: Instance name
          required: true
        - name: project
          in: query
          type: string
          description: Project name
        - name: path
          in: query
          type: string
          description: Template name
      - name: instancemetadatatemplatespost
        method: POST
        description: Create or replace a template file
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: name
          in: path
          type: string
          description: Instance name
          required: true
        - name: path
          in: query
          type: string
          description: Template name
        - name: project
          in: query
          type: string
          description: Project name
        - name: raw_file
          in: body
          type: string
          description: Raw file content
    - name: 1.0-instances-name-rebuild
      path: /1.0/instances/{name}/rebuild
      operations:
      - name: instancerebuildpost
        method: POST
        description: Rebuild an instance
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: name
          in: path
          type: string
          description: Instance name
          required: true
        - name: project
          in: query
          type: string
          description: Project name
        - name: instance
          in: body
          type: string
          description: InstanceRebuild request
          required: true
    - name: 1.0-instances-name-sftp
      path: /1.0/instances/{name}/sftp
      operations:
      - name: instancesftp
        method: GET
        description: Get the instance SFTP connection
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: name
          in: path
          type: string
          description: Instance name
          required: true
    - name: 1.0-instances-name-snapshots
      path: /1.0/instances/{name}/snapshots
      operations:
      - name: instancesnapshotsget
        method: GET
        description: Get the snapshots
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: name
          in: path
          type: string
          description: Instance name
          required: true
        - name: project
          in: query
          type: string
          description: Project name
      - name: instancesnapshotspost
        method: POST
        description: Create a snapshot
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: name
          in: path
          type: string
          description: Instance name
          required: true
        - name: project
          in: query
          type: string
          description: Project name
        - name: snapshot
          in: body
          type: string
          description: Snapshot request
    - name: 1.0-instances-name-snapshots-snapshot
      path: /1.0/instances/{name}/snapshots/{snapshot}
      operations:
      - name: instancesnapshotdelete
        method: DELETE
        description: Delete a snapshot
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: name
          in: path
          type: string
          description: Instance name
          required: true
        - name: snapshot
          in: path
          type: string
          description: Snapshot name
          required: true
        - name: project
          in: query
          type: string
          description: Project name
      - name: instancesnapshotget
        method: GET
        description: Get the snapshot
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: name
          in: path
          type: string
          description: Instance name
          required: true
        - name: snapshot
          in: path
          type: string
          description: Snapshot name
          required: true
        - name: project
          in: query
          type: string
          description: Project name
      - name: instancesnapshotpatch
        method: PATCH
        description: Partially update snapshot
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: name
          in: path
          type: string
          description: Instance name
          required: true
        - name: snapshot
          in: path
          type: string
          description: Snapshot name
          required: true
        - name: project
          in: query
          type: string
          description: Project name
        - name: snapshot
          in: body
          type: string
          description: Snapshot update
      - name: instancesnapshotpost
        method: POST
        description: Rename or move/migrate a snapshot
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: name
          in: path
          type: string
          description: Instance name
          required: true
        - name: snapshot
          in: path
          type: string
          description: Snapshot name
          required: true
        - name: project
          in: query
          type: string
          description: Project name
        - name: snapshot
          in: body
          type: string
          description: Snapshot migration
      - name: instancesnapshotput
        method: PUT
        description: Update snapshot
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: name
          in: path
          type: string
          description: Instance name
          required: true
        - name: snapshot
          in: path
          type: string
          description: Snapshot name
          required: true
        - name: project
          in: query
          type: string
          description: Project name
        - name: snapshot
          in: body
          type: string
          description: Snapshot update
    - name: 1.0-instances-name-snapshots?recursion=1
      path: /1.0/instances/{name}/snapshots?recursion=1
      operations:
      - name: instancesnapshotsgetrecursion1
        method: GET
        description: Get the snapshots
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: name
          in: path
          type: string
          description: Instance name
          required: true
        - name: project
          in: query
          type: string
          description: Project name
    - name: 1.0-instances-name-state
      path: /1.0/instances/{name}/state
      operations:
      - name: instancestateget
        method: GET
        description: Get the runtime state
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: name
          in: path
          type: string
          description: Instance name
          required: true
        - name: project
          in: query
          type: string
          description: Project name
      - name: instancestateput
        method: PUT
        description: Change the state
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: name
          in: path
          type: string
          description: Instance name
          requ

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