Skip to navigation
Air APIAPI ReferenceImages

Publish an image to the public published catalog of images

View as Markdown

Immediately publishes the image (auto-approved publish access record, then S3 publish). Default prefer_public is true (globally visible). When prefer_public is false, send authoritative allowed_orgs as a UUID array for the restricted allow-list (distinct from gated request-publish string hints). Optional justification is stored for audit when provided.

Required scopes (any one):

  • air:image_publish (roles: air_image_publisher)

Authentication

AuthorizationBearer

Bearer authentication of the form Bearer <token>, where token is your auth token.

Path parameters

idstringRequiredformat: "uuid"
A UUID string identifying this image.

Request

This endpoint expects an object.
namestringOptional1-128 characters

The name of the image. This must be unique with the version. This may need to be updated when publishing the image.

versionstringOptional1-64 characters

The version of the image. This must be unique with the name. This may need to be updated when publishing the image.

prefer_publicbooleanOptionalDefaults to true

Requester intent for public (true, default) vs restricted (false) publishing. Community managers may choose a different outcome when approving a gated request.

justificationstring or nullOptional<=2048 characters

Optional text explaining who/why to share with.

allowed_orgslist of stringsOptional

Authoritative allow-list: orgs that may use the image when prefer_public is false. The image owning org is always included; [] is valid. Privileged PATCH …/publish only — not the gated request-publish string hint.

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
404
Not Found Error
500
Internal Server Error