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	integer	Workspace ID

Query parameters

Name	Type	Description
q	string	Quick search by name or ID
id	integer[]	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	integer[]	Filter by source instance ID
source_disk	integer[]	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
state	string[]	Filter by resource state (AVAILABLE, PENDING, ...)

Plus the shared pagination parameters. Returns a paged list of images.

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

Search all images

GET/v1/imagesSearch all images

Administrator-only catalog view. Accepts the same query parameters as the workspace-scoped endpoint above and includes additional filters (owner, official, deprecated) applied without workspace-scoping. Returns a paged list of images.

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.

Path parameters

Name	Type	Description
wid	integer	Workspace ID

Request body

Field	Type	Required	Description
kind	string	yes	TEMPLATE, BACKUP, or ISO
name	string	yes	Image name (4-64 characters)
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; see OS fields below
uefi	boolean		Whether the image targets UEFI boot

source fields

Field	Type	Required	Description
type	string	yes	URL, BACKUP, INSTANCE, or UPLOAD
url	string		Source URL (for URL type)
backup_id	integer		Backup image ID to promote (for BACKUP type)
instance_id	integer		Source instance ID (for INSTANCE type)
disk_id	integer		Source disk ID (for INSTANCE type)
size_bytes	integer		Exact byte count the client will upload (for UPLOAD type)

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": "INSTANCE", "instance_id": 101, "disk_id": 202 },
    "os": { "family": "LINUX", "name": "Ubuntu 24.04" },
    "uefi": true
  }'

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 URL to PUT the file to (single-use, signed)
expires_at	string	ISO 8601 timestamp when the URL expires
max_size_bytes	integer	Exact byte count to upload

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

Fetch an image

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

Path parameters

Name	Type	Description
id	integer	Image ID

Returns the full image detail, including kind, source, os, size, uefi, official, deprecated, owner, and state.

Update an image

PATCH/v1/images/{id}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
id	integer	Image ID

Request body

Field	Type	Description
name	string	Rename the image (4-32 characters)
description	string	Update the description (4-1000 characters)
group	string	Update the catalog group (4-32 characters)
os	object	Update OS metadata; accepts family and name as nullable fields

Returns 204 No Content.

Restore an image onto an instance disk

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

Overwrites an instance disk with this image. The instance is powered off during the restore unless restart is false.

Path parameters

Name	Type	Description
id	integer	Image ID

Request body

Field	Type	Required	Description
instance_id	integer	yes	Instance to restore onto
disk_id	integer		Disk to restore onto; defaults to the instance's boot disk
restart	boolean		Whether to restart the instance after restore (default false)

Returns a workflow (202 Accepted).

Delete an image

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

Permanently deletes the image and frees its storage.

Path parameters

Name	Type	Description
id	integer	Image ID

Returns a workflow (202 Accepted).