POST /virtual_machines 

Create a new VS


Request Parameters

memory* - amount of RAM assigned to the VS

cpus* - number of CPUs assigned to the VS

cpu_shares* - required parameter. For KVM hypervisor the CPU priority value is always 100. For XEN, set a custom value. The default value for XEN is 1

hostname* - set the host name for this VS

label* - user-friendly VS description

primary_disk_size* - set the disk space for this VS

swap_disk_size* - set swap space. There is no swap disk for Windows-based VSs

type_of_format - type of filesystem - ext4. For Linux templates, you can choose ext4 file system instead of the ext3 default one

primary_disk_type - set the storage type "HDD" or "SSD" for the primary disk

swap_disk_type - set the storage type "HDD" or "SSD" for the swap disk

primary_network_id - the ID of the primary network. Optional parameter that can be used only if it is assigned to the network zone

primary_network_group_id - the ID of the primary network group. Optional parameter

required_automatic_backup - set 1 if you need automatic backups

rate_limit - set max port speed. Optional parameter: if none set, the system sets port speed to unlimited

required_virtual_machine_build* - set 1 to build VS automatically

required_virtual_machine_startup - set 1 to start up the VS automatically, otherwise set 0 (default state is "1")

required_ip_address_assignment* - set "1" if you want IP address to be assigned automatically after creation. Otherwise set "0"

admin_note - enter a brief comment for the VS. Optional parameter

note - a brief comment a user can add to a VS

template_id* - the ID of a template from which a VS should be built, alternatively template_label can be used to declare a template.

template_label* - the label of a template from which a VS should be built, can be used instead of template_id

hypervisor_group_id - the ID of the hypervisor zone in which the VS will be created. Optional: if no hypervisor zone is set, the VS will be built in any available hypervisor zone

hypervisor_id - the ID of a hypervisor where the VS will be built. Optional: if no hypervisor ID is specified, the VS will be built on the hypervisor with the least available RAM (but sufficient RAM for the VS)

initial_root_password - the root password for a VS. Optional, if none specified, the system will provide a random password. It can consist of 6-32 characters, letters [A-Za-z], digits [0-9], dash [ - ] and lower dash [ _ ]. You can use both lower- and uppercase letters

NOTE: It is not possible to set VS password when creating a Windows-based VMware virtual server without running a sysprep.

custom_variables - an array of custom variables with the following details:

  • enabled - true, if the variable is enabled, otherwise false
  • id - variable ID
  • name - variable name
  • value - variable value script

Response Parameters

add_to_marketplace – true, if the edge server is added to marketplace. The default value is "false". This parameter is for CDN servers only.

admin_note - administrator comment for the VS

allowed_resize_without_reboot – true if resize without reboot is allowed, otherwise false

allowed_hot_migrate – true if hot migration is allowed, otherwise false

allowed_swap – true if swap is allowed, otherwise false

booted - true, if the VS is boothed, otherwise false

built - true, if the VS is built, otherwise false

cpu_shares - the percentage of allocated CPU priority resource

cpus - number of CPUs assigned to the VS

created_at – the date when the VS was created in the [YYYY][MM][DD]T[hh][mm][ss] format

updated_at – the date when the VS was updated in the [YYYY][MM][DD]T[hh][mm][ss] format

customer_network_id - ID of the customer network

edge_server_type - type of the CDN edge server. This parameter is for CDN servers only.

enable_autoscale — true if autoscaling is allowed for this VS

enable_monitis - deprecated attribute

firewall notrack - parameter for adding firewall rules. It true for edge servers only. 

hostname - VS hostname

hypervisor_id – the ID of the hypervisor, on which the server is deployed

id – the VS ID

identifier – the VS identifier

initial_root_password — the VS root password

initial_root_password_encrypted - true, if the root password is encrypted, otherwise false

label - user-friendly VS description

local_remote_access_ip_address - IP address for remote connection

local_remote_access_port  - port for remote connection

locked - true if the VS is locked; otherwise false

memory - the RAM size allocated to this VS

min_disk_size — the minimum disk size required to build a VS from a specified template

operating_system — operating system used by the VS

operating_system_distro — the distribution of the OS from which this VS is built

recovery_mode - true if recovery mode allowed, otherwise false

remote_access_password — the password for the remote access

service_password - password of a service user

storage_server_type - 

strict_virtual_machine_id - the ID of a virtual machine that will never reside on the same HV with this VS

suspended - true if VS is suspended, otherwise false

template_id - the ID of the template the VS is based on

template_label - the name of the template from which this VS is built

user_id — the ID of a user assigned to this VS

vip — true if the VS has VIP status (gives migration priority)

xen_id — the VS ID set by the virtualization engine

 ip_addresses - an array of IP addresses with the following parameters:

  • address - IP address
  • broadcast - broadcast address
  • created_at - the date when the IP address was created in the [YYYY][MM][DD]T[hh][mm][ss]Z format
  • disallowed_primary - true if not allowed to be used as primary (for VS build), otherwise false
  • gateway - gateway address
  • id - the ID of the IP address
  • ip_address_pool_id - ID of the IP address pool to the IP address belongs to
  • network_address - the address of the network
  • network_id - the ID of the network
  • updated_at - the date when the IP address was updated in the [YYYY][MM][DD]T[hh][mm][ss]Z format
  • user_id - the ID of a user associated with this IP address
  • free - true if free, otherwise false
  • netmask - netmask for the IP address

monthly_bandwidth_used - VS monthly bandwidth in KB

total_disk_size - total VS disk size

