Images

An image is a stored disk artifact you can provision from or restore onto an instance. Images are unified under a single resource with a kind field that distinguishes their role: TEMPLATE for distribution images and custom golden images, BACKUP for point-in-time copies of an instance disk, and ISO for bootable optical-disc images. Platform-provided images (those with no owner) are visible to every workspace. Creating, restoring, and deleting images are asynchronous.

List images visible to a workspace

GET/v1/workspaces/{wid}/imagesList images visible to a workspace

Returns images owned by the workspace plus all platform-provided images (where owner is null), merged and filtered by the search parameters.

Path parameters

Name	Type	Description
wid	string	Workspace ID

Query parameters

Name	Type	Description
q	string	Quick search by name or ID
id	string[]	Filter to specific image IDs
name	string	Filter by name
group	string	Filter by catalog group
description	string	Filter by description
os	string	Filter by OS family (LINUX, WINDOWS, BSD)
kind	string[]	Filter by kind (TEMPLATE, BACKUP, ISO)
source_instance	string[]	Filter by source instance ID
source_disk	string[]	Filter by source disk ID
official	boolean	true to return only platform-provided images. false for workspace-owned only
deprecated	boolean	Filter by deprecated status
owner	string[]	Filter by owning workspace ID
state	string[]	Filter by resource state (PENDING, AVAILABLE, FAILED, SUSPENDED, DELETING, UNPLACED)

All filters are optional. Plus the shared pagination parameters. Returns 200 OK with a KeysetResultImageListView containing image list items and pagination fields: limit, page, total, has_next, has_previous, after, and before.

curl https://api.galaxygate.net/v1/workspaces/42/images?kind=TEMPLATE \
  -H "Authorization: Bearer $GALAXYGATE_TOKEN" \
  -A 'curl/8.5'

Create an image

POST/v1/workspaces/{wid}/imagesCreate an image

Creates a new image in a workspace. The source object controls where the bytes come from. We accept these combinations:

kind	Allowed source.type	Requirements
TEMPLATE	BACKUP, URL	URL requires a staff session, os.family, and uefi. BACKUP inherits OS metadata and boot mode from the backup.
BACKUP	INSTANCE	Supply instance_id, disk_id, or both. The instance must belong to the target workspace, be available and unlocked, and have a backup plan. Its disk must be available.
ISO	UPLOAD, URL	URL requires a staff session. UPLOAD is subject to workspace ISO count and storage quotas.

Path parameters

Name	Type	Description
wid	string	Workspace ID

Request body

Field	Type	Required	Description
kind	string	yes	TEMPLATE, BACKUP, or ISO
name	string	for TEMPLATE and ISO	Image name (4-64 characters). Generated for BACKUP when omitted.
source	object	yes	Where the bytes come from. See source fields below
description	string		Image description (4-1000 characters)
group	string		Catalog group, for example linux or windows (4-32 characters)
os	object		OS metadata for TEMPLATE and ISO. Required for a template URL source. See OS fields below
uefi	boolean		Template boot mode. Required for a template URL source. Inherited for a backup source

source fields

Field	Type	Required	Description
type	string	yes	URL, BACKUP, INSTANCE, or UPLOAD
url	string	for URL	Source URL (for URL type)
backup_id	string	for BACKUP	Backup image ID to promote (for BACKUP type)
instance_id	string	unless disk_id is set	Source instance ID for INSTANCE
disk_id	string	unless instance_id is set	Source disk ID for INSTANCE. Defaults to the instance's boot disk.
size_bytes	string	for UPLOAD	Exact byte count to upload, from 1 to 10737418240

os fields

Field	Type	Required	Description
family	string	yes	LINUX, WINDOWS, or BSD
name	string		OS display name, for example Ubuntu 24.04

curl -X POST https://api.galaxygate.net/v1/workspaces/42/images \
  -H "Authorization: Bearer $GALAXYGATE_TOKEN" \
  -H "Content-Type: application/json" \
  -A 'curl/8.5' \
  -d '{
    "kind": "TEMPLATE",
    "name": "my-golden-image",
    "source": { "type": "BACKUP", "backup_id": "1471181001588760790" }
  }'

Returns 202 Accepted with an ImageCreateResponse. For all source types except UPLOAD, the response is a WorkflowWithResource containing a workflow and the new image resource. For ISO images created with source type UPLOAD, the response also includes an upload object:

Field	Type	Description
url	string	Absolute signed URL to PUT the file to
expires_at	string	ISO 8601 timestamp when the URL expires
max_size_bytes	integer	Exact byte count to upload

Poll GET /v1/images/{imid} until state is AVAILABLE.

Fetch an image

GET/v1/images/{imid}Fetch image by ID

Path parameters

Name	Type	Description
imid	string	Image ID

Returns 200 OK with an ImageDetailView, including kind, source, os, size, uefi, official, deprecated, owner, server, and state.

Update an image

PATCH/v1/images/{imid}Update image settings

Updates image metadata. Send only the fields you want to change. Responds 204 No Content on success.

Path parameters

Name	Type	Description
imid	string	Image ID

Request body

Field	Type	Description
name	string	Rename the image (4-32 characters)
description	string	Update the description (4-1000 characters), or null to clear it
group	string	Update the catalog group (4-32 characters), or null to clear it
os	object	Update OS metadata. Optional family is LINUX, WINDOWS, or BSD. Optional name is a string, or null to clear it

Returns 204 No Content.

Restore an image onto an instance disk

POST/v1/images/{imid}/restoreRestore an image onto an instance disk

Overwrites an instance disk with a TEMPLATE or BACKUP image. ISO images cannot be restored. The image, instance, and disk must be available, and the image must fit the disk. The instance must be unlocked and already offline unless restart is true.

Path parameters

Name	Type	Description
imid	string	Image ID

Request body

Field	Type	Required	Description
instance_id	string	yes	Instance to restore onto
disk_id	string		Disk belonging to the instance. Defaults to its boot disk.
restart	boolean		Whether to restart the instance after restore (default false)

Returns 202 Accepted with a WorkflowData object.

Delete an image

DELETE/v1/images/{imid}Delete an image

Permanently deletes the image and frees its storage.

Path parameters

Name	Type	Description
imid	string	Image ID

Returns 202 Accepted with a WorkflowData object.