Incus images API

swagger: '2.0'
info:
  contact:
    email: lxc-devel@lists.linuxcontainers.org
    name: Incus upstream
    url: https://github.com/lxc/incus
  description: 'This is the REST API used by all Incus clients.

    Internal endpoints aren''t included in this documentation.


    The Incus API is available over both a local unix+http and remote https API.

    Authentication for local users relies on group membership and access to the unix socket.

    For remote users, the default authentication method is TLS client

    certificates.'
  license:
    name: Apache-2.0
    url: https://www.apache.org/licenses/LICENSE-2.0
  title: Incus external REST certificates images API
  version: '1.0'
tags:
- name: images
paths:
  /1.0/images:
    get:
      description: Returns a list of images (URLs).
      operationId: images_get
      parameters:
      - description: Project name
        example: default
        in: query
        name: project
        type: string
      - description: Collection filter
        example: default
        in: query
        name: filter
        type: string
      - description: Retrieve images from all projects
        in: query
        name: all-projects
        type: boolean
      produces:
      - application/json
      responses:
        '200':
          description: API endpoints
          schema:
            description: Sync response
            properties:
              metadata:
                description: List of endpoints
                example: "[\n  \"/1.0/images/06b86454720d36b20f94e31c6812e05ec51c1b568cf3a8abd273769d213394bb\",\n  \"/1.0/images/084dd79dd1360fd25a2479eb46674c2a5ef3022a40fe03c91ab3603e3402b8e1\"\n]"
                items:
                  type: string
                type: array
              status:
                description: Status description
                example: Success
                type: string
              status_code:
                description: Status code
                example: 200
                type: integer
              type:
                description: Response type
                example: sync
                type: string
            type: object
        '403':
          $ref: '#/responses/Forbidden'
        '500':
          $ref: '#/responses/InternalServerError'
      summary: Get the images
      tags:
      - images
    post:
      consumes:
      - application/json
      description: Adds a new image to the image store.
      operationId: images_post
      parameters:
      - description: Project name
        example: default
        in: query
        name: project
        type: string
      - description: Image
        in: body
        name: image
        schema:
          $ref: '#/definitions/ImagesPost'
      - description: Raw image file
        in: body
        name: raw_image
      - description: Push secret for server to server communication
        example: RANDOM-STRING
        in: header
        name: X-Incus-secret
        schema:
          type: string
      - description: Expected fingerprint when pushing a raw image
        in: header
        name: X-Incus-fingerprint
        schema:
          type: string
      - description: List of aliases to assign
        in: header
        name: X-Incus-aliases
        schema:
          items:
            type: string
          type: array
      - description: Descriptive properties
        in: header
        name: X-Incus-properties
        schema:
          additionalProperties:
            type: string
          type: object
      - description: Whether the image is available to unauthenticated users
        in: header
        name: X-Incus-public
        schema:
          type: boolean
      - description: Original filename of the image
        in: header
        name: X-Incus-filename
        schema:
          type: string
      - description: List of profiles to use
        in: header
        name: X-Incus-profiles
        schema:
          items:
            type: string
          type: array
      produces:
      - application/json
      responses:
        '202':
          $ref: '#/responses/Operation'
        '400':
          $ref: '#/responses/BadRequest'
        '403':
          $ref: '#/responses/Forbidden'
        '500':
          $ref: '#/responses/InternalServerError'
      summary: Add an image
      tags:
      - images
  /1.0/images/{fingerprint}:
    delete:
      description: Removes the image from the image store.
      operationId: image_delete
      parameters:
      - description: Fingerprint
        in: path
        name: fingerprint
        required: true
        type: string
      - description: Project name
        example: default
        in: query
        name: project
        type: string
      produces:
      - application/json
      responses:
        '202':
          $ref: '#/responses/Operation'
        '400':
          $ref: '#/responses/BadRequest'
        '403':
          $ref: '#/responses/Forbidden'
        '500':
          $ref: '#/responses/InternalServerError'
      summary: Delete the image
      tags:
      - images
    get:
      description: Gets a specific image.
      operationId: image_get
      parameters:
      - description: Fingerprint
        in: path
        name: fingerprint
        required: true
        type: string
      - description: Project name
        example: default
        in: query
        name: project
        type: string
      produces:
      - application/json
      responses:
        '200':
          description: Image
          schema:
            description: Sync response
            properties:
              metadata:
                $ref: '#/definitions/Image'
              status:
                description: Status description
                example: Success
                type: string
              status_code:
                description: Status code
                example: 200
                type: integer
              type:
                description: Response type
                example: sync
                type: string
            type: object
        '403':
          $ref: '#/responses/Forbidden'
        '500':
          $ref: '#/responses/InternalServerError'
      summary: Get the image
      tags:
      - images
    patch:
      consumes:
      - application/json
      description: Updates a subset of the image definition.
      operationId: image_patch
      parameters:
      - description: Fingerprint
        in: path
        name: fingerprint
        required: true
        type: string
      - description: Project name
        example: default
        in: query
        name: project
        type: string
      - description: Image configuration
        in: body
        name: image
        required: true
        schema:
          $ref: '#/definitions/ImagePut'
      produces:
      - application/json
      responses:
        '200':
          $ref: '#/responses/EmptySyncResponse'
        '400':
          $ref: '#/responses/BadRequest'
        '403':
          $ref: '#/responses/Forbidden'
        '412':
          $ref: '#/responses/PreconditionFailed'
        '500':
          $ref: '#/responses/InternalServerError'
      summary: Partially update the image
      tags:
      - images
    put:
      consumes:
      - application/json
      description: Updates the entire image definition.
      operationId: image_put
      parameters:
      - description: Fingerprint
        in: path
        name: fingerprint
        required: true
        type: string
      - description: Project name
        example: default
        in: query
        name: project
        type: string
      - description: Image configuration
        in: body
        name: image
        required: true
        schema:
          $ref: '#/definitions/ImagePut'
      produces:
      - application/json
      responses:
        '200':
          $ref: '#/responses/EmptySyncResponse'
        '400':
          $ref: '#/responses/BadRequest'
        '403':
          $ref: '#/responses/Forbidden'
        '412':
          $ref: '#/responses/PreconditionFailed'
        '500':
          $ref: '#/responses/InternalServerError'
      summary: Update the image
      tags:
      - images
  /1.0/images/{fingerprint}/export:
    get:
      description: 'Download the raw image file(s) from the server.

        If the image is in split format, a multipart http transfer occurs.'
      operationId: image_export_get
      parameters:
      - description: Fingerprint
        in: path
        name: fingerprint
        required: true
        type: string
      - description: Project name
        example: default
        in: query
        name: project
        type: string
      produces:
      - application/octet-stream
      - multipart/form-data
      responses:
        '200':
          description: Raw image data
        '403':
          $ref: '#/responses/Forbidden'
        '500':
          $ref: '#/responses/InternalServerError'
      summary: Get the raw image file(s)
      tags:
      - images
    post:
      description: Gets the server to connect to a remote server and push the image to it.
      operationId: images_export_post
      parameters:
      - description: Fingerprint
        in: path
        name: fingerprint
        required: true
        type: string
      - description: Project name
        example: default
        in: query
        name: project
        type: string
      - description: Image push request
        in: body
        name: image
        required: true
        schema:
          $ref: '#/definitions/ImageExportPost'
      produces:
      - application/json
      responses:
        '202':
          $ref: '#/responses/Operation'
        '403':
          $ref: '#/responses/Forbidden'
        '500':
          $ref: '#/responses/InternalServerError'
      summary: Make the server push the image to a remote server
      tags:
      - images
  /1.0/images/{fingerprint}/export?public:
    get:
      description: 'Download the raw image file(s) of a public image from the server.

        If the image is in split format, a multipart http transfer occurs.'
      operationId: image_export_get_untrusted
      parameters:
      - description: Fingerprint
        in: path
        name: fingerprint
        required: true
        type: string
      - description: Project name
        example: default
        in: query
        name: project
        type: string
      - description: Secret token to retrieve a private image
        example: RANDOM-STRING
        in: query
        name: secret
        type: string
      produces:
      - application/octet-stream
      - multipart/form-data
      responses:
        '200':
          description: Raw image data
        '403':
          $ref: '#/responses/Forbidden'
        '500':
          $ref: '#/responses/InternalServerError'
      summary: Get the raw image file(s)
      tags:
      - images
  /1.0/images/{fingerprint}/refresh:
    post:
      description: 'This causes the server to check the image source server for an updated

        version of the image and if available to refresh the local copy with the

        new version.'
      operationId: images_refresh_post
      parameters:
      - description: Fingerprint
        in: path
        name: fingerprint
        required: true
        type: string
      - description: Project name
        example: default
        in: query
        name: project
        type: string
      produces:
      - application/json
      responses:
        '202':
          $ref: '#/responses/Operation'
        '403':
          $ref: '#/responses/Forbidden'
        '500':
          $ref: '#/responses/InternalServerError'
      summary: Refresh an image
      tags:
      - images
  /1.0/images/{fingerprint}/secret:
    post:
      description: 'This generates a background operation including a secret one time key

        in its metadata which can be used to fetch this image from an untrusted

        client.'
      operationId: images_secret_post
      parameters:
      - description: Fingerprint
        in: path
        name: fingerprint
        required: true
        type: string
      - description: Project name
        example: default
        in: query
        name: project
        type: string
      produces:
      - application/json
      responses:
        '202':
          $ref: '#/responses/Operation'
        '403':
          $ref: '#/responses/Forbidden'
        '500':
          $ref: '#/responses/InternalServerError'
      summary: Generate secret for retrieval of the image by an untrusted client
      tags:
      - images
  /1.0/images/{fingerprint}?public:
    get:
      description: Gets a specific public image.
      operationId: image_get_untrusted
      parameters:
      - description: Fingerprint
        in: path
        name: fingerprint
        required: true
        type: string
      - description: Project name
        example: default
        in: query
        name: project
        type: string
      - description: Secret token to retrieve a private image
        example: RANDOM-STRING
        in: query
        name: secret
        type: string
      produces:
      - application/json
      responses:
        '200':
          description: Image
          schema:
            description: Sync response
            properties:
              metadata:
                $ref: '#/definitions/Image'
              status:
                description: Status description
                example: Success
                type: string
              status_code:
                description: Status code
                example: 200
                type: integer
              type:
                description: Response type
                example: sync
                type: string
            type: object
        '403':
          $ref: '#/responses/Forbidden'
        '500':
          $ref: '#/responses/InternalServerError'
      summary: Get the public image
      tags:
      - images
  /1.0/images/aliases:
    get:
      description: Returns a list of image aliases (URLs).
      operationId: images_aliases_get
      parameters:
      - description: Project name
        example: default
        in: query
        name: project
        type: string
      produces:
      - application/json
      responses:
        '200':
          description: API endpoints
          schema:
            description: Sync response
            properties:
              metadata:
                description: List of endpoints
                example: "[\n  \"/1.0/images/aliases/foo\",\n  \"/1.0/images/aliases/bar1\"\n]"
                items:
                  type: string
                type: array
              status:
                description: Status description
                example: Success
                type: string
              status_code:
                description: Status code
                example: 200
                type: integer
              type:
                description: Response type
                example: sync
                type: string
            type: object
        '403':
          $ref: '#/responses/Forbidden'
        '500':
          $ref: '#/responses/InternalServerError'
      summary: Get the image aliases
      tags:
      - images
    post:
      consumes:
      - application/json
      description: Creates a new image alias.
      operationId: images_aliases_post
      parameters:
      - description: Project name
        example: default
        in: query
        name: project
        type: string
      - description: Image alias
        in: body
        name: image alias
        required: true
        schema:
          $ref: '#/definitions/ImageAliasesPost'
      produces:
      - application/json
      responses:
        '200':
          $ref: '#/responses/EmptySyncResponse'
        '400':
          $ref: '#/responses/BadRequest'
        '403':
          $ref: '#/responses/Forbidden'
        '500':
          $ref: '#/responses/InternalServerError'
      summary: Add an image alias
      tags:
      - images
  /1.0/images/aliases/{name}:
    delete:
      description: Deletes a specific image alias.
      operationId: image_alias_delete
      parameters:
      - description: Alias name
        in: path
        name: name
        required: true
        type: string
      - description: Project name
        example: default
        in: query
        name: project
        type: string
      produces:
      - application/json
      responses:
        '200':
          $ref: '#/responses/EmptySyncResponse'
        '400':
          $ref: '#/responses/BadRequest'
        '403':
          $ref: '#/responses/Forbidden'
        '500':
          $ref: '#/responses/InternalServerError'
      summary: Delete the image alias
      tags:
      - images
    get:
      description: Gets a specific image alias.
      operationId: image_alias_get
      parameters:
      - description: Alias name
        in: path
        name: name
        required: true
        type: string
      - description: Project name
        example: default
        in: query
        name: project
        type: string
      produces:
      - application/json
      responses:
        '200':
          description: Image alias
          schema:
            description: Sync response
            properties:
              metadata:
                $ref: '#/definitions/ImageAliasesEntry'
              status:
                description: Status description
                example: Success
                type: string
              status_code:
                description: Status code
                example: 200
                type: integer
              type:
                description: Response type
                example: sync
                type: string
            type: object
        '403':
          $ref: '#/responses/Forbidden'
        '500':
          $ref: '#/responses/InternalServerError'
      summary: Get the image alias
      tags:
      - images
    patch:
      consumes:
      - application/json
      description: Updates a subset of the image alias configuration.
      operationId: images_alias_patch
      parameters:
      - description: Alias name
        in: path
        name: name
        required: true
        type: string
      - description: Project name
        example: default
        in: query
        name: project
        type: string
      - description: Image alias configuration
        in: body
        name: image alias
        required: true
        schema:
          $ref: '#/definitions/ImageAliasesEntryPut'
      produces:
      - application/json
      responses:
        '200':
          $ref: '#/responses/EmptySyncResponse'
        '400':
          $ref: '#/responses/BadRequest'
        '403':
          $ref: '#/responses/Forbidden'
        '412':
          $ref: '#/responses/PreconditionFailed'
        '500':
          $ref: '#/responses/InternalServerError'
      summary: Partially update the image alias
      tags:
      - images
    post:
      consumes:
      - application/json
      description: Renames an existing image alias.
      operationId: images_alias_post
      parameters:
      - description: Alias name
        in: path
        name: name
        required: true
        type: string
      - description: Project name
        example: default
        in: query
        name: project
        type: string
      - description: Image alias rename request
        in: body
        name: image alias
        required: true
        schema:
          $ref: '#/definitions/ImageAliasesEntryPost'
      produces:
      - application/json
      responses:
        '200':
          $ref: '#/responses/EmptySyncResponse'
        '400':
          $ref: '#/responses/BadRequest'
        '403':
          $ref: '#/responses/Forbidden'
        '500':
          $ref: '#/responses/InternalServerError'
      summary: Rename the image alias
      tags:
      - images
    put:
      consumes:
      - application/json
      description: Updates the entire image alias configuration.
      operationId: images_aliases_put
      parameters:
      - description: Alias name
        in: path
        name: name
        required: true
        type: string
      - description: Project name
        example: default
        in: query
        name: project
        type: string
      - description: Image alias configuration
        in: body
        name: image alias
        required: true
        schema:
          $ref: '#/definitions/ImageAliasesEntryPut'
      produces:
      - application/json
      responses:
        '200':
          $ref: '#/responses/EmptySyncResponse'
        '400':
          $ref: '#/responses/BadRequest'
        '403':
          $ref: '#/responses/Forbidden'
        '412':
          $ref: '#/responses/PreconditionFailed'
        '500':
          $ref: '#/responses/InternalServerError'
      summary: Update the image alias
      tags:
      - images
  /1.0/images/aliases/{name}?public:
    get:
      description: 'Gets a specific public image alias.

        This untrusted endpoint only works for aliases pointing to public images.'
      operationId: image_alias_get_untrusted
      parameters:
      - description: Alias name
        in: path
        name: name
        required: true
        type: string
      - description: Project name
        example: default
        in: query
        name: project
        type: string
      produces:
      - application/json
      responses:
        '200':
          description: Image alias
          schema:
            description: Sync response
            properties:
              metadata:
                $ref: '#/definitions/ImageAliasesEntry'
              status:
                description: Status description
                example: Success
                type: string
              status_code:
                description: Status code
                example: 200
                type: integer
              type:
                description: Response type
                example: sync
                type: string
            type: object
        '403':
          $ref: '#/responses/Forbidden'
        '500':
          $ref: '#/responses/InternalServerError'
      summary: Get the public image alias
      tags:
      - images
  /1.0/images/aliases?recursion=1:
    get:
      description: Returns a list of image aliases (structs).
      operationId: images_aliases_get_recursion1
      parameters:
      - description: Project name
        example: default
        in: query
        name: project
        type: string
      produces:
      - application/json
      responses:
        '200':
          description: API endpoints
          schema:
            description: Sync response
            properties:
              metadata:
                description: List of image aliases
                items:
                  $ref: '#/definitions/ImageAliasesEntry'
                type: array
              status:
                description: Status description
                example: Success
                type: string
              status_code:
                description: Status code
                example: 200
                type: integer
              type:
                description: Response type
                example: sync
                type: string
            type: object
        '403':
          $ref: '#/responses/Forbidden'
        '500':
          $ref: '#/responses/InternalServerError'
      summary: Get the image aliases
      tags:
      - images
  /1.0/images?public:
    get:
      description: Returns a list of publicly available images (URLs).
      operationId: images_get_untrusted
      parameters:
      - description: Project name
        example: default
        in: query
        name: project
        type: string
      - description: Collection filter
        example: default
        in: query
        name: filter
        type: string
      - description: Retrieve images from all projects
        in: query
        name: all-projects
        type: boolean
      produces:
      - application/json
      responses:
        '200':
          description: API endpoints
          schema:
            description: Sync response
            properties:
              metadata:
                description: List of endpoints
                example: "[\n  \"/1.0/images/06b86454720d36b20f94e31c6812e05ec51c1b568cf3a8abd273769d213394bb\",\n  \"/1.0/images/084dd79dd1360fd25a2479eb46674c2a5ef3022a40fe03c91ab3603e3402b8e1\"\n]"
                items:
                  type: string
                type: array
              status:
                description: Status description
                example: Success
                type: string
              status_code:
                description: Status code
                example: 200
                type: integer
              type:
                description: Response type
                example: sync
                type: string
            type: object
        '403':
          $ref: '#/responses/Forbidden'
        '500':
          $ref: '#/responses/InternalServerError'
      summary: Get the public images
      tags:
      - images
    post:
      consumes:
      - application/json
      description: 'Pushes the data to the target image server.

        This is meant for server to server communication where a new image entry is

        prepared on the target server and the source server is provided that URL

        and a secret token to push the image content over.'
      operationId: images_post_untrusted
      parameters:
      - description: Project name
        example: default
        in: query
        name: project
        type: string
      - description: Image
        in: body
        name: image
        required: true
        schema:
          $ref: '#/definitions/ImagesPost'
      produces:
      - application/json
      responses:
        '200':
          $ref: '#/responses/EmptySyncResponse'
        '400':
          $ref: '#/responses/BadRequest'
        '403':
          $ref: '#/responses/Forbidden'
        '500':
          $ref: '#/responses/InternalServerError'
      summary: Add an image
      tags:
      - images
  /1.0/images?public&recursion=1:
    get:
      description: Returns a list of publicly available images (structs).
      operationId: images_get_recursion1_untrusted
      parameters:
      - description: Project name
        example: default
        in: query
        name: project
        type: string
      - description: Collection filter
        example: default
        in: query
        name: filter
        type: string
      - description: Retrieve images from all projects
        in: query
        name: all-projects
        type: boolean
      produces:
      - application/json
      responses:
        '200':
          description: API endpoints
          schema:
            description: Sync response
            properties:
              metadata:
                description: List of images
                items:
                  $ref: '#/definitions/Image'
                type: array
              status:
                description: Status description
                example: Success
                type: string
              status_code:
                description: Status code
                example: 200
                type: integer
              type:
                description: Response type
                example: sync
                type: string
            type: object
        '403':
          $ref: '#/responses/Forbidden'
        '500':
          $ref: '#/responses/InternalServerError'
      summary: Get the public images
      tags:
      - images
  /1.0/images?recursion=1:
    get:
      description: Returns a list of images (structs).
      operationId: images_get_recursion1
      parameters:
      - description: Project name
        example: default
        in: query
        name: project
        type: string
      - description: Collection filter
        example: default
        in: query
        name: filter
        type: string
      - description: Retrieve images from all projects
        example: default
        in: query
        name: all-projects
        type: boolean
      produces:
      - application/json
      responses:
        '200':
          description: API endpoints
          schema:
            description: Sync response
            properties:
              metadata:
                description: List of images
                items:
                  $ref: '#/definitions/Image'
                type: array
              status:
                description: Status description
                example: Success
                type: string
              status_code:
                description: Status code
                example: 200
                type: integer
              type:
                description: Response type
                example: sync
                type: string
            type: object
        '403':
          $ref: '#/responses/Forbidden'
        '500':
          $ref: '#/responses/InternalServerError'
      summary: Get the images
      tags:
      - images