JSON Request example

 curl -i -X POST -H 'Accept: application/json' -H 'Content-type: application/json' -u user:userpass -d '{
    "virtual_machine": {
        "template_id": "10",
        "label": "lazar",
        "hostname": "lazar",
        "initial_root_password": "tyrh",
        "memory": "2000",
        "cpus": "1",
        "cpu_shares": "1",
        "primary_disk_size": "25",
        "required_ip_address_assignment": "1",
        "required_automatic_backup": "1",
        "required_virtual_machine_build": "1"
}' --url <api_url>/virtual_machines.json

JSON Response

    "virtual_machine": {
        "add_to_marketplace": null,
        "admin_note": null,
        "allowed_hot_migrate": true,
        "allowed_swap": true,
        "booted": false,
        "built": false,
        "cores_per_socket": 0,
        "cpu_shares": 1,
        "cpu_sockets": null,
        "cpu_threads": null,
        "cpu_units": 10,
        "cpus": 1,
        "created_at": "2015-08-25T01:19:49+00:00",
        "customer_network_id": null,
        "deleted_at": null,
        "edge_server_type": null,
        "enable_autoscale": null,
        "enable_monitis": null,
        "firewall_notrack": false,
        "hostname": "myHost",
        "hypervisor_id": 7,
        "id": 123,
        "identifier": "v0qm2yndtmegyx",
        "initial_root_password_encrypted": false,
        "iso_id": null,
        "label": "zaza",
        "local_remote_access_ip_address": "",
        "local_remote_access_port": null,
        "locked": true,
        "memory": 528,
        "min_disk_size": 5,
        "note": null,
        "operating_system": "linux",
        "operating_system_distro": "lbva",
        "preferred_hvs": [
        "recovery_mode": null,
        "remote_access_password": "password",
        "service_password": null,
        "state": "building",
        "storage_server_type": null,
        "strict_virtual_machine_id": null,
        "suspended": false,
        "template_id": 10,
        "template_label": "Load Balancer Virtual Appliance",
        "updated_at": "2015-08-25T01:19:49+00:00",
        "user_id": 123,
        "vip": null,
        "xen_id": null,
        "ip_addresses": [
                "ip_address": {
                    "address": "",
                    "broadcast": "",
                    "created_at": "2015-07-30T01:35:55+00:00",
                    "customer_network_id": null,
                    "disallowed_primary": false,
                    "gateway": "",
                    "hypervisor_id": null,
                    "id": 1234,
                    "ip_address_pool_id": null,
                    "network_address": "",
                    "network_id": 1,
                    "pxe": false,
                    "updated_at": "2015-08-25T01:19:49+00:00",
                    "user_id": null,
                    "free": false,
                    "netmask": ""
        "monthly_bandwidth_used": "0",
        "total_disk_size": 11,
        "price_per_hour": 0.01108394,
        "price_per_hour_powered_off": 0.00305558,
        "support_incremental_backups": true,
        "cpu_priority": 1

XML Request example

 curl -i -X POST -H 'Accept: application/xml' -H 'Content-type: application/xml' -u user:userpass -d
<primary_disk_size>30</primary_disk_size><required_ip_address_assignment>1</required_ip_address_assignment><required_automatic_backup>0</required_automatic_backup><required_virtual_machine_build>1</required_virtual_machine_build></virtual_machine>' --url <api_url>/virtual_machines.xml

XML Response example

 <?xml version="1.0" encoding="UTF-8"?>
  <add_to_marketplace nil="true"/>
  <admin_note nil="true"/>
  <allow_resize_without_reboot type="boolean">false</allow_resize_without_reboot>
  <allowed_hot_migrate type="boolean">true</allowed_hot_migrate>
  <allowed_swap type="boolean">true</allowed_swap>
  <booted type="boolean">false</booted>
  <built type="boolean">false</built>
  <cpu_shares type="integer">1</cpu_shares>
  <cpus type="integer">1</cpus>
  <created_at type="datetime">2013-06-11T16:03:58+03:00</created_at>
  <customer_network_id nil="true"/>
  <deleted_at nil="true"/>
  <edge_server_type nil="true"/>
  <enable_autoscale type="boolean">false</enable_autoscale>
  <enable_monitis type="boolean">false</enable_monitis>
  <firewall_notrack type="boolean">false</firewall_notrack>
  <hypervisor_id type="integer">1</hypervisor_id>
  <id type="integer">15</id>
  <initial_root_password_encrypted type="boolean">false</initial_root_password_encrypted>
  <local_remote_access_port nil="true"/>
  <locked type="boolean">true</locked>
  <memory type="integer">128</memory>
  <min_disk_size type="integer">5</min_disk_size>
  <note nil="true"/>
  <preferred_hvs type="array"/>
  <recovery_mode nil="true"/>
  <service_password nil="true"/>
  <storage_server_type nil="true"/>
  <strict_virtual_machine_id nil="true"/>
  <suspended type="boolean">false</suspended>
  <template_id type="integer">8</template_id>
  <template_label>Ubuntu 13.04 x64</template_label>
  <updated_at type="datetime">2013-06-11T16:03:59+03:00</updated_at>
  <user_id type="integer">1</user_id>
  <vip nil="true"/>
  <xen_id nil="true"/>
  <ip_addresses type="array">
      <created_at type="datetime">2013-06-11T14:16:21+03:00</created_at>
      <customer_network_id nil="true"/>
      <disallowed_primary type="boolean">false</disallowed_primary>
      <hypervisor_id nil="true"/>
      <id type="integer">386</id>
      <ip_address_pool_id nil="true"/>
      <network_id type="integer">9</network_id>
      <pxe type="boolean">false</pxe>
      <updated_at type="datetime">2013-06-11T14:16:21+03:00</updated_at>
      <user_id nil="true"/>
      <free type="boolean">false</free>
  <total_disk_size type="integer">6</total_disk_size>