Skip to navigation
Air APIAPI ReferenceImages

Request to publish an image

View as Markdown

Submits a gated publish intent. The image moves to PENDING_PUBLISH, the publish access record is PENDING, and community managers are notified. Requires justification. Optional allowed_orgs_request_text is free-text. Returns 409 if another publish or visibility request is already open or the image is in a publishing pipeline state.

Required scopes (any one):

  • air:image_write (roles: air_image_publisher, air_image_uploader)
  • 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.

justificationstringOptional1-2048 characters
Required explanation for community manager review and email.
allowed_orgs_request_textstringOptional<=4096 charactersDefaults to

Optional free-text description of orgs that should have access if the outcome is restricted. Not the authoritative allow list.

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
409
Conflict Error
500
Internal Server Error