POST /api/vms/{id}/shutdown

Stop a VM and tear down its running host resources.

Property	Value
Scope	readwrite
Request body	none
Success	204 No Content

Endpoint

POST ${baseUrl}/api/vms/${id}/shutdown

readwrite

Stop a VM and tear down its running host resources.

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}/shutdown" \
  --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	Shutdown completed at the host API layer.

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}/shutdown" \
  --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 shutdown.
500	CH_ERROR, STORAGE_ERROR, or INTERNAL	Host failed to stop or clean up VM resources.