Instance commands

This page covers per-action command endpoints for instances. Every endpoint listed here is a POST. Commands that return workflow data run asynchronously.

Create a snapshot

POST/v1/commands/create-snapshotCreates a snapshot of an instance

Queues a point-in-time snapshot of an instance disk. The instance and disk must be in AVAILABLE state, and the instance must not be locked. See Snapshots for the snapshot resource and how to list or delete snapshots.

Request body

Field	Type	Required	Description
instance_id	string	yes	Instance ID to snapshot
disk_id	string		Disk to snapshot. Defaults to the boot disk

curl -s -A 'curl/8.5' -X POST https://api.galaxygate.net/v1/commands/create-snapshot \
  -H "Authorization: Bearer $GALAXYGATE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "instance_id": "101",
    "disk_id": "55"
  }'

Returns workflow data (200 OK). Poll GET /v1/workflows/{id} until state is COMPLETED. See Asynchronous operations.

Restore a snapshot

POST/v1/commands/restore-snapshotRestores a snapshot

Wipes all data on the instance's disk and restores the given snapshot in its place. The snapshot must be AVAILABLE. Unless restart is true, the instance must be offline before the restore begins.

Request body

Field	Type	Required	Description
snapshot_id	string	yes	Snapshot ID to restore
restart	boolean		Power the instance off before restoring, then back on after. Defaults to false

Returns workflow data (202 Accepted). Poll until state is COMPLETED.

Attach an ISO

POST/v1/commands/attach-isoAttaches an ISO to an instance

Connects an ISO image to an instance's virtual CDROM. The CDROM update is attempted immediately. The ISO must be either an official image or one that belongs to your workspace.

Request body

Field	Type	Required	Description
instance	string	yes	Instance ID
iso	string	yes	ISO image ID to attach

Returns workflow data (200 OK).

Detach an ISO

POST/v1/commands/detach-isoDetach ISO from an instance

Disconnects the ISO currently attached to an instance. The CDROM update is attempted immediately. Fails if no ISO is attached.

Request body

Field	Type	Required	Description
instance	string	yes	Instance ID

Returns workflow data (200 OK).

Install a recipe

POST/v1/commands/install-recipeInstalls a recipe on an instance

Runs a recipe on a running instance. The instance must be online and in AVAILABLE state. See Recipes for how to create and list recipes and discover their fields.

Request body

Field	Type	Required	Description
instance	string	yes	Instance ID
recipe	string	yes	Recipe ID to install
fields	object	yes	Key-value map of recipe field IDs to values. Send {} if the recipe has no fields

Returns workflow data (200 OK).

Reset the root password

POST/v1/commands/reset-instance-passwordResets an instance's root password

Generates a new 14-character root password and attempts to apply it through several methods, falling back to an offline (restart-required) reset if the live methods fail. The new password is returned immediately in the response body. Store it now as it is not shown again.

Request body

Field	Type	Required	Description
instance_id	string	yes	Instance ID

Returns the response synchronously with the following fields:

Field	Type	Description
password	string	The new root password
task_id	string	Audit log entry ID for this operation

Sync SSH keys

POST/v1/commands/sync-instance-ssh-keysSyncs workspace SSH keys to an instance

Replaces the entire authorized_keys file on the instance's root account with the workspace's current set of SSH keys. Requires the instance to be online and running a Linux or BSD operating system.

Request body

Field	Type	Required	Description
instance_id	string	yes	Instance ID

Returns workflow data (202 Accepted).

Update hostname

POST/v1/commands/update-instance-hostnameUpdates an instance's hostname

Renames the instance and sets its hostname through the guest agent. The instance must be online with its guest agent running.

Request body

Field	Type	Required	Description
instance_id	string	yes	Instance ID
hostname	string	yes	New hostname with letters, digits, and hyphens in dot-separated labels, up to 63 characters

Returns workflow data (200 OK).

Apply pending upgrades

POST/v1/commands/apply-upgradesApplies pending instance upgrades

Applies all pending instance upgrades. A running instance is powered off for the upgrade and powered back on afterwards.

Request body

Field	Type	Required	Description
instance	string	yes	Instance ID

Returns workflow data (200 OK).

Batch power

POST/v1/commands/batch-instance-powerExecutes a power action on a batch of instances

Issues a power action against multiple instances in a single call. Power commands execute in sequence. Instances that are not AVAILABLE, are locked, or are not accessible to the caller are silently skipped. The request fails only when no eligible instances remain.

Request body

Field	Type	Required	Description
instances	string[]	yes	List of instance IDs
action	string	yes	One of POWER_ON, POWER_OFF, SHUTDOWN, POWER_CYCLE

curl -s -A 'curl/8.5' -X POST https://api.galaxygate.net/v1/commands/batch-instance-power \
  -H "Authorization: Bearer $GALAXYGATE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "instances": ["101", "102", "103"],
    "action": "POWER_OFF"
  }'

Returns an object containing workflow data and skipped instance records (200 OK).