For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.
Once the image has been created, the image will transition to the `READY` state and the actual image content will need to be uploaded. Use the `start-upload` endpoint to upload the image content.
**Required scope:** `air:image_write` (roles: `air_image_publisher`, `air_image_uploader`)
Authentication
AuthorizationBearer
Bearer authentication of the form Bearer <token>, where token is your auth token.
Request
This endpoint expects an object.
namestringRequired1-128 characters
The name of the image. This must be unique with the version.
versionstringRequired1-64 characters
The version of the image. This must be unique with the name.
default_usernamestringRequired1-64 characters
The default username for authenticating with the operating system.
default_passwordstringRequired1-64 characters
The default password for authenticating with the operating system.
mountpointstring or nullOptional1-128 characters
Partition that hosts the operating system root file system.
minimum_resourcesobjectOptional
The minimum resources required to run the image.
includes_air_agentbooleanOptionalDefaults to false
Whether the image includes the Air Agent service.
cpu_archenumOptionalDefaults to x86
The CPU architecture of the image.
x86 - x86
ARM - ARM
Allowed values:
emulation_typelist of stringsOptional
The types of emulation the image supports.
emulation_versionstringOptional<=64 characters
The version of the emulation the image supports.
providerenumOptionalDefaults to VM
The provider of the image.
VM - VM
CONTAINER - CONTAINER
Allowed values:
notesstringOptional<=4096 characters
Notes about the image.
release_notesstringOptional<=4096 characters
Release notes for the image.
user_manualstringOptional<=4096 characters
User manual for the image.
Response
idstringRead-onlyformat: "uuid"
namestring1-128 characters
The name of the image. This must be unique with the version.
versionstring1-64 characters
The version of the image. This must be unique with the name.
createddatetimeRead-only
creatorstring or nullRead-only
The email of the user who created the image.
modifieddatetimeRead-only
default_usernamestring<=64 characters
The default username for authenticating with the operating system.
default_passwordstring<=64 characters
The default password for authenticating with the operating system.
publishedbooleanRead-only
Whether the image is published.
publicly_publishedbooleanRead-only
Whether the image is published to all users (public) vs restricted to an allow-list. Always false for unpublished images.
publish_access_record_idstring or nullRead-only
The id of the image publish access record. Returned only to the owning organization, Air admins, and SREs; null otherwise.
upload_statusenum
The upload status of the image file.
READY - Ready
UPLOADING - Uploading
VALIDATING - Validating
COMPLETE - Complete
PUBLISHING - Publishing
UNPUBLISHING - Unpublishing
COPYING_FROM_IMAGE_SHARE - Copying from image share
PENDING_PUBLISH - Pending Publish
PENDING_UNPUBLISH - Pending Unpublish
last_uploaded_atdatetime or nullRead-only
The date and time the image was last uploaded.
sizeintegerRead-only
The size of the image file in bytes.
hashstringRead-only
The hash of the image file. This is used to check if the content of the image has changed.
is_owned_by_clientbooleanRead-only
If the image is owned by the client. When true, the client can share/publish/unpublish the image.
mountpointstring or nullOptional1-128 characters
Partition that hosts the operating system root file system.
minimum_resourcesobjectOptional
The minimum resources required to run the image.
includes_air_agentbooleanOptionalDefaults to false
Whether the image includes the Air Agent service.
cpu_archenumOptionalDefaults to x86
The CPU architecture of the image.
x86 - x86
ARM - ARM
Allowed values:
emulation_typelist of stringsOptional
The types of emulation the image supports.
emulation_versionstringOptional<=64 characters
The version of the emulation the image supports.
providerenumOptionalDefaults to VM
The provider of the image.
VM - VM
CONTAINER - CONTAINER
Allowed values:
notesstringOptional<=4096 characters
Notes about the image.
release_notesstringOptional<=4096 characters
Release notes for the image.
user_manualstringOptional<=4096 characters
User manual for the image.
Errors
400
Bad Request Error
403
Forbidden Error
500
Internal Server Error
Once the image has been created, the image will transition to the READY state and the actual image content will need to be uploaded. Use the start-upload endpoint to upload the image content.
