Virtual Machines

These calls allow management of virtual machines (also known as Cloud severs).

The rules for what can be changed on a running virtual machine are currently complex — the best advice is to power down a virtual machine before making any changes to it, or be prepared to handle a refusal from the API.


These are relative to

GET /accounts/{account-id}/groups/{group-id}/virtual_machines
GET /accounts/{account-id}/groups/{group-id}/virtual_machines/{vm-id}
POST /accounts/{account-id}/groups/{group-id}/virtual_machines
PUT /accounts/{account-id}/groups/{group-id}/virtual_machines/{vm-id}
DELETE /accounts/{account-id}/groups/{group-id}/virtual_machines/{vm-id}

# Non-nested endpoints (currently only GET)
GET /virtual_machines
GET /virtual_machines?account_id={account-id}
GET /virtual_machines?group_id={group-id}
GET /virtual_machines/{vm-id}
  • Replace {account-id} with the account id or name.
  • Replace {group-id} with the group id or name (or default if you don’t use groups!).
  • Replace {vm-id} with the id of the virtual machine.

Additional endpoints


  • autoreboot_on — boolean specifying whether the machine will automatically turn back on on shutdown/reboot.
  • cdrom_url — url of an iso to expose to the vm as a cd drive.
  • cores — number of cpu cores available.
  • memory — amount of memory, in megabytes.
  • name — name of the virtual machine.
  • power_on — boolean specifying whether the machine is turned on.
  • keymap
  • hardware_profile — which hardware profile is being used (see the definitions page)
  • hardware_profile_locked — whether the hardware profile is locked and therefore will not be auto upgraded.
  • group_id — id of the group this virtual machine belongs to.

Read Only Attributes

These are returned in responses, but can not be set by the user

  • id — unique key (integer).
  • management_address — ssh’ing to this IP will allow (out-of-band) access to the virtual machine using its console. If the VM is not responding or you are locked out for some reason, this is very useful! This is only available from another Bytemark IP Address or prearranged IPs.
  • deleted — boolean specifying whether the machine has been deleted.
  • hostname — bigv hostname for the machine.
  • head — location of the VM on Bytemark’s host machines (heads).
  • zone_name — which zone the virtual machine was created in (see the definitions page). This can be set when creating, but not changed.
  • last_imaged_with — The name of the operating system this virtual machine was last imaged with, according to our records.


If you would like to see deleted virtual machines (i.e. virtual machines in which the deleted field is set to true), you need to pass the include_deleted=true parameter through in the query string, e.g.:

GET /accounts/myaccountname/groups/default/virtual_machines?include_deleted=true

# Or if you are using the overview parameter in accounts:
GET /accounts?view=overview&include_deleted=true

Creating a virtual machine

It is possible to create a virtual machine by using POST /accounts/{account-id}/groups/{group-id}/virtual_machines, but it will only be a machine; it will not have a disc or be installed with anything.

To create a virtual machine with discs and an operating system see the create page.

Moving virtual machines between groups

By specifying the group_id in a PUT request body, you can move a virtual machine to another group (which may be in any account). The requester must be at least a group administrator for both groups.

Currently, the virtual machine must be powered off. Additionally, if one of the groups is associated with a private VLAN, the second group must be associated with the same private VLAN.


The signal endpoint can be used to send ACPI signals to the machine, but there is also the more brute force approach — like the mains plug on a physical machine.

  • The power_on attribute specifies if the machine should be turned on or off.
  • The autoreboot_on attribute specifies if the machine should be restarted upon power off.

Therefore the following can be achieved:


autoreboot_on = true
power_on = true


autoreboot_on = false
power_on = false


autoreboot_on = true
power_on = false

Deleting and Purging

When a virtual machine is deleted using the DELETE endpoint, it still exists, but has its deleted attribute set to true. This means it will be taken down and will only show when the include_deleted=true query string is used.

However, it can be undeleted by setting deleted back to false for a certain amount of time after deletion.

If you wish to purge a virtual machine — either a previously deleted one or to delete a live one and ensure that it can’t be undeleted, you can use the purge=true query string with the DELETE endpoint. This will completely remove the server, put the IP address back into the pool and allow the name to be re-used.

DELETE /accounts/{account-id}/groups/{group-id}/virtual_machines/{vm-id}?purge=true


All virtual machines in a group


GET /accounts/myaccountname/groups/default/virtual_machines


curl -H "Content-type: application/json" \
     -H "Authorization: Bearer {session-id}" \

Response (success: 200)


Single virtual machines


GET /accounts/myaccountname/groups/default/virtual_machines/1234


curl -H "Content-type: application/json" \
     -H "Authorization: Bearer {session-id}" \

Response (success: 200)




PUT /accounts/myaccountname/groups/default/virtual_machines/45


curl -H "Content-type: application/json" \
     -H "Authorization: Bearer {session-id}" \
     -X PUT \
     -d '{"power_on":false,"autoreboot_on":false}' \

Response (success: 200)




DELETE /accounts/myaccountname/groups/default/virtual_machines/45


curl -H "Content-type: application/json" \
     -H "Authorization: Bearer {session-id}" \
     -X DELETE \

Response (success: 204)

Updated on September 14, 2020

Was this article helpful?

Related Articles

Have you tried Kubernetes?
Kubernetes (K8s) is helping enterprises to ship faster & scale their business. Sounds good? Let us build a K8s solution for your needs.
Register your interest