Virtual Machine: Create

To reduce HTTP calls, a transactional version of POST virtual_machinesPOST discsand POST reimage are provided in a single call:


Relative to

POST /accounts/{account-id}/groups/{group-id}/vm_create

It takes a JSON data hash like:

  "virtual_machine": { ... },
  "discs": [ { ... }, { ... } ],
  "reimage": { ... },
  "ips": {
    "ipv4": "x.x.x.x",
    "ipv6": "xxxx:xxxx:xxxx:xxxx:xxxx::x"


Common attributes are listed below. Please see virtual machines for a complete list of options.

  • virtual_machine
    • cdrom_url – URL of an ISO to expose to the VM as a CD drive.
    • cores – number of CPU cores.
    • memory – amount of memory, in megabytes.
    • name – name of the virtual machine.
    • hardware_profile – which hardware profile to use (see the definitions page)
    • power_on – boolean specifying whether the machine should be turned on.
  • discs
    • label – Unix device label – this can be any string to identify the drive.
    • size – size in megabytes.
    • storage_grade – device type: SATA or archive.
  • reimage
    • distribution – the name of a distribution — valid options are available by calling GET /definitions.
    • root_password – the root password the machine should have after reimaging.
    • ssh_public_key – if specified, the contents of /root/.ssh/authorized_keys (for Linux distributions). Allows passwordless login.
    • firstboot_script – if specified, an arbitrary executable to be run on first boot (for Linux distributions). This should be a full, executable script, probably starting #!/bin/sh
  • ips
    • ipv4 – The IPv4 address the VM should have.
    • ipv6 – The IPv6 address the VM should have.
‘ips’ attributes are optional, and only valid for private VLANs

This allows you to specify specific IP addresses for the virtual machine to use instead of them being automatically selected. You can select one or the other of these. For example, you can specify an IPv4 address, but leave the IPv6 to be automatically allocated.

This will fail if another virtual machine exists with that same IP, but it will not check whether there is anything else on the network with that IP. For example, if you have a Dedicated Server already using that IP address, you will likely break the networking to that server by using its IP address here.

Return codes

POST vm_create will return 202 on success, and will process the creation in the background. You will need to poll and check the power_on attribute for when the machine has been powered on (if power_on was set to true when created).


POST /accounts/myaccountname/groups/default/vm_create
curl -H "Content-type: application/json" \
     -H "Authorization: Bearer {session-id}" \
     -X POST \
     -d '{"virtual_machine":{"name":"myserver1","cores":1,"memory":1024}, "discs":[{"label":"root","storage_grade":"sata","size":25600}], "reimage":{"distribution":"precise", "root_password":"mypassword"}}' \
Response (success: 202)
Updated on May 22, 2019

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