definitions:
  StatusCode:
    format: int64
    title: StatusCode represents a valid operation and container status.
    type: integer
    x-go-package: github.com/lxc/incus/v7/shared/api
  ImageAliasesEntry:
    description: ImageAliasesEntry represents an image alias
    properties:
      description:
        description: Alias description
        example: Our preferred Ubuntu image
        type: string
        x-go-name: Description
      name:
        description: Alias name
        example: ubuntu-22.04
        type: string
        x-go-name: Name
      target:
        description: Target fingerprint for the alias
        example: 06b86454720d36b20f94e31c6812e05ec51c1b568cf3a8abd273769d213394bb
        type: string
        x-go-name: Target
      type:
        description: Alias type (container or virtual-machine)
        example: container
        type: string
        x-go-name: Type
    type: object
    x-go-package: github.com/lxc/incus/v7/shared/api
  ImageAliasesEntryPut:
    description: ImageAliasesEntryPut represents the modifiable fields of an image alias
    properties:
      description:
        description: Alias description
        example: Our preferred Ubuntu image
        type: string
        x-go-name: Description
      target:
        description: Target fingerprint for the alias
        example: 06b86454720d36b20f94e31c6812e05ec51c1b568cf3a8abd273769d213394bb
        type: string
        x-go-name: Target
    type: object
    x-go-package: github.com/lxc/incus/v7/shared/api
  ImageSource:
    description: ImageSource represents the source of an image
    properties:
      alias:
        description: Source alias to download from
        example: jammy
        type: string
        x-go-name: Alias
      certificate:
        description: Source server certificate (if not trusted by system CA)
        example: X509 PEM certificate
        type: string
        x-go-name: Certificate
      image_type:
        description: Type of image (container or virtual-machine)
        example: container
        type: string
        x-go-name: ImageType
      protocol:
        description: Source server protocol
        example: simplestreams
        type: string
        x-go-name: Protocol
      server:
        description: URL of the source server
        example: https://images.linuxcontainers.org
        type: string
        x-go-name: Server
    type: object
    x-go-package: github.com/lxc/incus/v7/shared/api
  ImageAliasesPost:
    description: ImageAliasesPost represents a new image alias
    properties:
      description:
        description: Alias description
        example: Our preferred Ubuntu image
        type: string
        x-go-name: Description
      name:
        description: Alias name
        example: ubuntu-22.04
        type: string
        x-go-name: Name
      target:
        description: Target fingerprint for the alias
        example: 06b86454720d36b20f94e31c6812e05ec51c1b568cf3a8abd273769d213394bb
        type: string
        x-go-name: Target
      type:
        description: Alias type (container or virtual-machine)
        example: container
        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: Ali

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