POST /api/vms/{id}/power-button

Ask the guest OS to shut down cleanly. The host falls back to a hard stop if the graceful path does not complete.

Property	Value
Scope	readwrite
Request body	none
Success	204 No Content

Endpoint

POST ${baseUrl}/api/vms/${id}/power-button

readwrite

Ask the guest OS to shut down, with a hard-stop fallback.

Use your host URL and API key as shell variables:

baseUrl="https://agent.example.com"
VIRT_AGENT_API_KEY="<your-api-key>"

cURL template

curl --request POST "${baseUrl}/api/vms/${id}/power-button" \
  --header "Authorization: Bearer ${VIRT_AGENT_API_KEY}"

Request

Location	Name	Type	Required	Description
Header	Authorization	bearer token	yes	Bearer ${VIRT_AGENT_API_KEY} from a readwrite key.
Path	id	string	yes	VM id.

Response

Status	Body	Description
204 No Content	none	ACPI power button was sent or the host accepted the graceful shutdown flow.

Examples

Call example

baseUrl="https://agent.example.com"
VIRT_AGENT_API_KEY="<your-api-key>"
id="demo-api-vm"

curl --request POST "${baseUrl}/api/vms/${id}/power-button" \
  --header "Authorization: Bearer ${VIRT_AGENT_API_KEY}"

Response example

HTTP/1.1 204 No Content

Errors

Status	Code	Description
401	UNAUTHORIZED	API key is missing or invalid.
403	FORBIDDEN	Key is read-only or endpoint is outside the key allowlist.
404	NOT_FOUND	VM id does not exist.
409	INVALID_STATE	VM state does not allow power-button shutdown.
500	CH_ERROR or INTERNAL	Host failed to deliver or complete the shutdown flow.