Instance commands

This page covers per-action command endpoints for instances. Every endpoint listed here is a POST and runs asynchronously, returning a workflow you poll until the operation settles - except where noted below.

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 must be in AVAILABLE state and not locked. See Snapshots for the snapshot resource and how to list or delete snapshots.

Request body

Field	Type	Required	Description
instance_id	integer	yes	Instance ID to snapshot
disk_id	integer		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 a workflow; 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	integer	yes	Snapshot ID to restore
restart	boolean		Power the instance off before restoring, then back on after; defaults to false

Returns a workflow; 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	integer	yes	Instance ID
iso	integer	yes	ISO image ID to attach

Returns a workflow.

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	integer	yes	Instance ID

Returns a workflow.

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	integer	yes	Instance ID
recipe	integer	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 a workflow.

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	integer	yes	Instance ID

Returns the response synchronously with the following fields:

Field	Type	Description
password	string	The new root password
task_id	integer	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	integer	yes	Instance ID

Returns a workflow.

Update hostname

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

Requests a hostname change on a Linux instance. The instance must be offline before the update is applied.

Request body

Field	Type	Required	Description
instance_id	integer	yes	Instance ID
hostname	string	yes	New hostname; 4 to 32 characters

Returns an audit log entry for the operation.

Apply pending upgrades

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

Applies all hardware upgrades that have been staged on an instance (for example a CPU or memory increase requested while the instance was online). The instance must be offline unless restart is set to true.

Request body

Field	Type	Required	Description
instance	integer	yes	Instance ID
restart	boolean		Power the instance off before applying upgrades; defaults to false

Returns a workflow.

Upgrade an instance

POST/v1/commands/upgrade-instanceUpgrades an instance

Resizes an instance. The body is one of two shapes, chosen by the type discriminator. The instance must be in AVAILABLE state and not locked. If the instance is currently online, the new specs take effect on the next restart and a pending-upgrades flag is set; billing is adjusted immediately.

Common body fields (both shapes)

Field	Type	Required	Description
type	string	yes	PLAN or CUSTOM
instance	integer	yes	Instance ID

PLAN body adds

Field	Type	Required	Description
plan	integer	yes	Plan ID; takes all specs and the flat price from the plan

CUSTOM body adds

Field	Type	Required	Description
cpu	integer		Number of vCPU cores
memory	integer		Memory in bytes
download	integer		Download speed cap in bytes/sec
upload	integer		Upload speed cap in bytes/sec
disk	integer		Boot disk size in bytes; can only grow, never shrink
io_limits	object		Disk I/O limits: read_bytes_sec, write_bytes_sec, read_iops, write_iops

Returns a workflow.

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	integer[]	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 a workflow.

Batch terminate

POST/v1/commands/batch-instance-terminateTerminates a batch of instances

Terminates multiple instances. Requires the Administrator role on each instance's workspace. Locked instances are skipped.

When immediate is false, each instance is scheduled for deletion in 3 days and powered off now; use cancel termination to undo a scheduled deletion.

Request body

Field	Type	Required	Description
instances	integer[]	yes	List of instance IDs
immediate	boolean	yes	true to delete now, false to schedule deletion in 3 days

Returns a workflow.

Batch suspend

POST/v1/commands/batch-instance-suspendSuspends or resumes a batch of instances

Administrator only. Suspends or resumes multiple instances in a single call. To suspend, instances must be AVAILABLE; to resume, they must be SUSPENDED.

Request body

Field	Type	Required	Description
instances	integer[]	yes	List of instance IDs
suspend	boolean	yes	true to suspend, false to resume

Returns a workflow.

Cancel a termination

POST/v1/commands/cancel-terminationCancels the deletion of an instance

Cancels a scheduled termination and resumes the instance to an offline state. Has no effect if no termination is scheduled.

Request body

Field	Type	Required	Description
instance	integer	yes	Instance ID

Returns an audit log entry.

Terminate an instance

POST/v1/commands/terminate-instancePermanently deletes an instance

Permanently removes an instance and frees its resources. When immediate is false, the instance is suspended and scheduled for deletion in 3 days; that scheduled deletion can be cancelled with cancel termination.

Request body

Field	Type	Required	Description
instance	integer	yes	Instance ID
immediate	boolean	yes	true to delete now, false to schedule deletion in 3 days

Returns a workflow.

Migrate an instance

POST/v1/commands/migrate-instanceMigrates an instance to another node

Administrator only. Moves an instance to a different compute node. If node is omitted, the platform selects a suitable target node automatically.

Request body

Field	Type	Required	Description
instance	integer	yes	Instance ID
node	integer		Target node ID; omit to let the platform choose
region	string		Target region; used only when node is omitted

Returns a workflow.

Suspend an instance

POST/v1/commands/suspend-instanceSuspends or resumes a single instance

Administrator only. Suspends or resumes a single instance.

Request body

Field	Type	Required	Description
instance	integer	yes	Instance ID
suspend	boolean	yes	true to suspend, false to resume

Returns an audit log entry.