DELETE /api/vms/{id}

Delete a VM record and the resources owned by that VM.

Caution

This is destructive. Read the VM state before deleting it from automation.

Property	Value
Scope	readwrite
Request body	none
Success	204 No Content

Endpoint

DELETE ${baseUrl}/api/vms/${id}

readwrite

Remove a VM and agent-owned 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 DELETE "${baseUrl}/api/vms/${id}" \
  --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	VM record and agent-owned resources were removed.

Examples

Call example

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

curl --request DELETE "${baseUrl}/api/vms/${id}" \
  --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.
500	CH_ERROR, STORAGE_ERROR, or INTERNAL	Host failed while tearing down resources.