Incus REST API

definitions:
    Access:
        items:
            $ref: '#/definitions/AccessEntry'
        title: Access represents everyone that may access a particular resource.
        type: array
        x-go-package: github.com/lxc/incus/v7/shared/api
    AccessEntry:
        properties:
            identifier:
                description: Certificate fingerprint
                example: 636b69519d27ae3b0e398cb7928043846ce1e3842f0ca7a589993dd913ab8cc9
                type: string
                x-go-name: Identifier
            provider:
                description: Which authorization method the certificate uses
                example: tls, openfga
                type: string
                x-go-name: Provider
            role:
                description: The role associated with the certificate
                example: admin, view, operator
                type: string
                x-go-name: Role
        title: AccessEntry represents an entity having access to the resource.
        type: object
        x-go-package: github.com/lxc/incus/v7/shared/api
    BackupTarget:
        properties:
            access_key:
                description: AccessKey is the S3 API access key
                example: GOOG1234
                type: string
                x-go-name: AccessKey
            bucket_name:
                description: BucketName is the name of the S3 bucket.
                example: my_bucket
                type: string
                x-go-name: BucketName
            path:
                description: Path is the target path.
                example: foo/test.tar
                type: string
                x-go-name: Path
            protocol:
                description: Protocol is the upload protocol.
                example: S3
                type: string
                x-go-name: Protocol
            secret_key:
                description: SecretKey is the S3 API access key
                example: secret123
                type: string
                x-go-name: SecretKey
            url:
                description: URL is the HTTPS URL for the backup
                example: https://storage.googleapis.com
                type: string
                x-go-name: URL
        title: BackupTarget represents the target storage server for an instance or volume backup.
        type: object
        x-go-package: github.com/lxc/incus/v7/shared/api
    Certificate:
        description: Certificate represents a certificate
        properties:
            certificate:
                description: The certificate itself, as PEM encoded X509 (or as base64 encoded X509 on POST)
                example: X509 PEM certificate
                type: string
                x-go-name: Certificate
            description:
                description: Certificate description
                example: X509 certificate
                type: string
                x-go-name: Description
            fingerprint:
                description: SHA256 fingerprint of the certificate
                example: fd200419b271f1dc2a5591b693cc5774b7f234e1ff8c6b78ad703b6888fe2b69
                readOnly: true
                type: string
                x-go-name: Fingerprint
            name:
                description: Name associated with the certificate
                example: castiana
                type: string
                x-go-name: Name
            projects:
                description: List of allowed projects (applies when restricted)
                example:
                    - default
                    - foo
                    - bar
                items:
                    type: string
                type: array
                x-go-name: Projects
            restricted:
                description: Whether to limit the certificate to listed projects
                example: true
                type: boolean
                x-go-name: Restricted
            type:
                description: Usage type for the certificate
                example: client
                type: string
                x-go-name: Type
        type: object
        x-go-package: github.com/lxc/incus/v7/shared/api
    CertificateAddToken:
        properties:
            addresses:
                description: The addresses of the server
                example:
                    - 10.98.30.229:8443
                items:
                    type: string
                type: array
                x-go-name: Addresses
            client_name:
                description: The name of the new client
                example: user@host
                type: string
                x-go-name: ClientName
            expires_at:
                description: The token's expiry date.
                example: "2021-03-23T17:38:37.753398689-04:00"
                format: date-time
                type: string
                x-go-name: ExpiresAt
            fingerprint:
                description: The fingerprint of the network certificate
                example: 57bb0ff4340b5bb28517e062023101adf788c37846dc8b619eb2c3cb4ef29436
                type: string
                x-go-name: Fingerprint
            secret:
                description: The random join secret
                example: 2b2284d44db32675923fe0d2020477e0e9be11801ff70c435e032b97028c35cd
                type: string
                x-go-name: Secret
        title: CertificateAddToken represents the fields contained within an encoded certificate add token.
        type: object
        x-go-package: github.com/lxc/incus/v7/shared/api
    CertificatePut:
        description: CertificatePut represents the modifiable fields of a certificate
        properties:
            certificate:
                description: The certificate itself, as PEM encoded X509 (or as base64 encoded X509 on POST)
                example: X509 PEM certificate
                type: string
                x-go-name: Certificate
            description:
                description: Certificate description
                example: X509 certificate
                type: string
                x-go-name: Description
            name:
                description: Name associated with the certificate
                example: castiana
                type: string
                x-go-name: Name
            projects:
                description: List of allowed projects (applies when restricted)
                example:
                    - default
                    - foo
                    - bar
                items:
                    type: string
                type: array
                x-go-name: Projects
            restricted:
                description: Whether to limit the certificate to listed projects
                example: true
                type: boolean
                x-go-name: Restricted
            type:
                description: Usage type for the certificate
                example: client
                type: string
                x-go-name: Type
        type: object
        x-go-package: github.com/lxc/incus/v7/shared/api
    CertificatesPost:
        description: CertificatesPost represents the fields of a new certificate
        properties:
            certificate:
                description: The certificate itself, as PEM encoded X509 (or as base64 encoded X509 on POST)
                example: X509 PEM certificate
                type: string
                x-go-name: Certificate
            description:
                description: Certificate description
                example: X509 certificate
                type: string
                x-go-name: Description
            name:
                description: Name associated with the certificate
                example: castiana
                type: string
                x-go-name: Name
            projects:
                description: List of allowed projects (applies when restricted)
                example:
                    - default
                    - foo
                    - bar
                items:
                    type: string
                type: array
                x-go-name: Projects
            restricted:
                description: Whether to limit the certificate to listed projects
                example: true
                type: boolean
                x-go-name: Restricted
            token:
                description: Whether to create a certificate add token
                example: true
                type: boolean
                x-go-name: Token
            trust_token:
                description: Trust token (used to add an untrusted client)
                example: blah
                type: string
                x-go-name: TrustToken
            type:
                description: Usage type for the certificate
                example: client
                type: string
                x-go-name: Type
        type: object
        x-go-package: github.com/lxc/incus/v7/shared/api
    Cluster:
        properties:
            enabled:
                description: Whether clustering is enabled
                example: true
                type: boolean
                x-go-name: Enabled
            member_config:
                description: List of member configuration keys (used during join)
                example: []
                items:
                    $ref: '#/definitions/ClusterMemberConfigKey'
                type: array
                x-go-name: MemberConfig
            server_name:
                description: Name of the cluster member answering the request
                example: server01
                type: string
                x-go-name: ServerName
        title: Cluster represents high-level information about a cluster.
        type: object
        x-go-package: github.com/lxc/incus/v7/shared/api
    ClusterCertificatePut:
        description: ClusterCertificatePut represents the certificate and key pair for all cluster members
        properties:
            cluster_certificate:
                description: The new certificate (X509 PEM encoded) for the cluster
                example: X509 PEM certificate
                type: string
                x-go-name: ClusterCertificate
            cluster_certificate_key:
                description: The new certificate key (X509 PEM encoded) for the cluster
                example: X509 PEM certificate key
                type: string
                x-go-name: ClusterCertificateKey
        type: object
        x-go-package: github.com/lxc/incus/v7/shared/api
    ClusterGroup:
        properties:
            config:
                description: Cluster group configuration map
                example:
                    user.mykey: foo
                type: object
                x-go-name: Config
            description:
                description: The description of the cluster group
                example: amd64 servers
                type: string
                x-go-name: Description
            members:
                description: List of members in this group
                example:
                    - server01
                    - server02
                items:
                    type: string
                type: array
                x-go-name: Members
            name:
                description: The new name of the cluster group
                example: group1
                type: string
                x-go-name: Name
            used_by:
                description: List of URLs of objects using this cluster group
                example:
                    - /1.0/cluster/members/server01
                    - /1.0/project/default
                items:
                    type: string
                readOnly: true
                type: array
                x-go-name: UsedBy
        title: ClusterGroup represents a cluster group.
        type: object
        x-go-package: github.com/lxc/incus/v7/shared/api
    ClusterGroupPost:
        properties:
            name:
                description: The new name of the cluster group
                example: group1
                type: string
                x-go-name: Name
        title: ClusterGroupPost represents the fields required to rename a cluster group.
        type: object
        x-go-package: github.com/lxc/incus/v7/shared/api
    ClusterGroupPut:
        properties:
            config:
                description: Cluster group configuration map
                example:
                    user.mykey: foo
                type: object
                x-go-name: Config
            description:
                description: The description of the cluster group
                example: amd64 servers
                type: string
                x-go-name: Description
            members:
                description: List of members in this group
                example:
                    - server01
                    - server02
                items:
                    type: string
                type: array
                x-go-name: Members
        title: ClusterGroupPut represents the modifiable fields of a cluster group.
        type: object
        x-go-package: github.com/lxc/incus/v7/shared/api
    ClusterGroupsPost:
        properties:
            config:
                description: Cluster group configuration map
                example:
                    user.mykey: foo
                type: object
                x-go-name: Config
            description:
                description: The description of the cluster group
                example: amd64 servers
                type: string
                x-go-name: Description
            members:
                description: List of members in this group
                example:
                    - server01
                    - server02
                items:
                    type: string
                type: array
                x-go-name: Members
            name:
                description: The new name of the cluster group
                example: group1
                type: string
                x-go-name: Name
        title: ClusterGroupsPost represents the fields available for a new cluster group.
        type: object
        x-go-package: github.com/lxc/incus/v7/shared/api
    ClusterMember:
        properties:
            architecture:
                description: The primary architecture of the cluster member
                example: x86_64
                type: string
                x-go-name: Architecture
            config:
                description: Additional configuration information
                example:
                    scheduler.instance: all
                type: object
                x-go-name: Config
            database:
                description: Whether the cluster member is a database server
                example: true
                type: boolean
                x-go-name: Database
            description:
                description: Cluster member description
                example: AMD Epyc 32c/64t
                type: string
                x-go-name: Description
            failure_domain:
                description: Name of the failure domain for this cluster member
                example: rack1
                type: string
                x-go-name: FailureDomain
            groups:
                description: List of cluster groups this member belongs to
                example:
                    - group1
                    - group2
                items:
                    type: string
                type: array
                x-go-name: Groups
            message:
                description: Additional status information
                example: fully operational
                type: string
                x-go-name: Message
            roles:
                description: List of roles held by this cluster member
                example:
                    - database
                items:
                    type: string
                type: array
                x-go-name: Roles
            server_name:
                description: Name of the cluster member
                example: server01
                type: string
                x-go-name: ServerName
            status:
                description: Current status
                example: Online
                type: string
                x-go-name: Status
            url:
                description: URL at which the cluster member can be reached
                example: https://10.0.0.1:8443
                type: string
                x-go-name: URL
        title: ClusterMember represents a member of a cluster.
        type: object
        x-go-package: github.com/lxc/incus/v7/shared/api
    ClusterMemberConfigKey:
        description: |-
            The Value field is empty when getting clustering information with GET
            1.0/cluster, and should be filled by the joining server when performing a PUT
            1.0/cluster join request.
        properties:
            description:
                description: A human friendly description key
                example: '"source" property for storage pool "local"'
                type: string
                x-go-name: Description
            entity:
                description: The kind of configuration key (network, storage-pool, ...)
                example: storage-pool
                type: string
                x-go-name: Entity
            key:
                description: The name of the key
                example: source
                type: string
                x-go-name: Key
            name:
                description: The name of the object requiring this key
                example: local
                type: string
                x-go-name: Name
            value:
                description: The value on the answering cluster member
                example: /dev/sdb
                type: string
                x-go-name: Value
        title: |-
            ClusterMemberConfigKey represents a single config key that a new member of
            the cluster is required to provide when joining.
        type: object
        x-go-package: github.com/lxc/incus/v7/shared/api
    ClusterMemberJoinToken:
        properties:
            addresses:
                description: The addresses of existing online cluster members
                example:
                    - 10.98.30.229:8443
                items:
                    type: string
                type: array
                x-go-name: Addresses
            expires_at:
                description: The token's expiry date.
                example: "2021-03-23T17:38:37.753398689-04:00"
                format: date-time
                type: string
                x-go-name: ExpiresAt
            fingerprint:
                description: The fingerprint of the network certificate
                example: 57bb0ff4340b5bb28517e062023101adf788c37846dc8b619eb2c3cb4ef29436
                type: string
                x-go-name: Fingerprint
            secret:
                description: The random join secret.
                example: 2b2284d44db32675923fe0d2020477e0e9be11801ff70c435e032b97028c35cd
                type: string
                x-go-name: Secret
            server_name:
                description: The name of the new cluster member
                example: server02
                type: string
                x-go-name: ServerName
        title: ClusterMemberJoinToken represents the fields contained within an encoded cluster member join token.
        type: object
        x-go-package: github.com/lxc/incus/v7/shared/api
    ClusterMemberPost:
        properties:
            server_name:
                description: The new name of the cluster member
                example: server02
                type: string
                x-go-name: ServerName
        title: ClusterMemberPost represents the fields required to rename a cluster member.
        type: object
        x-go-package: github.com/lxc/incus/v7/shared/api
    ClusterMemberPut:
        description: ClusterMemberPut represents the modifiable fields of a cluster member
        properties:
            config:
                description: Additional configuration information
                example:
                    scheduler.instance: all
                type: object
                x-go-name: Config
            description:
                description: Cluster member description
                example: AMD Epyc 32c/64t
                type: string
                x-go-name: Description
            failure_domain:
                description: Name of the failure domain for this cluster member
                example: rack1
                type: string
                x-go-name: FailureDomain
            groups:
                description: List of cluster groups this member belongs to
                example:
                    - group1
                    - group2
                items:
                    type: string
                type: array
                x-go-name: Groups
            roles:
                description: List of roles held by this cluster member
                example:
                    - database
                items:
                    type: string
                type: array
                x-go-name: Roles
        type: object
        x-go-package: github.com/lxc/incus/v7/shared/api
    ClusterMemberState:
        properties:
            storage_pools:
                additionalProperties:
                    $ref: '#/definitions/StoragePoolState'
                type: object
                x-go-name: StoragePools
            sysinfo:
                $ref: '#/definitions/ClusterMemberSysInfo'
        title: ClusterMemberState represents the state of a cluster member.
        type: object
        x-go-package: github.com/lxc/incus/v7/shared/api
    ClusterMemberStatePost:
        properties:
            action:
                description: The action to be performed. Valid actions are "evacuate" and "restore".
                example: evacuate
                type: string
                x-go-name: Action
            mode:
                description: Override the configured evacuation mode.
                example: stop
                type: string
                x-go-name: Mode
        title: ClusterMemberStatePost represents the fields required to evacuate a cluster member.
        type: object
        x-go-package: github.com/lxc/incus/v7/shared/api
    ClusterMemberSysInfo:
        properties:
            buffered_ram:
                format: uint64
                type: integer
                x-go-name: BufferRAM
            free_ram:
                format: uint64
                type: integer
                x-go-name: FreeRAM
            free_swap:
                format: uint64
                type: integer
                x-go-name: FreeSwap
            load_averages:
                items:
                    format: double
                    type: number
                type: array
                x-go-name: LoadAverages
            processes:
                format: uint16
                type: integer
                x-go-name: Processes
            shared_ram:
                format: uint64
                type: integer
                x-go-name: SharedRAM
            total_ram:
                format: uint64
                type: integer
                x-go-name: TotalRAM
            total_swap:
                format: uint64
                type: integer
                x-go-name: TotalSwap
            uptime:
                format: int64
                type: integer
                x-go-name: Uptime
        title: ClusterMemberSysInfo represents the sysinfo of a cluster member.
        type: object
        x-go-package: github.com/lxc/incus/v7/shared/api
    ClusterMembersPost:
        properties:
            server_name:
                description: The name of the new cluster member
                example: server02
                type: string
                x-go-name: ServerName
        title: ClusterMembersPost represents the fields required to request a join token to add a member to the cluster.
        type: object
        x-go-package: github.com/lxc/incus/v7/shared/api
    ClusterPut:
        properties:
            cluster_address:
                description: The address of the cluster you wish to join
                example: 10.0.0.1:8443
                type: string
                x-go-name: ClusterAddress
            cluster_certificate:
                description: The expected certificate (X509 PEM encoded) for the cluster
                example: X509 PEM certificate
                type: string
                x-go-name: ClusterCertificate
            cluster_token:
                description: The cluster join token for the cluster you're trying to join
                example: blah
                type: string
                x-go-name: ClusterToken
            enabled:
                description: Whether clustering is enabled
                example: true
                type: boolean
                x-go-name: Enabled
            member_config:
                description: List of member configuration keys (used during join)
                example: []
                items:
                    $ref: '#/definitions/ClusterMemberConfigKey'
                type: array
                x-go-name: MemberConfig
            server_address:
                description: The local address to use for cluster communication
                example: 10.0.0.2:8443
                type: string
                x-go-name: ServerAddress
            server_name:
                description: Name of the cluster member answering the request
                example: server01
                type: string
                x-go-name: ServerName
        title: ClusterPut represents the fields required to bootstrap or join a cluster.
        type: object
        x-go-package: github.com/lxc/incus/v7/shared/api
    ConfigMap:
        additionalProperties:
            type: string
        description: |-
            ConfigMap type is used to hold incus config. In contrast to plain
            map[string]string it provides unmarshal methods for JSON and YAML, which
            gracefully handle numbers and bools.
        type: object
        x-go-package: github.com/lxc/incus/v7/shared/api
    DevicesMap:
        additionalProperties:
            additionalProperties:
                type: string
            type: object
        description: |-
            DevicesMap type is used to hold incus devices configurations. In contrast to
            plain map[string]map[string]string it provides unmarshal methods for JSON and
            YAML, which gracefully handle numbers and bools.
        type: object
        x-go-package: github.com/lxc/incus/v7/shared/api
    Event:
        description: Event represents an event entry (over websocket)
        properties:
            location:
                description: Originating cluster member
                example: server01
                type: string
                x-go-name: Location
            metadata:
                description: JSON encoded metadata (see EventLogging, EventLifecycle or Operation)
                example:
                    action: instance-started
                    context: {}
                    source: /1.0/instances/c1
                type: object
                x-go-name: Metadata
            project:
                description: Project the event belongs to.
                example: default
                type: string
                x-go-name: Project
            timestamp:
                description: Time at which the event was sent
                example: "2021-02-24T19:00:45.452649098-05:00"
                format: date-time
                type: string
                x-go-name: Timestamp
            type:
                description: Event type (one of operation, logging or lifecycle)
                example: lifecycle
                type: string
                x-go-name: Type
        type: object
        x-go-package: github.com/lxc/incus/v7/shared/api
    Image:
        description: Image represents an image
        properties:
            aliases:
                description: List of aliases
                items:
                    $ref: '#/definitions/ImageAlias'
                type: array
                x-go-name: Aliases
            architecture:
                description: Architecture
                example: x86_64
                type: string
                x-go-name: Architecture
            auto_update:
                description: Whether the image should auto-update when a new build is available
                example: true
                type: boolean
                x-go-name: AutoUpdate
            cached:
                description: Whether the image is an automatically cached remote image
                example: true
                type: boolean
                x-go-name: Cached
            created_at:
                description: When the image was originally created
                example: "2021-03-23T20:00:00-04:00"
                format: date-time
                type: string
                x-go-name: CreatedAt
            expires_at:
                description: When the image becomes obsolete
                example: "2025-03-23T20:00:00-04:00"
                format: date-time
                type: string
                x-go-name: ExpiresAt
            filename:
                description: Original filename
                example: 06b86454720d36b20f94e31c6812e05ec51c1b568cf3a8abd273769d213394bb.rootfs
                type: string
                x-go-name: Filename
            fingerprint:
                description: Full SHA-256 fingerprint
                example: 06b86454720d36b20f94e31c6812e05ec51c1b568cf3a8abd273769d213394bb
                type: string
                x-go-name: Fingerprint
            last_used_at:
                description: Last time the image was used
                example: "2021-03-22T20:39:00.575185384-04:00"
                format: date-time
                type: string
                x-go-name: LastUsedAt
            profiles:
                description: List of profiles to use when creating from this image (if none provided by user)
                example:
                    - default
                items:
                    type: string
                type: array
                x-go-name: Profiles
            project:
                description: Project name
                example: project1
                type: string
                x-go-name: Project
            properties:
                additionalProperties:
                    type: string
                description: Descriptive properties
                example:
                    os: Ubuntu
                    release: jammy
                    variant: cloud
                type: object
                x-go-name: Properties
            public:
                description: Whether the image is available to unauthenticated users
                example: false
                type: boolean
                x-go-name: Public
            size:
                description: Size of the image in bytes
                example: 272237676
                format: int64
                type: integer
                x-go-name: Size
            type:
                description: Type of image (container or virtual-machine)
                example: container
                type: string
                x-go-name: Type
            update_source:
                $ref: '#/definitions/ImageSource'
            uploaded_at:
                description: When the image was added to this server
                example: "2021-03-24T14:18:15.115036787-04:00"
                format: date-time
                type: string
                x-go-name: UploadedAt
        type: object
        x-go-package: github.com/lxc/incus/v7/shared/api
    ImageAlias:
        description: ImageAlias represents an alias from the alias list of an image
        properties:
            description:
                description: Description of the alias
                example: Our preferred Ubuntu image
                type: string
                x-go-name: Description
            name:
                description: Name of the alias
                example: ubuntu-22.04
                type: string
                x-go-name: Name
        type: object
        x-go-package: github.com/lxc/incus/

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