Incus external REST API

naftiko: 1.0.0-alpha2
info:
  label: Incus external REST API
  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.
  tags:
  - Incus
  - API
  created: '2026-05-06'
  modified: '2026-05-06'
capability:
  consumes:
  - type: http
    namespace: incus
    baseUri: https://api.example.com
    description: Incus external REST API HTTP API.
    resources:
    - name: resource
      path: /
      operations:
      - name: api-get
        method: GET
        description: Get the supported API endpoints
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
    - name: 1-0
      path: /1.0
      operations:
      - name: server-get
        method: GET
        description: Get the server environment and configuration
        inputParameters:
        - name: target
          in: query
          type: string
          description: Cluster member name
        - name: project
          in: query
          type: string
          description: Project name
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
      - name: server-patch
        method: PATCH
        description: Partially update the server configuration
        inputParameters:
        - name: target
          in: query
          type: string
          description: Cluster member name
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
      - name: server-put
        method: PUT
        description: Update the server configuration
        inputParameters:
        - name: target
          in: query
          type: string
          description: Cluster member name
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
    - name: 1-0-certificates
      path: /1.0/certificates
      operations:
      - name: certificates-get
        method: GET
        description: Get the trusted certificates
        inputParameters:
        - name: filter
          in: query
          type: string
          description: Collection filter
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
      - name: certificates-post
        method: POST
        description: Add a trusted certificate
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
    - name: 1-0-certificates-fingerprint
      path: /1.0/certificates/{fingerprint}
      operations:
      - name: certificate-delete
        method: DELETE
        description: Delete the trusted certificate
        inputParameters:
        - name: fingerprint
          in: path
          type: string
          required: true
          description: Fingerprint
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
      - name: certificate-get
        method: GET
        description: Get the trusted certificate
        inputParameters:
        - name: fingerprint
          in: path
          type: string
          required: true
          description: Fingerprint
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
      - name: certificate-patch
        method: PATCH
        description: Partially update the trusted certificate
        inputParameters:
        - name: fingerprint
          in: path
          type: string
          required: true
          description: Fingerprint
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
      - name: certificate-put
        method: PUT
        description: Update the trusted certificate
        inputParameters:
        - name: fingerprint
          in: path
          type: string
          required: true
          description: Fingerprint
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
    - name: 1-0-certificates-public
      path: /1.0/certificates?public
      operations:
      - name: certificates-post-untrusted
        method: POST
        description: Add a trusted certificate
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
    - name: 1-0-certificates-recursion-1
      path: /1.0/certificates?recursion=1
      operations:
      - name: certificates-get-recursion1
        method: GET
        description: Get the trusted certificates
        inputParameters:
        - name: filter
          in: query
          type: string
          description: Collection filter
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
    - name: 1-0-cluster
      path: /1.0/cluster
      operations:
      - name: cluster-get
        method: GET
        description: Get the cluster configuration
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
      - name: cluster-put
        method: PUT
        description: Update the cluster configuration
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
    - name: 1-0-cluster-certificate
      path: /1.0/cluster/certificate
      operations:
      - name: clustering-update-cert
        method: PUT
        description: Update the certificate for the cluster
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
    - name: 1-0-cluster-groups
      path: /1.0/cluster/groups
      operations:
      - name: cluster-groups-get
        method: GET
        description: Get the cluster groups
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
      - name: cluster-groups-post
        method: POST
        description: Create a cluster group.
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
    - name: 1-0-cluster-groups-name
      path: /1.0/cluster/groups/{name}
      operations:
      - name: cluster-group-delete
        method: DELETE
        description: Delete the cluster group.
        inputParameters:
        - name: name
          in: path
          type: string
          required: true
          description: Cluster group name
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
      - name: cluster-group-get
        method: GET
        description: Get the cluster group
        inputParameters:
        - name: name
          in: path
          type: string
          required: true
          description: Cluster group name
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
      - name: cluster-group-patch
        method: PATCH
        description: Update the cluster group
        inputParameters:
        - name: name
          in: path
          type: string
          required: true
          description: Cluster group name
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
      - name: cluster-group-post
        method: POST
        description: Rename the cluster group
        inputParameters:
        - name: name
          in: path
          type: string
          required: true
          description: Cluster group name
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
      - name: cluster-group-put
        method: PUT
        description: Update the cluster group
        inputParameters:
        - name: name
          in: path
          type: string
          required: true
          description: Cluster group name
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
    - name: 1-0-cluster-groups-recursion-1
      path: /1.0/cluster/groups?recursion=1
      operations:
      - name: cluster-groups-get-recursion1
        method: GET
        description: Get the cluster groups
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
    - name: 1-0-cluster-members
      path: /1.0/cluster/members
      operations:
      - name: cluster-members-get
        method: GET
        description: Get the cluster members
        inputParameters:
        - name: filter
          in: query
          type: string
          description: Collection filter
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
      - name: cluster-members-post
        method: POST
        description: Request a join token
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
    - name: 1-0-cluster-members-name
      path: /1.0/cluster/members/{name}
      operations:
      - name: cluster-member-delete
        method: DELETE
        description: Delete the cluster member
        inputParameters:
        - name: name
          in: path
          type: string
          required: true
          description: Cluster member name
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
      - name: cluster-member-get
        method: GET
        description: Get the cluster member
        inputParameters:
        - name: name
          in: path
          type: string
          required: true
          description: Cluster member name
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
      - name: cluster-member-patch
        method: PATCH
        description: Partially update the cluster member
        inputParameters:
        - name: name
          in: path
          type: string
          required: true
          description: Cluster member name
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
      - name: cluster-member-post
        method: POST
        description: Rename the cluster member
        inputParameters:
        - name: name
          in: path
          type: string
          required: true
          description: Cluster member name
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
      - name: cluster-member-put
        method: PUT
        description: Update the cluster member
        inputParameters:
        - name: name
          in: path
          type: string
          required: true
          description: Cluster member name
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
    - name: 1-0-cluster-members-name-state
      path: /1.0/cluster/members/{name}/state
      operations:
      - name: cluster-member-state-get
        method: GET
        description: Get state of the cluster member
        inputParameters:
        - name: name
          in: path
          type: string
          required: true
          description: Cluster member name
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
      - name: cluster-member-state-post
        method: POST
        description: Evacuate or restore a cluster member
        inputParameters:
        - name: name
          in: path
          type: string
          required: true
          description: Cluster member name
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
    - name: 1-0-cluster-members-recursion-1
      path: /1.0/cluster/members?recursion=1
      operations:
      - name: cluster-members-get-recursion1
        method: GET
        description: Get the cluster members
        inputParameters:
        - name: filter
          in: query
          type: string
          description: Collection filter
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
    - name: 1-0-events
      path: /1.0/events
      operations:
      - name: events-get
        method: GET
        description: Get the event stream
        inputParameters:
        - name: project
          in: query
          type: string
          description: Project name
        - name: type
          in: query
          type: string
          description: Event type(s), comma separated (valid types are logging, operation or lifecycle)
        - name: all-projects
          in: query
          type: string
          description: Retrieve instances from all projects
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
    - name: 1-0-images
      path: /1.0/images
      operations:
      - name: images-get
        method: GET
        description: Get the images
        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: string
          description: Retrieve images from all projects
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
      - name: images-post
        method: POST
        description: Add an image
        inputParameters:
        - name: project
          in: query
          type: string
          description: Project name
        - name: X-Incus-secret
          in: header
          type: string
          description: Push secret for server to server communication
        - name: X-Incus-fingerprint
          in: header
          type: string
          description: Expected fingerprint when pushing a raw image
        - name: X-Incus-aliases
          in: header
          type: array
          description: List of aliases to assign
        - name: X-Incus-properties
          in: header
          type: object
          description: Descriptive properties
        - name: X-Incus-public
          in: header
          type: boolean
          description: Whether the image is available to unauthenticated users
        - name: X-Incus-filename
          in: header
          type: string
          description: Original filename of the image
        - name: X-Incus-profiles
          in: header
          type: array
          description: List of profiles to use
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
    - name: 1-0-images-fingerprint
      path: /1.0/images/{fingerprint}
      operations:
      - name: image-delete
        method: DELETE
        description: Delete the image
        inputParameters:
        - name: fingerprint
          in: path
          type: string
          required: true
          description: Fingerprint
        - name: project
          in: query
          type: string
          description: Project name
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
      - name: image-get
        method: GET
        description: Get the image
        inputParameters:
        - name: fingerprint
          in: path
          type: string
          required: true
          description: Fingerprint
        - name: project
          in: query
          type: string
          description: Project name
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
      - name: image-patch
        method: PATCH
        description: Partially update the image
        inputParameters:
        - name: fingerprint
          in: path
          type: string
          required: true
          description: Fingerprint
        - name: project
          in: query
          type: string
          description: Project name
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
      - name: image-put
        method: PUT
        description: Update the image
        inputParameters:
        - name: fingerprint
          in: path
          type: string
          required: true
          description: Fingerprint
        - name: project
          in: query
          type: string
          description: Project name
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
    - name: 1-0-images-fingerprint-export
      path: /1.0/images/{fingerprint}/export
      operations:
      - name: image-export-get
        method: GET
        description: Get the raw image file(s)
        inputParameters:
        - name: fingerprint
          in: path
          type: string
          required: true
          description: Fingerprint
        - name: project
          in: query
          type: string
          description: Project name
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
      - name: images-export-post
        method: POST
        description: Make the server push the image to a remote server
        inputParameters:
        - name: fingerprint
          in: path
          type: string
          required: true
          description: Fingerprint
        - name: project
          in: query
          type: string
          description: Project name
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
    - name: 1-0-images-fingerprint-export-public
      path: /1.0/images/{fingerprint}/export?public
      operations:
      - name: image-export-get-untrusted
        method: GET
        description: Get the raw image file(s)
        inputParameters:
        - name: fingerprint
          in: path
          type: string
          required: true
          description: Fingerprint
        - name: project
          in: query
          type: string
          description: Project name
        - name: secret
          in: query
          type: string
          description: Secret token to retrieve a private image
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
    - name: 1-0-images-fingerprint-refresh
      path: /1.0/images/{fingerprint}/refresh
      operations:
      - name: images-refresh-post
        method: POST
        description: Refresh an image
        inputParameters:
        - name: fingerprint
          in: path
          type: string
          required: true
          description: Fingerprint
        - name: project
          in: query
          type: string
          description: Project name
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
    - name: 1-0-images-fingerprint-secret
      path: /1.0/images/{fingerprint}/secret
      operations:
      - name: images-secret-post
        method: POST
        description: Generate secret for retrieval of the image by an untrusted client
        inputParameters:
        - name: fingerprint
          in: path
          type: string
          required: true
          description: Fingerprint
        - name: project
          in: query
          type: string
          description: Project name
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
    - name: 1-0-images-fingerprint-public
      path: /1.0/images/{fingerprint}?public
      operations:
      - name: image-get-untrusted
        method: GET
        description: Get the public image
        inputParameters:
        - name: fingerprint
          in: path
          type: string
          required: true
          description: Fingerprint
        - name: project
          in: query
          type: string
          description: Project name
        - name: secret
          in: query
          type: string
          description: Secret token to retrieve a private image
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
    - name: 1-0-images-aliases
      path: /1.0/images/aliases
      operations:
      - name: images-aliases-get
        method: GET
        description: Get the image aliases
        inputParameters:
        - name: project
          in: query
          type: string
          description: Project name
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
      - name: images-aliases-post
        method: POST
        description: Add an image alias
        inputParameters:
        - name: project
          in: query
          type: string
          description: Project name
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
    - name: 1-0-images-aliases-name
      path: /1.0/images/aliases/{name}
      operations:
      - name: image-alias-delete
        method: DELETE
        description: Delete the image alias
        inputParameters:
        - name: name
          in: path
          type: string
          required: true
          description: Alias name
        - name: project
          in: query
          type: string
          description: Project name
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
      - name: image-alias-get
        method: GET
        description: Get the image alias
        inputParameters:
        - name: name
          in: path
          type: string
          required: true
          description: Alias name
        - name: project
          in: query
          type: string
          description: Project name
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
      - name: images-alias-patch
        method: PATCH
        description: Partially update the image alias
        inputParameters:
        - name: name
          in: path
          type: string
          required: true
          description: Alias name
        - name: project
          in: query
          type: string
          description: Project name
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
      - name: images-alias-post
        method: POST
        description: Rename the image alias
        inputParameters:
        - name: name
          in: path
          type: string
          required: true
          description: Alias name
        - name: project
          in: query
          type: string
          description: Project name
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
      - name: images-aliases-put
        method: PUT
        description: Update the image alias
        inputParameters:
        - name: name
          in: path
          type: string
          required: true
          description: Alias name
        - name: project
          in: query
          type: string
          description: Project name
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
    - name: 1-0-images-aliases-name-public
      path: /1.0/images/aliases/{name}?public
      operations:
      - name: image-alias-get-untrusted
        method: GET
        description: Get the public image alias
        inputParameters:
        - name: name
          in: path
          type: string
          required: true
          description: Alias name
        - name: project
          in: query
          type: string
          description: Project name
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
    - name: 1-0-images-aliases-recursion-1
      path: /1.0/images/aliases?recursion=1
      operations:
      - name: images-aliases-get-recursion1
        method: GET
        description: Get the image aliases
        inputParameters:
        - name: project
          in: query
          type: string
          description: Project name
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
    - name: 1-0-images-public
      path: /1.0/images?public
      operations:
      - name: images-get-untrusted
        method: GET
        description: Get the public images
        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: string
          description: Retrieve images from all projects
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
      - name: images-post-untrusted
        method: POST
        description: Add an image
        inputParameters:
        - name: project
          in: query
          type: string
          description: Project name
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
    - name: 1-0-images-public-recursion-1
      path: /1.0/images?public&recursion=1
      operations:
      - name: images-get-recursion1-untrusted
        method: GET
        description: Get the public images
        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: string
          description: Retrieve images from all projects
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
    - name: 1-0-images-recursion-1
      path: /1.0/images?recursion=1
      operations:
      - name: images-get-recursion1
        method: GET
        description: Get the images
        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: string
          description: Retrieve images from all projects
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
    - name: 1-0-instances
      path: /1.0/instances
      operations:
      - name: instances-get
        method: GET
        description: Get the instances
        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: string
          description: Retrieve instances from all projects
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
  exposes:
  - type: rest
    port: 8080
    namespace: incus-rest
    description: REST adapter for Incus external REST API.
    resources:
    - path: /
      name: api-get
      operations:
      - method: GET
        name: api-get
        description: Get the supported API endpoints
        call: incus.api-get
        outputParameters:
        - type: object
          mapping: $.
    - path: /1.0
      name: server-get
      operations:
      - method: GET
        name: server-get
        description: Get the server environment and configuration
        call: incus.server-get
        outputParameters:
        - type: object
          mapping: $.
    - path: /1.0
      name: server-patch
      operations:
      - method: PATCH
        name: server-patch
        description: Partially update the server configuration
        call: incus.server-patch
        outputParameters:
        - type: object
          mapping: $.
    - path: /1.0
      name: server-put
      operations:
      - method: PUT
        name: server-put
        description: Update the server configuration
        call: incus.server-put
        outputParameters:
        - type: object
          mapping: $.
    - path: /1.0/certificates
      name: certificates-get
      operations:
      - method: GET
        name: certificates-get
        description: Get the trusted certificates
        call: incus.certificates-get
        outputParameters:
        - type: object
          mapping: $.
    - path: /1.0/certificates
      name: certificates-post
      operations:
      - method: POST
        name: certificates-post
        description: Add a trusted certificate
        call: incus.certificates-post
        outputParameters:
        - type: object
          mapping: $.
    - path: /1.0/certificates/{fingerprint}
      name: certificate-delete
      operations:
      - method: DELETE
        name: certificate-delete
        description: Delete the trusted certificate
        call: incus.certificate-delete
        with:
          fingerprint: rest.fingerprint
        outputParameters:
        - type: object
          mapping: $.
    - path: /1.0/certificates/{fingerprint}
      name: certificate-get
      operations:
      - method: GET
        name: certificate-get
        description: Get the trusted certificate
        call: incus.certificate-get
        with:
          fingerprint: rest.fingerprint
        outputParameters:
        - type: object
          mapping: $.
    - path: /1.0/certificates/{fingerprint}
      name: certificate-patch
      operations:
      - method: PATCH
        name: certificate-patch
        description: Partially update the trusted certificate
        call: incus.certificate-patch
        with:
          fingerprint: rest.fingerprint
        outputParameters:
        - type: object
          mapping: $.
    - path: /1.0/certificates/{fingerprint}
      name: certificate-put
      operations:
      - method: PUT
        name: certificate-put
        description: Update the trusted certificate
        call: incus.certificate-put
        with:
          fingerprint: rest.fingerprint
        outputParameters:
        - type: object
          mapping: $.
    - path: /1.0/certificates?public
      name: certificates-post-untrusted
      operations:
      - method: POST
        name: certificates-post-untrusted
        description: Add a trusted certificate
        call: incus.certificates-post-untrusted
        outputParameters:
        - type: object
          mapping: $.
    - path: /1.0/certificates?recursion=1
      name: certificates-get-recursion1
      operations:
      - method: GET
        name: certificates-get-recursion1
        description: Get the trusted certificates
        call: incus.certificates-get-recursion1
        outputParameters:
        - type: object
          mapping: $.
    - path: /1.0/cluster
      name: cluster-get
      operations:
      - method: GET
        name: cluster-get
        description: Get the cluster configuration
        call: incus.cluster-get
        outputParameters:
        - type: object
          mapping: $.
    - path: /1.0/cluster
      name: cluster-put
      operations:
      - met

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