VM Actions (Start, Stop, Reboot)

POST/v2.1/servers/{server_id}/action

Most lifecycle operations on an existing VM use the same endpoint with a different action key in the body. The request is asynchronous: the API returns 202 Accepted and the VM status changes a moment later, so poll GET /v2.1/servers/{server_id} until it reaches the expected status.

info

Source: server-actions

Request

Parameters

server_idstringrequiredpath

The UUID of the VM.

os-startnullrequiredbody

Start a stopped VM. Requires status SHUTOFF.

os-stopnullrequiredbody

Stop a running VM (graceful ACPI shutdown, then forced after the configured timeout).

rebootobjectrequiredbody

Reboot a running VM.

1 field

typestringrequiredbody

SOFT (graceful) or HARD (power cycle).

pausenullrequiredbody

Freeze the VM in memory. Requires status ACTIVE.

unpausenullrequiredbody

Undo pause.

suspendnullrequiredbody

Suspend the VM and release its memory on the host. Requires status ACTIVE.

resumenullrequiredbody

Undo suspend.

locknullrequiredbody

Prevent other users and some API actions from changing the VM.

unlocknullrequiredbody

Remove the lock.

The action key must be the only key in the body. Sending two actions in one request returns 400.

Action reference

Action	Body	Requires status	Resulting status
Start	{"os-start": null}	SHUTOFF	ACTIVE
Stop	{"os-stop": null}	ACTIVE	SHUTOFF
Reboot (graceful)	{"reboot": {"type": "SOFT"}}	ACTIVE	ACTIVE
Reboot (hard)	{"reboot": {"type": "HARD"}}	ACTIVE	ACTIVE
Pause	{"pause": null}	ACTIVE	PAUSED
Unpause	{"unpause": null}	PAUSED	ACTIVE
Suspend	{"suspend": null}	ACTIVE	SUSPENDED
Resume	{"resume": null}	SUSPENDED	ACTIVE
Lock	{"lock": null}	any	unchanged
Unlock	{"unlock": null}	locked	unchanged

warning

HARD reboot and os-stop with a VM that has unsaved data can lose writes. Use SOFT reboot, or shut down from inside the guest, when the workload is not disposable.

Sample Request — stop a VM

cURL

curl -ks -X POST -H 'Content-Type: application/json' -H 'X-Auth-Token: gAAAAA<...>' \
-d '{"os-stop": null}' \
https://api.vietnix.cloud:8774/v2.1/servers/{server_id}/action

HTTP

POST https://api.vietnix.cloud:8774/v2.1/servers/{server_id}/action
Content-Type: application/json
X-Auth-Token: gAAAAA<...>

{
  "os-stop": null
}

Sample Request — graceful reboot

curl -ks -X POST -H 'Content-Type: application/json' -H 'X-Auth-Token: gAAAAA<...>' \
-d '{"reboot": {"type": "SOFT"}}' \
https://api.vietnix.cloud:8774/v2.1/servers/{server_id}/action

Response

The response body is empty. The action is tracked through the VM status.

Status Code

Success

Status Code	Description
202 - Accepted	The action was accepted and is being processed.

Error

Status Code	Description
400 - Bad Request	The action is unknown, or more than one action was sent.
401 - Unauthorized	User must authenticate before making a request.
403 - Forbidden	Policy does not allow current user to do this operation.
404 - Not Found	The VM does not exist, or is not visible to your project.
409 - Conflict	The VM is in a status that does not allow this action (for example os-start on an ACTIVE VM).

note

os-start does not bring back a shelved VM. Use {"unshelve": null} for that, and {"shelve": null} to shelve one. Shelving releases the compute resources while keeping the VM definition and volumes.