The images API from Incus — 14 operation(s) for images.
Every API here is available over the APIs.io API and to AI agents over MCP.
One button, every client — Claude, Cursor, VS Code and the rest.
https://apis.io/mcp
find_apisBrowse and filter every API in the catalog.get_api_artifactsOne API's artifacts, grouped by type.get_openapiThe primary OpenAPI for this API.find_similar_apisAPIs that look like this one.apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.resolveTurn a domain, URL or GitHub org into the provider it belongs to.find_cohortsEvery scored population of providers in the catalog.curl "https://apis.io/api/v1/apis/incus-images-api"curl "https://apis.io/api/v1/apis?limit=25"Discovery needs no key. Ratings and market analysis are Pro.
Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.
A second provider on the same verified email joins the account you already have.
openapi: 3.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
schema:
type: string
- description: Collection filter
example: default
in: query
name: filter
schema:
type: string
- description: Retrieve images from all projects
in: query
name: all-projects
schema:
type: boolean
responses:
'200':
description: API endpoints
content:
application/json:
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: '#/components/responses/Forbidden'
'500':
$ref: '#/components/responses/InternalServerError'
summary: Get the images
tags:
- images
post:
description: Adds a new image to the image store.
operationId: images_post
parameters:
- description: Project name
example: default
in: query
name: project
schema:
type: string
- 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
responses:
'202':
$ref: '#/components/responses/Operation'
'400':
$ref: '#/components/responses/BadRequest'
'403':
$ref: '#/components/responses/Forbidden'
'500':
$ref: '#/components/responses/InternalServerError'
summary: Add an image
tags:
- images
requestBody:
content:
application/json:
schema: {}
description: Raw image file
/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
schema:
type: string
- description: Project name
example: default
in: query
name: project
schema:
type: string
responses:
'202':
$ref: '#/components/responses/Operation'
'400':
$ref: '#/components/responses/BadRequest'
'403':
$ref: '#/components/responses/Forbidden'
'500':
$ref: '#/components/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
schema:
type: string
- description: Project name
example: default
in: query
name: project
schema:
type: string
responses:
'200':
description: Image
content:
application/json:
schema:
description: Sync response
properties:
metadata:
$ref: '#/components/schemas/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: '#/components/responses/Forbidden'
'500':
$ref: '#/components/responses/InternalServerError'
summary: Get the image
tags:
- images
patch:
description: Updates a subset of the image definition.
operationId: image_patch
parameters:
- description: Fingerprint
in: path
name: fingerprint
required: true
schema:
type: string
- description: Project name
example: default
in: query
name: project
schema:
type: string
responses:
'200':
$ref: '#/components/responses/EmptySyncResponse'
'400':
$ref: '#/components/responses/BadRequest'
'403':
$ref: '#/components/responses/Forbidden'
'412':
$ref: '#/components/responses/PreconditionFailed'
'500':
$ref: '#/components/responses/InternalServerError'
summary: Partially update the image
tags:
- images
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/ImagePut'
description: Image configuration
required: true
put:
description: Updates the entire image definition.
operationId: image_put
parameters:
- description: Fingerprint
in: path
name: fingerprint
required: true
schema:
type: string
- description: Project name
example: default
in: query
name: project
schema:
type: string
responses:
'200':
$ref: '#/components/responses/EmptySyncResponse'
'400':
$ref: '#/components/responses/BadRequest'
'403':
$ref: '#/components/responses/Forbidden'
'412':
$ref: '#/components/responses/PreconditionFailed'
'500':
$ref: '#/components/responses/InternalServerError'
summary: Update the image
tags:
- images
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/ImagePut'
description: Image configuration
required: true
/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
schema:
type: string
- description: Project name
example: default
in: query
name: project
schema:
type: string
responses:
'200':
description: Raw image data
'403':
$ref: '#/components/responses/Forbidden'
'500':
$ref: '#/components/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
schema:
type: string
- description: Project name
example: default
in: query
name: project
schema:
type: string
responses:
'202':
$ref: '#/components/responses/Operation'
'403':
$ref: '#/components/responses/Forbidden'
'500':
$ref: '#/components/responses/InternalServerError'
summary: Make the server push the image to a remote server
tags:
- images
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/ImageExportPost'
description: Image push request
required: true
/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
schema:
type: string
- description: Project name
example: default
in: query
name: project
schema:
type: string
- description: Secret token to retrieve a private image
example: RANDOM-STRING
in: query
name: secret
schema:
type: string
responses:
'200':
description: Raw image data
'403':
$ref: '#/components/responses/Forbidden'
'500':
$ref: '#/components/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
schema:
type: string
- description: Project name
example: default
in: query
name: project
schema:
type: string
responses:
'202':
$ref: '#/components/responses/Operation'
'403':
$ref: '#/components/responses/Forbidden'
'500':
$ref: '#/components/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
schema:
type: string
- description: Project name
example: default
in: query
name: project
schema:
type: string
responses:
'202':
$ref: '#/components/responses/Operation'
'403':
$ref: '#/components/responses/Forbidden'
'500':
$ref: '#/components/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
schema:
type: string
- description: Project name
example: default
in: query
name: project
schema:
type: string
- description: Secret token to retrieve a private image
example: RANDOM-STRING
in: query
name: secret
schema:
type: string
responses:
'200':
description: Image
content:
application/json:
schema:
description: Sync response
properties:
metadata:
$ref: '#/components/schemas/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: '#/components/responses/Forbidden'
'500':
$ref: '#/components/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
schema:
type: string
responses:
'200':
description: API endpoints
content:
application/json:
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: '#/components/responses/Forbidden'
'500':
$ref: '#/components/responses/InternalServerError'
summary: Get the image aliases
tags:
- images
post:
description: Creates a new image alias.
operationId: images_aliases_post
parameters:
- description: Project name
example: default
in: query
name: project
schema:
type: string
responses:
'200':
$ref: '#/components/responses/EmptySyncResponse'
'400':
$ref: '#/components/responses/BadRequest'
'403':
$ref: '#/components/responses/Forbidden'
'500':
$ref: '#/components/responses/InternalServerError'
summary: Add an image alias
tags:
- images
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/ImageAliasesPost'
description: Image alias
required: true
/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
schema:
type: string
- description: Project name
example: default
in: query
name: project
schema:
type: string
responses:
'200':
$ref: '#/components/responses/EmptySyncResponse'
'400':
$ref: '#/components/responses/BadRequest'
'403':
$ref: '#/components/responses/Forbidden'
'500':
$ref: '#/components/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
schema:
type: string
- description: Project name
example: default
in: query
name: project
schema:
type: string
responses:
'200':
description: Image alias
content:
application/json:
schema:
description: Sync response
properties:
metadata:
$ref: '#/components/schemas/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: '#/components/responses/Forbidden'
'500':
$ref: '#/components/responses/InternalServerError'
summary: Get the image alias
tags:
- images
patch:
description: Updates a subset of the image alias configuration.
operationId: images_alias_patch
parameters:
- description: Alias name
in: path
name: name
required: true
schema:
type: string
- description: Project name
example: default
in: query
name: project
schema:
type: string
responses:
'200':
$ref: '#/components/responses/EmptySyncResponse'
'400':
$ref: '#/components/responses/BadRequest'
'403':
$ref: '#/components/responses/Forbidden'
'412':
$ref: '#/components/responses/PreconditionFailed'
'500':
$ref: '#/components/responses/InternalServerError'
summary: Partially update the image alias
tags:
- images
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/ImageAliasesEntryPut'
description: Image alias configuration
required: true
post:
description: Renames an existing image alias.
operationId: images_alias_post
parameters:
- description: Alias name
in: path
name: name
required: true
schema:
type: string
- description: Project name
example: default
in: query
name: project
schema:
type: string
responses:
'200':
$ref: '#/components/responses/EmptySyncResponse'
'400':
$ref: '#/components/responses/BadRequest'
'403':
$ref: '#/components/responses/Forbidden'
'500':
$ref: '#/components/responses/InternalServerError'
summary: Rename the image alias
tags:
- images
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/ImageAliasesEntryPost'
description: Image alias rename request
required: true
put:
description: Updates the entire image alias configuration.
operationId: images_aliases_put
parameters:
- description: Alias name
in: path
name: name
required: true
schema:
type: string
- description: Project name
example: default
in: query
name: project
schema:
type: string
responses:
'200':
$ref: '#/components/responses/EmptySyncResponse'
'400':
$ref: '#/components/responses/BadRequest'
'403':
$ref: '#/components/responses/Forbidden'
'412':
$ref: '#/components/responses/PreconditionFailed'
'500':
$ref: '#/components/responses/InternalServerError'
summary: Update the image alias
tags:
- images
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/ImageAliasesEntryPut'
description: Image alias configuration
required: true
/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
schema:
type: string
- description: Project name
example: default
in: query
name: project
schema:
type: string
responses:
'200':
description: Image alias
content:
application/json:
schema:
description: Sync response
properties:
metadata:
$ref: '#/components/schemas/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: '#/components/responses/Forbidden'
'500':
$ref: '#/components/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
schema:
type: string
responses:
'200':
description: API endpoints
content:
application/json:
schema:
description: Sync response
properties:
metadata:
description: List of image aliases
items:
$ref: '#/components/schemas/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: '#/components/responses/Forbidden'
'500':
$ref: '#/components/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
schema:
type: string
- description: Collection filter
example: default
in: query
name: filter
schema:
type: string
- description: Retrieve images from all projects
in: query
name: all-projects
schema:
type: boolean
responses:
'200':
description: API endpoints
content:
application/json:
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: '#/components/responses/Forbidden'
'500':
$ref: '#/components/responses/InternalServerError'
summary: Get the public images
tags:
- images
post:
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
schema:
type: string
responses:
'200':
$ref: '#/components/responses/EmptySyncResponse'
'400':
$ref: '#/components/responses/BadRequest'
'403':
$ref: '#/components/responses/Forbidden'
'500':
$ref: '#/components/responses/InternalServerError'
summary: Add an image
tags:
- images
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/ImagesPost'
description: Image
required: true
/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
schema:
type: string
- description: Collection filter
example: default
in: query
name: filter
schema:
type: string
- description: Retrieve images from all projects
in: query
name: all-projects
schema:
type: boolean
responses:
'200':
description: API endpoints
content:
application/json:
schema:
description: Sync response
properties:
metadata:
description: List of images
items:
$ref: '#/components/schemas/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: '#/components/responses/Forbidden'
'500':
$ref: '#/components/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
schema:
type: string
- description: Collection filter
example: default
in: query
name: filter
schema:
type: string
- description: Retrieve images from all projects
example: default
in: query
name: all-projects
schema:
type: boolean
responses:
'200':
description: API endpoints
content:
application/json:
schema:
description: Sync response
properties:
metadata:
description: List of images
items:
$ref: '#/components/schemas/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: '#/components/responses/Forbidden'
'500':
$ref: '#/components/responses/InternalServerError'
summary: Get the images
tags:
- images
components:
responses:
PreconditionFailed:
description: Precondition Failed
content:
application/json:
schema:
properties:
error:
example: precondition failed
type: string
x-go-name: Error
error_code:
example: 412
format: int64
type: integer
x-go-name: ErrorCode
type:
example: error
type: string
x-go-name: Type
type: object
InternalServerError:
description: Internal Server Error
content:
application/json:
schema:
properties:
error:
example: internal server error
type: string
x-go-name: Error
error_code:
example: 500
format: int64
type: integer
x-go-name: ErrorCode
type:
example: error
type: string
x-go-name: Type
type: object
BadRequest:
description: Bad Request
content:
application/json:
schema:
properties:
error:
example: bad request
type: string
x-go-name: Error
error_code:
example: 400
format: int64
type: integer
x-go-name: ErrorCo
# --- truncated at 32 KB (50 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/incus/refs/heads/main/openapi/incus-images-api-openapi.yml