API Endpoint api.exoscale.ch/compute
Protocol HTTPS
Port 443
Authentication True

Making API requests

To make API requests against our Compute API, you need to pass to the API url commands and parameters in the form:

https://api.exoscale.ch/compute?command=deployVirtualMachine&serviceofferingid=21624abb-764e-4def-81d7-9fc54b5957fb&templateid=54c83a5e-c548-4d91-8b14-5cf2d4c081ee&zoneid=1128bd56-b4d9-4ac6-a7b9-c715b187ce11&apikey=miVr6X7u6bN_sdahOBpjNejPgEsT35eXqjB8CG20&signature=ahlpA6J1Fq6OYI1HFrMSGgBt0WY%3D

Here is the breakdown of the request:

  1. https://api.exoscale.ch/compute
  2. ?command=deployVirtualMachine
  3. &serviceofferingid=21624abb-764e-4def-81d7-9fc54b5957fb
  4. &templateid=54c83a5e-c548-4d91-8b14-5cf2d4c081ee
  5. &zoneid=1128bd56-b4d9-4ac6-a7b9-c715b187ce11
  6. &apikey=miVr6X7u6bN_sdahOBpjNejPgEsT35eXqjB8CG20
  7. &signature=ahlpA6J1Fq6OYI1HFrMSGgBt0WY%3D

The first line is the API URL.

The second line refers to the command you wish to execute. In our example, we are attempting to deploy a fresh new virtual machine. It is preceded by a (?) to separate itself from the API URL.

Lines 3-5 are the parameters for this given command. To see the command and its request parameters, please refer to the appropriate section in the API documentation below. Each parameter field-value pair (field=value) is preceded by an ampersand character (&).

Line 6 is the user API Key that uniquely identifies the account.

Line 7 is the signature hash created to authenticate the user account executing the API command.

Note: each field is case insensitive but its value should be considered case sensitive.

Signing API requests:

The command string needs to hashed using HMAC SHA-1 hashing algorithm against the API secret key. The resulting byte array should be Base64 encoded in UTF-8 format so that it can be passed via http.

To generate the signature you have to lower case the complete list of request parameters and sort them alphabetically via the field for each field-value pair. The resulting string to sign from the previous example with a secret key VDaACYb0LV9eNjTetIOElcVQkvJck_J_QljX would be:

apikey=mivr6x7u6bn_sdahobpjnejpgest35exqjb8cg20&command=deployvirtualmachine&serviceofferingid=21624abb-764e-4def-81d7-9fc54b5957fb&templateid=54c83a5e-c548-4d91-8b14-5cf2d4c081ee&zoneid=1128bd56-b4d9-4ac6-a7b9-c715b187ce11

Resulting in a signature value of:

ahlpA6J1Fq6OYI1HFrMSGgBt0WY%3D

Note: spaces are expected to be replaced by %20 when encoding the URL.

Here is a Python3 example of the signature implementation from the library we recommend, cs.

import base64
import hashlib
import hmac
import json
from urllib.request import urlopen
from urllib.parse import quote, urlencode

API_KEY = "miVr6X7u6bN_sdahOBpjNejPgEsT35eXqjB8CG20"
API_SECRET= "VDaACYb0LV9eNjTetIOElcVQkvJck_J_QljX"

COMPUTE_ENDPOINT = "https://api.exoscale.ch/compute"

def sign(command, secret):
  """Adds the signature bit to a command expressed as a dict"""
  # order matters
  arguments = sorted(command.items())

  # urllib.parse.urlencode is not good enough here.
  # key contains should only contain safe content already.
  # safe="*" is required when producing the signature.
  query_string = "&".join("=".join((key, quote(value, safe="*")))
                          for key, value in arguments)

  # Signing using HMAC-SHA1
  digest = hmac.new(
      secret.encode("utf-8"),
      msg=query_string.lower().encode("utf-8"),
      digestmod=hashlib.sha1).digest()

  signature = base64.b64encode(digest).decode("utf-8")

  return dict(command, signature=signature)


# The command contains the apikey and the parameters
command = {
  "command":           "deployVirtualMachine",
  "serviceofferingid": "21624abb-764e-4def-81d7-9fc54b5957fb",
  "templateid":        "54c83a5e-c548-4d91-8b14-5cf2d4c081ee",
  "zoneid":            "1128bd56-b4d9-4ac6-a7b9-c715b187ce11",
  "apikey":            API_KEY,
}

# Signing the request and URL encoding it
params = sign(command, API_SECRET)
query_string = urlencode(params)

# As GET
with urlopen(f"{COMPUTE_ENDPOINT}?{query_string}") as f:
  response = json.load(f)

# As POST
with urlopen(COMPUTE_ENDPOINT, query_string.encode("utf-8")) as f:
  response = json.load(f)

API call types

There are 2 distinct types of call on the Exoscale Compute API:

  • Sync: synchronous call, the call answer is provided in the payload of the GET or POST answer.
  • Async: asynchronous calls. These calls return a JobID that matches to the job being executed in the background. You can then query the status of the Async job via the command queryAsyncJobResult. They are marked in this page with .

More detailed information on the API calls can be found on Apache CloudStack developer website

Virtual Machines

GET deployVirtualMachine Async

Description

Creates and automatically starts a virtual machine based on a service offering, disk offering, and template.

Request Parameters

Parameter Description Required
serviceofferingid

the ID of the service offering for the virtual machine

templateid

the ID of the template for the virtual machine

zoneid

availability zone for the virtual machine

affinitygroupids

comma separated list of affinity groups id that are going to be applied to the virtual machine. Mutually exclusive with affinitygroupnames parameter

affinitygroupnames

comma separated list of affinity groups names that are going to be applied to the virtual machine.Mutually exclusive with affinitygroupids parameter

details

used to specify the custom parameters.

displayname

an optional user generated name for the virtual machine

displayvm

an optional field, whether to the display the vm to the end user or not.

group

an optional group for the virtual machine

ip4

a future optional boolean attribute to request an IPv4. Currently defaults to true and not modifiable.

ip6

an optional boolean attribute to request an IPv6 for the machine on the default nic. Currently defaults to false if not specified.

keyboard

an optional keyboard device type for the virtual machine. valid value can be one of de,de-ch,es,fi,fr,fr-be,fr-ch,is,it,jp,nl-be,no,pt,uk,us

keypair

name of the ssh key pair used to login to the virtual machine

name

host name for the virtual machine

networkids

list of network ids used by virtual machine. Can’t be specified with ipToNetworkList parameter

rootdisksize

Optional size in gigabyte of the disk

securitygroupids

comma separated list of security groups id that going to be applied to the virtual machine. Should be passed only when vm is created from a zone with Basic Network support. Mutually exclusive with securitygroupnames parameter

securitygroupnames

comma separated list of security groups names that going to be applied to the virtual machine. Should be passed only when vm is created from a zone with Basic Network support. Mutually exclusive with securitygroupids parameter

startvm

true if the vm should start after creation; defaults to true if not specified.

userdata

an optional binary data that can be sent to the virtual machine upon a successful deployment. This binary data must be base64 encoded before adding it to the requests. Using HTTP GET (via querystring), you can send up to 2KB of data after base64 encoding. Using HTTP POST(via POST body), you can send up to 32K of data after base64 encoding.

Answer

{
    "virtualmachine": {
        "account": "account@email.com",
        "cpunumber": 1,
        "cpuspeed": 2198,
        "cpuused": "0.22%",
        "created": "2013-12-19T22:28:31+0100",
        "displayname": "vagrant_1387488511",
        "guestosid": "113038d0-a8cd-4d20-92be-ea313f87c3ac",
        "haenable": false,
        "hypervisor": "KVM",
        "id": "8e5fe56d-6d8a-4210-b826-73327b9385dc",
        "keypair": "vagrant",
        "memory": 512,
        "name": "8e5fe56d-6d8a-4210-b826-73327b9385dc",
        "networkkbsread": 10060,
        "networkkbswrite": 5443,
        "nic": [
            {
                "gateway": "185.19.28.1",
                "id": "672bf4f3-8ed0-4581-9b3d-b6cd4c4fe8e6",
                "ipaddress": "185.19.28.148",
                "isdefault": true,
                "macaddress": "06:78:f8:00:00:d1",
                "netmask": "255.255.254.0",
                "networkid": "00304a04-c7ea-4e77-a786-18bc64347bf7",
                "traffictype": "Guest",
                "type": "Shared"
            }
        ],
        "passwordenabled": true,
        "rootdeviceid": 0,
        "rootdevicetype": "Filesystem",
        "securitygroup": [
            {
                "description": "Default Security Group",
                "id": "b87ff34d-abf3-42d3-a097-78075515dd34",
                "name": "default"
            }
        ],
        "serviceofferingid": "71004023-bb72-4a97-b1e9-bc66dfce9470",
        "serviceofferingname": "Micro",
        "state": "Stopped",
        "tags": [],
        "templatedisplaytext": "Linux Ubuntu 12.04 LTS 64-bit 10GB Disk",
        "templateid": "a17b40d6-83e4-4f2a-9ef0-dce6af575789",
        "templatename": "Linux Ubuntu 12.04 LTS 64-bit",
        "zoneid": "1128bd56-b4d9-4ac6-a7b9-c715b187ce11",
        "zonename": "CH-GV2"
    }
}

GET destroyVirtualMachine Async

Description

Destroys a virtual machine. Once destroyed, only the administrator can recover it.

Request Parameters

Parameter Description Required
id

The ID of the virtual machine

Answer

{
    "null": {
        "securitygroup": [],
        "nic": [],
        "tags": [],
        "affinitygroup": []
    }
}

GET rebootVirtualMachine Async

Description

Reboots a virtual machine.

Request Parameters

Parameter Description Required
id

The ID of the virtual machine

Answer

{
    "virtualmachine": {
        "state": "Running",
        /* ... */
    }
}

GET scaleVirtualMachine Async

Description

Scales a virtual machine to a new service offering size (requires the virtual machine to be stopped).

Request Parameters

Parameter Description Required
id

The ID of the virtual machine

serviceofferingid

The ID of the service offering for the virtual machine

Answer

{
    "success": "true"
}

GET restoreVirtualMachine Async

Description

Restore a VM to its original template or a new template keeping its service offering and network configuration.

Request Parameters

Parameter Description Required
virtualmachineid

The ID of the virtual machine

templateid

An optional ID for a different template to use for the restoration process.

rootdisksize

Optional size in gigabyte of the disk

Answer

{
    "virtualmachine": { /* modified virtual machine */ }
}

GET startVirtualMachine Async

Description

Starts a virtual machine.

Request Parameters

Parameter Description Required
id

The ID of the virtual machine

rescueprofile

An optional rescue profile when booting. The only supported option is netboot.

Answer

{
    "virtualmachine": {
        "state": "Running",
        /* ... */
    }
}

GET stopVirtualMachine Async

Description

Stops a virtual machine.

Request Parameters

Parameter Description Required
id

The ID of the virtual machine

forced

Force stop the VM (vm is marked as Stopped even when command fails to be send to the backend). The caller knows the VM is stopped.

Answer

{
    "virtualmachine": {
        "state": "Stopped",
        /* ... */
    }
}

GET resetPasswordForVirtualMachine Async

Description

Resets the password for virtual machine. The virtual machine must be in a “Stopped” state and the template must already support this feature for this command to take effect. [async]

Request Parameters

Parameter Description Required
id

The ID of the virtual machine

Answer

{
    "virtualmachine": {
        "password": "<the new password>",
        /* ... */
    }
}

GET changeServiceForVirtualMachine

Description

Changes the service offering for a virtual machine. The virtual machine must be in a “Stopped” state for this command to take effect.

Request Parameters

Parameter Description Required
id

The ID of the virtual machine

serviceofferingid

the service offering ID to apply to the virtual machine

Answer

{
    "virtualmachine": {
        "serviceofferingid": "<id>",
        "serviceofferingname": "<name>",
        /* ... */
    }
}

GET updateVirtualMachine

Description

Updates properties of a virtual machine. The VM has to be stopped and restarted for the new properties to take effect. UpdateVirtualMachine does not first check whether the VM is stopped. Therefore, stop the VM manually before issuing this call.

Request Parameters

Parameter Description Required
id

The ID of the virtual machine

displayname

user generated name

displayvm

an optional field, whether to the display the vm to the end user or not.

group

group of the virtual machine

name

new host name of the vm. The VM has to be stopped/started for this update to take affect.

securitygroupids

a list of the Security Groups UUIDs that you want to associate with this VM.Please note that when adding a group to a VM, you need to pass the complete list of SG associated with the VM, not only the new additions.

userData

an optional binary data that can be sent to the virtual machine upon a successful deployment. This binary data must be base64 encoded before adding it to the requests. Using HTTP GET (via querystring), you can send up to 2KB of data after base64 encoding. Using HTTP POST(via POST body), you can send up to 32K of data after base64 encoding.

Answer

{
    "virtualmachine": { /* modified virtual machine */ }
}

GET listVirtualMachines

Description

List the virtual machines.

Request Parameters

Parameter Description Required
affinitygroupid

list vms by affinity group

details

comma separated list of host details requestsed, value can be a list of [all, group, nics, stats, secgrp, tmpl, servoff, iso, volume, min, affgrp]. If no parameter is passed in, the details will be defaulted to all

forvirtualnetwork

list by network type; true if need to list vms using Virtual Network, false otherwise

groupid

the group ID

id

the ID of the virtual machine

keyword

List by keyword

name

name of the virtual machine

networkid

list by network id

page
pagesize
state

state of the virtual machine

tags

List resources by tags (key/value pairs)

templateid

list vms by template

zoneid

the availability zone ID

Answer

{
    "count": 1,
    "virtualmachine": [
        {
            "account": "account@email.com",
            "cpunumber": 1,
            "cpuspeed": 2198,
            "cpuused": "0.22%",
            "created": "2013-12-19T22:28:31+0100",
            "displayname": "vagrant_1387488511",
            "guestosid": "113038d0-a8cd-4d20-92be-ea313f87c3ac",
            "haenable": false,
            "hypervisor": "KVM",
            "id": "8e5fe56d-6d8a-4210-b826-73327b9385dc",
            "keypair": "vagrant",
            "memory": 512,
            "name": "8e5fe56d-6d8a-4210-b826-73327b9385dc",
            "networkkbsread": 10060,
            "networkkbswrite": 5443,
            "nic": [
                {
                    "gateway": "185.19.28.1",
                    "id": "672bf4f3-8ed0-4581-9b3d-b6cd4c4fe8e6",
                    "ipaddress": "185.19.28.148",
                    "isdefault": true,
                    "macaddress": "06:78:f8:00:00:d1",
                    "netmask": "255.255.254.0",
                    "networkid": "00304a04-c7ea-4e77-a786-18bc64347bf7",
                    "traffictype": "Guest",
                    "type": "Shared"
                }
            ],
            "passwordenabled": true,
            "rootdeviceid": 0,
            "rootdevicetype": "Filesystem",
            "securitygroup": [
                {
                    "description": "Default Security Group",
                    "id": "b87ff34d-abf3-42d3-a097-78075515dd34",
                    "name": "default"
                }
            ],
            "serviceofferingid": "71004023-bb72-4a97-b1e9-bc66dfce9470",
            "serviceofferingname": "Micro",
            "state": "Stopped",
            "tags": [],
            "templatedisplaytext": "Linux Ubuntu 12.04 LTS 64-bit 10GB Disk",
            "templateid": "a17b40d6-83e4-4f2a-9ef0-dce6af575789",
            "templatename": "Linux Ubuntu 12.04 LTS 64-bit",
            "zoneid": "1128bd56-b4d9-4ac6-a7b9-c715b187ce11",
            "zonename": "CH-GV2"
        }
    ]
}

GET getVMPassword

Description

Returns an encrypted password for the VM.

Request Parameters

Parameter Description Required
id

The ID of the virtual machine

Answer

{
    "password": "base64 encoded encryped password with the initial SSH key"
}

GET addNicToVirtualMachine Async

Description

Adds VM to specified network by creating a NIC

Request Parameters

Parameter Description Required
ipaddress

Static IP address lease for the corresponding NIC and network which should be in the range defined in the network. Also, the last IP of the network is reserved by the DHCP server.

networkid

The ID of the network

virtualmachineid

The ID of the virtual machine

Answer

{
    "virtualmachine": {
        "nic": [
            {
                "gateway": "185.19.28.1",
                "id": "672bf4f3-8ed0-4581-9b3d-b6cd4c4fe8e6",
                "ipaddress": "185.19.28.148",
                "isdefault": true,
                "macaddress": "06:78:f8:00:00:d1",
                "netmask": "255.255.254.0",
                "networkid": "00304a04-c7ea-4e77-a786-18bc64347bf7",
                "traffictype": "Guest",
                "type": "Shared"
            },
            {
                "networkid": "<networkid>",
                "ipaddress": "<ipaddress>",
                /* added NIC */
            }
        ],
        /* ... */
    }
}

GET removeNicFromVirtualMachine Async

Description

Removes VM from specified network by deleting a NIC

Request Parameters

Parameter Description Required
nicid

The ID of NIC

virtualmachineid

The ID of the virtual machine

Answer

{
    "virtualmachine": { /* modified virtual machine */ }
}

GET updateVmNicIp Async

Description

Update the default Ip of a VM Nic

Request Parameters

Parameter Description Required
ipaddress

Static IP address lease for the corresponding NIC and network which should be in the range defined in the network. If absent, the call removes the lease associated with the nic.

nicid

the ID of the nic

Answer

{
    "virtualmachine": {
        "nic": [
            {
                "gateway": "185.19.28.1",
                "id": "672bf4f3-8ed0-4581-9b3d-b6cd4c4fe8e6",
                "ipaddress": "185.19.28.148",
                "isdefault": true,
                "macaddress": "06:78:f8:00:00:d1",
                "netmask": "255.255.254.0",
                "networkid": "00304a04-c7ea-4e77-a786-18bc64347bf7",
                "traffictype": "Guest",
                "type": "Shared"
            },
            {
                "id": "<nicid>",
                "ipaddress": "<ipaddress>",
                /* updated NIC */
            }
        ],
        /* ... */
    }
}

Volumes

GET listVolumes

Description

List volumes.

Request Parameters

Parameter Description Required
id

the ID of the disk volume

keyword

List by keyword

name

the name of the disk volume

page
pagesize
tags

List resources by tags (key/value pairs)

type

the type of disk volume

virtualmachineid

the ID of the virtual machine

zoneid

the ID of the availability zone

Answer

No Answer

GET resizeVolume Async

Description

Resize a volume.

Request Parameters

Parameter Description Required
id

the ID of the disk volume

size

new volume size in GB

Answer

{
    "jobid": "<ID to use with queryAsyncJobResult>"
}

Snapshots

GET createSnapshot Async

Description

Creates a snapshot

Request Parameters

Parameter Description Required
volumeid

The ID of the disk volume

Answer

{
    "jobid": "<ID to use with queryAsyncJobResult>"
}

GET listSnapshots

Description

List available snapshots

Request Parameters

Parameter Description Required
id

lists snapshot by snapshot ID

keyword

List by keyword

name

lists snapshot by snapshot name

page
pagesize
tags

List resources by tags (key/value pairs)

volumeid

the ID of the disk volume

zoneid

list snapshots by zone id

Answer

No Answer

GET deleteSnapshot Async

Description

Deletes a snapshot

Request Parameters

Parameter Description Required
id

The ID of the snapshot

Answer

{
    "jobid": "<ID to use with queryAsyncJobResult>"
}

GET revertSnapshot Async

Description

Reverts a snapshot

Request Parameters

Parameter Description Required
id

The ID of the snapshot

Answer

{
    "jobid": "<ID to use with queryAsyncJobResult>"
}

Security Group

GET createSecurityGroup

Description

Creates a security group

Request Parameters

Parameter Description Required
name

name of the security group

description

the description of the security group

Answer

No Answer

GET deleteSecurityGroup

Description

Deletes security group

Request Parameters

Parameter Description Required
id

The ID of the security group. Mutually exclusive with name parameter

name

The ID of the security group. Mutually exclusive with id parameter

Answer

No Answer

GET authorizeSecurityGroupIngress Async

Description

Authorizes a particular ingress rule for this security group

Request Parameters

Parameter Description Required
cidrList

the cidr list associated

description

a description for this ingress rule

endport

end port for this ingress rule

icmpcode

error code for this icmp message

icmptype

type of the icmp message being sent

protocol

TCP is default. UDP is the other supported protocol

securitygroupid

The ID of the security group. Mutually exclusive with securitygroupname parameter

securitygroupname

The name of the security group. Mutually exclusive with securitygroupname parameter

startport

start port for this ingress rule

usersecuritygrouplist

user to security group mapping. Used when specifying another security group as the source or destination for the rule instead of a cidr.

Answer

{
    "jobid": "<ID to use with queryAsyncJobResult>"
}

GET revokeSecurityGroupIngress Async

Description

Deletes a particular ingress rule from this security group

Request Parameters

Parameter Description Required
id

The ID of the ingress rule

Answer

{
    "jobid": "<ID to use with queryAsyncJobResult>"
}

GET authorizeSecurityGroupEgress Async

Description

Authorizes a particular egress rule for this security group

Request Parameters

Parameter Description Required
cidrList

the cidr list associated

description

a description for this egress rule

endport

end port for this egress rule

icmpcode

error code for this icmp message

icmptype

type of the icmp message being sent

protocol

TCP is default. UDP is the other supported protocol

securitygroupid

The ID of the security group. Mutually exclusive with securitygroupname parameter

securitygroupname

The name of the security group. Mutually exclusive with securitygroupname parameter

startport

start port for this egress rule

usersecuritygrouplist

user to security group mapping. Used when specifying another security group as the source or destination for the rule instead of a cidr.

Answer

{
    "jobid": "<ID to use with queryAsyncJobResult>"
}

GET revokeSecurityGroupEgress Async

Description

Deletes a particular egress rule from this security group

Request Parameters

Parameter Description Required
id

The ID of the egress rule

Answer

{
    "jobid": "<ID to use with queryAsyncJobResult>"
}

GET listSecurityGroups

Description

Lists security groups

Request Parameters

Parameter Description Required
id

list the security group by the id provided

keyword

List by keyword

page
pagesize
securitygroupname

lists security groups by name

tags

List resources by tags (key/value pairs)

virtualmachineid

lists security groups by virtual machine id

Answer

{
    "count": 2,
    "securitygroup": [
        {
            "account": "demo@exoscale.ch",
            "egressrule": [],
            "id": "d19f67f7-71a4-492b-ba68-9f8f1b6235de",
            "ingressrule": [
                {
                    "account": "demo@exoscale.ch",
                    "endport": 443,
                    "protocol": "tcp",
                    "ruleid": "34b9a81d-5632-4215-af50-618f43840c8b",
                    "securitygroupname": "test",
                    "startport": 443,
                    "tags": []
                },
                {
                    "account": "demo@exoscale.ch",
                    "endport": 55,
                    "protocol": "tcp",
                    "ruleid": "fef0f703-7456-40c4-ac40-c7997917b46e",
                    "securitygroupname": "privnet",
                    "startport": 55,
                    "tags": []
                },
                {
                    "account": "demo@exoscale.ch",
                    "description": "asdsad",
                    "endport": 3309,
                    "protocol": "tcp",
                    "ruleid": "5568552a-b292-472b-8765-1cadf415b8f4",
                    "securitygroupname": "test",
                    "startport": 3309,
                    "tags": []
                },
                {
                    "account": "demo@exoscale.ch",
                    "endport": 11111,
                    "protocol": "tcp",
                    "ruleid": "7f71ef79-12c0-448c-9d30-8f1cfdf8efd7",
                    "securitygroupname": "default",
                    "startport": 11111,
                    "tags": []
                }
            ],
            "name": "test",
            "tags": []
        },
        {
            "account": "demo@exoscale.ch",
            "description": "Default Security Group",
            "egressrule": [],
            "id": "df66b167-a728-4dc5-bd69-f3962f5e72c4",
            "ingressrule": [
                {
                    "cidr": "0.0.0.0/0",
                    "endport": 22,
                    "protocol": "tcp",
                    "ruleid": "e87c0363-ce6c-4492-8369-800b588f1c19",
                    "startport": 22,
                    "tags": []
                },
                {
                    "cidr": "0.0.0.0/0",
                    "icmpcode": 0,
                    "icmptype": 8,
                    "protocol": "icmp",
                    "ruleid": "36b9c1b6-0b44-4bf5-a30f-b1b8caeda5a9",
                    "tags": []
                },
                {
                    "cidr": "0.0.0.0/0",
                    "endport": 3389,
                    "protocol": "tcp",
                    "ruleid": "3da0b4c0-59b7-40b9-8aa6-a8eea0520370",
                    "startport": 3389,
                    "tags": []
                }
            ],
            "name": "default",
            "tags": []
        }
    ]
}

Anti-Affinity Groups

GET createAntiAffinityGroup

Description

Creates an Anti-Affinity Group. Anti-Affinity Groups can be used to prevent virtual machines belonging to the same group to be co-located on the same hypervisors.

Request Parameters

Parameter Description Required
name

name of the Anti-Affinity Group

description

description of the Anti-Affinity Group

Answer

No Answer

GET listAntiAffinityGroups

Description

Lists Anti-Affinity Groups.

Request Parameters

Parameter Description Required
id

an unique identifier to restrict results to

name

a name to restrict results to

page
pagesize
virtualmachineid

an unique identifier of virtual machine to restrict results to

Answer

No Answer

GET deleteAntiAffinityGroup

Description

Deletes an Anti-Affinity Group.

Request Parameters

Parameter Description Required
id

unique identifier of the Anti-Affinity Group. Mutually exclusive with the “name” parameter.

name

name of the Anti-Affinity Group. Mutually exclusive with the “id” parameter.

Answer

No Answer

Offerings

GET listServiceOfferings

Description

Lists all available service offerings.

Request Parameters

Parameter Description Required
id

ID of the service offering

keyword

list by keyword

name

name of the service offering

page
pagesize
virtualmachineid

the ID of the virtual machine. Pass this in if you want to see the available service offering that a virtual machine can be changed to.

Answer

{
    "count": 11,
    "serviceoffering": [
        {
            "authorized": true,
            "cpunumber": 1,
            "cpuspeed": 2198,
            "created": "2013-02-08T17:20:17+0100",
            "defaultuse": false,
            "displaytext": "Micro 512mb 1cpu",
            "id": "71004023-bb72-4a97-b1e9-bc66dfce9470",
            "iscustomized": false,
            "issystem": false,
            "isvolatile": false,
            "limitcpuuse": false,
            "memory": 512,
            "name": "Micro",
            "offerha": false,
            "storagetype": "local"
        },
        {
            "authorized": true,
            "cpunumber": 1,
            "cpuspeed": 2198,
            "created": "2013-02-08T17:20:39+0100",
            "defaultuse": false,
            "displaytext": "Tiny 1024mb 1cpu",
            "id": "b6cd1ff5-3a2f-4e9d-a4d1-8988c1191fe8",
            "iscustomized": false,
            "issystem": false,
            "isvolatile": false,
            "limitcpuuse": false,
            "memory": 1024,
            "name": "Tiny",
            "offerha": false,
            "storagetype": "local"
        },
        {
            "authorized": true,
            "cpunumber": 2,
            "cpuspeed": 2198,
            "created": "2013-02-08T17:21:05+0100",
            "defaultuse": false,
            "displaytext": "Small 2048mb 2cpu",
            "id": "21624abb-764e-4def-81d7-9fc54b5957fb",
            "iscustomized": false,
            "issystem": false,
            "isvolatile": false,
            "limitcpuuse": false,
            "memory": 2048,
            "name": "Small",
            "offerha": false,
            "storagetype": "local"
        },
        {
            "authorized": true,
            "cpunumber": 2,
            "cpuspeed": 2198,
            "created": "2013-02-08T17:21:43+0100",
            "defaultuse": false,
            "displaytext": "Medium 4096mb 2cpu",
            "id": "b6e9d1e8-89fc-4db3-aaa4-9b4c5b1d0844",
            "iscustomized": false,
            "issystem": false,
            "isvolatile": false,
            "limitcpuuse": false,
            "memory": 4096,
            "name": "Medium",
            "offerha": false,
            "storagetype": "local"
        },
        {
            "authorized": true,
            "cpunumber": 4,
            "cpuspeed": 2198,
            "created": "2013-02-08T17:22:27+0100",
            "defaultuse": false,
            "displaytext": "Large 8192mb 4cpu",
            "id": "c6f99499-7f59-4138-9427-a09db13af2bc",
            "iscustomized": false,
            "issystem": false,
            "isvolatile": false,
            "limitcpuuse": false,
            "memory": 8192,
            "name": "Large",
            "offerha": false,
            "storagetype": "local"
        },
        {
            "authorized": true,
            "cpunumber": 4,
            "cpuspeed": 2198,
            "created": "2013-02-08T17:23:38+0100",
            "defaultuse": false,
            "displaytext": "Extra-large 16384mb 4cpu",
            "id": "350dc5ea-fe6d-42ba-b6c0-efb8b75617ad",
            "iscustomized": false,
            "issystem": false,
            "isvolatile": false,
            "limitcpuuse": false,
            "memory": 16384,
            "name": "Extra-large",
            "offerha": false,
            "storagetype": "local"
        },
        {
            "authorized": true,
            "cpunumber": 8,
            "cpuspeed": 2198,
            "created": "2013-02-08T17:24:10+0100",
            "defaultuse": false,
            "displaytext": "Huge 32768mb 8cpu",
            "id": "a216b0d1-370f-4e21-a0eb-3dfc6302b564",
            "iscustomized": false,
            "issystem": false,
            "isvolatile": false,
            "limitcpuuse": false,
            "memory": 32768,
            "name": "Huge",
            "offerha": false,
            "storagetype": "local"
        },
        {
            "authorized": false,
            "cpunumber": 12,
            "cpuspeed": 2198,
            "created": "2016-06-27T16:39:12+0200",
            "defaultuse": false,
            "displaytext": "Mega 64gb 12cpu",
            "id": "c0d3fb5d-6fdb-4a63-9361-3e5cfa8b36d0",
            "iscustomized": false,
            "issystem": false,
            "isvolatile": false,
            "limitcpuuse": false,
            "memory": 65536,
            "name": "Mega",
            "offerha": false,
            "storagetype": "local"
        },
        {
            "authorized": false,
            "cpunumber": 16,
            "cpuspeed": 2198,
            "created": "2016-06-27T16:40:31+0200",
            "defaultuse": false,
            "displaytext": "Titan 128gb 16cpu",
            "id": "74bfaf4e-7d67-4adf-9322-12b9a36e84f7",
            "iscustomized": false,
            "issystem": false,
            "isvolatile": false,
            "limitcpuuse": false,
            "memory": 131072,
            "name": "Titan",
            "offerha": false,
            "storagetype": "local"
        },
        {
            "authorized": true,
            "cpunumber": 12,
            "cpuspeed": 2198,
            "created": "2017-02-16T06:58:55+0100",
            "defaultuse": false,
            "displaytext": "GPU small 1gpu 60gb 12cpu",
            "hosttags": "GPU",
            "id": "07246b95-bbe4-498f-92a3-ce5be4d38342",
            "iscustomized": false,
            "issystem": false,
            "isvolatile": false,
            "limitcpuuse": false,
            "memory": 57344,
            "name": "GPU-small",
            "offerha": false,
            "serviceofferingdetails": {
                "pciCardinality": "1",
                "pciDevice": "15f8",
                "pciVendor": "10de"
            },
            "storagetype": "local"
        },
        {
            "authorized": true,
            "cpunumber": 48,
            "cpuspeed": 2198,
            "created": "2017-02-16T07:00:57+0100",
            "defaultuse": false,
            "displaytext": "GPU huge 4gpu 240gb 48cpu",
            "hosttags": "GPU",
            "id": "dee65287-12cf-4e36-b635-32dbc9a2e909",
            "iscustomized": false,
            "issystem": false,
            "isvolatile": false,
            "limitcpuuse": false,
            "memory": 230400,
            "name": "GPU-huge",
            "offerha": false,
            "serviceofferingdetails": {
                "pciCardinality": "4",
                "pciDevice": "15f8",
                "pciVendor": "10de"
            },
            "storagetype": "local"
        }
    ]
}

Template

GET registerCustomTemplate Async

Description

Register a new template

Request Parameters

Parameter Description Required
checksum

the MD5 checksum value of this template

displaytext

the description of the template

name

the name of the template

zoneid

the ID of the zone the template is to be registered on

url

the URL of where the template is hosted

passwordenabled

true if the template supports the password reset feature; default is false

sshkeyenabled

true if the template supports the sshkey upload feature; default is false

details

Template details in key/value pairs. The “username” key can be used to configure the default template user.

Answer

{
    "jobprocstatus": 0,
    "userid": "00de4ad4-90cc-11e9-8a51-bb318e2a9733",
    "jobresulttype": "object",
    "created": "2019-06-17T06:51:20Z",
    "jobid": "21410c30-90cc-11e9-b368-8109ee03169d",
    "jobresult": {
        "template": [
            {
                "displaytext": "My custom template",
                "format": "QCOW2",
                "hypervisor": "KVM",
                "isfeatured": false,
                "zoneid": "1128bd56-b4d9-4ac6-a7b9-c715b187ce11",
                "name": "Linux Debian Custom template test 64-bit",
                "isready": false,
                "created": "2019-06-17T06:51:20Z",
                "templatetype": "USER",
                "oscategoryname": "Other",
                "size": 10737418240,
                "oscategoryid": "981265e8-f395-4d8f-8b28-83f9870e5e91",
                "account": "00de4ad4-90cc-11e9-8a51-bb318e2a9733",
                "isextractable": true,
                "zonename": "ch-gva-2",
                "details": null,
                "checksum": "6cf902921d1257a93cbcf8b23596692e",
                "id": "c0b087fe-5c25-4fb9-82de-26048dcc96f7",
                "ispublic": false,
                "ostypeid": "8fec0e5f-345a-4681-b077-6792fd09cd22",
                "passwordenabled": false,
                "crosszones": true,
                "ostypename": "Other (64-bit)"
            }
        ]
    },
    "jobresultcode": 0,
    "jobstatus": 1,
    "cmd": "registerCustomTemplateCmd"
}

GET deleteTemplate Async

Description

Delete a template

Request Parameters

Parameter Description Required
id

the template ID

Answer

{
    "userid": "a454a25d-339a-4423-86a6-44501b4e5cdf",
    "cmd": "org.apache.cloudstack.api.command.user.template.DeleteTemplateCmd",
    "jobstatus": 1,
    "jobprocstatus": 0,
    "jobresultcode": 0,
    "jobresulttype": "object",
    "jobresult": {
        "success": true
    },
    "created": "2019-06-17T08:58:01+0200",
    "jobid": "b92f3f3d-445c-413f-acce-0981ee21e801"
}

GET listTemplates

Description

List all templates.

Request Parameters

Parameter Description Required
templatefilter

possible values are “self”, “featured”, “community”. * self : templates that have been registered or created by you. * featured : templates that are visible in the Exoscale portal. * community : templates that have been marked as public but not featured.

id

the template ID

name

the template name

page
pagesize
tags

List resources by tags (key/value pairs)

zoneid

list templates by zoneid

Answer

{
    "count": 1,
    "template": [
        {
            "bootmode": "legacy",
            "checksum": "6cf902921d1257a93cbcf8b23596692e",
            "created": "2019-03-27T10:40:22+0100",
            "crossZones": true,
            "details": {
                "username": "debian"
            },
            "directdownload": true,
            "displaytext": "Linux Debian 9 64-bit 2019-03-27-6cf902",
            "format": "QCOW2",
            "hypervisor": "KVM",
            "id": "1b7017d5-9472-43d4-820b-70dc4ca7966f",
            "isdynamicallyscalable": false,
            "isextractable": true,
            "isfeatured": true,
            "ispublic": true,
            "isready": true,
            "name": "Linux Debian 9 64-bit",
            "oscategoryid": "3953b323-46ec-4118-9407-83be25bc0a39",
            "oscategoryname": "Debian",
            "ostypeid": "874905df-d2f5-4415-8700-8cbc9abd6ae1",
            "ostypename": "Debian GNU/Linux 4(32-bit)",
            "passwordenabled": true,
            "size": 1418264736,
            "sshkeyenabled": false,
            "tags": [],
            "templatetype": "USER",
            "zoneid": "1747ef5e-5451-41fd-9f1a-58913bae9702",
            "zonename": "ch-gva-2"
        }
    ]
}

SSH Keypairs

GET createSSHKeyPair

Description

Create a new keypair and returns the private key

Request Parameters

Parameter Description Required
name

Name of the keypair

Answer

No Answer

GET deleteSSHKeyPair

Description

Deletes a keypair by name

Request Parameters

Parameter Description Required
name

Name of the keypair

Answer

No Answer

GET listSSHKeyPairs

Description

List registered keypairs

Request Parameters

Parameter Description Required
fingerprint

A public key fingerprint to look for

keyword

List by keyword

name

A key pair name to look for

page
pagesize

Answer

No Answer

GET registerSSHKeyPair

Description

Register a public key in a keypair under a certain name

Request Parameters

Parameter Description Required
name

Name of the keypair

publicKey

Public key material of the keypair

Answer

No Answer

IP Addresses

GET associateIpAddress Async

Description

Acquires and associates a public IP to an account. An optional healthcheck for the IP can also be configured.

Request Parameters

Parameter Description Required
interval

probing interval in seconds, must be at least 5 (default: 10)

mode

probing mode, must be either "tcp" or "http"

path

probe HTTP request path, must be specified in "http" mode

port

service port to probe, must be between 1 and 65535

strikes-fail

number of unsuccessful probes before considering the target unhealthy (default: 3)

strikes-ok

number of successful probes before considering the target healthy (default: 2)

timeout

time in seconds before considering a probing failed, must be lower than interval (default: 2)

zoneid

the ID of the availability zone for which you want to acquire a public IP address from

Answer

{
    "jobid": "<ID to use with queryAsyncJobResult>"
}

GET updateIpAddress Async

Description

Updates an IP address.

Request Parameters

Parameter Description Required
id

the id of the public IP address to update

interval

probing interval in seconds, must be at least 5 (default: 10)

mode

probing mode, must be either "tcp" or "http"

path

probe HTTP request path, must be specified in "http" mode

port

service port to probe, must be between 1 and 65535

strikes-fail

number of unsuccessful probes before considering the target unhealthy (default: 3)

strikes-ok

number of successful probes before considering the target healthy (default: 2)

timeout

time in seconds before considering a probing failed, must be lower than interval (default: 2)

Answer

{
    "jobid": "<ID to use with queryAsyncJobResult>"
}

GET disassociateIpAddress Async

Description

Disassociates an IP address.

Request Parameters

Parameter Description Required
id

the id of the public ip address to disassociate

Answer

{
    "jobid": "<ID to use with queryAsyncJobResult>"
}

GET listPublicIpAddresses

Description

Lists all public ip addresses

Request Parameters

Parameter Description Required
allocatedonly

limits search results to allocated public IP addresses

id

lists ip address by id

ipaddress

lists the specified IP address

iselastic

list only elastic IP

page
pagesize
zoneid

lists all public IP addresses by Zone ID

Answer

No Answer

NIC

GET activateIp6 Async

Description

Activate the IP6 address on a virtual machine

Request Parameters

Parameter Description Required
nicid

the ID of the nic to which you want to activate the IPv6

Answer

{
    "nic":
    {
        "deviceid": "0",
        "gateway": "159.100.241.1",
        "id": "2f3d9311-79a4-4fb3-9755-d46b81befc9b",
        "ip6address": "2a04:c46:c00:68f:402:4ff:fe00:33",
        "ip6cidr": "2a04:c46:c00:68f:402:4ff:fe00:33/64",
        "ipaddress": "159.100.241.239",
        "isdefault": true,
        "macaddress": "06:ea:32:00:00:86",
        "netmask": "255.255.255.0",
        "networkid": "bd666a36-fe9d-4f2d-ab6f-088aedd204bd",
        "virtualmachineid": "33d5700b-f778-4bdc-af6d-8cbeb4f3a3de"
    }
}

GET addIpToNic Async

Description

Assigns secondary IP to NIC

Request Parameters

Parameter Description Required
nicid

the ID of the nic to which you want to assign private IP

ipaddress

Secondary IP Address

Answer

{
    "jobid": "<ID to use with queryAsyncJobResult>"
}

GET removeIpFromNic Async

Description

Removes secondary IP from the NIC.

Request Parameters

Parameter Description Required
id

the ID of the secondary ip address to nic

Answer

{
    "jobid": "<ID to use with queryAsyncJobResult>"
}

GET listNics

Description

list the vm nics IP to NIC

Request Parameters

Parameter Description Required
virtualmachineid

the ID of the vm

page
pagesize

Answer

{
    "count": 2,
    "nic": [
        {
            "deviceid": "0",
            "gateway": "159.100.241.1",
            "id": "2f3d9311-79a4-4fb3-9755-d46b81befc9b",
            "ipaddress": "159.100.241.239",
            "isdefault": true,
            "macaddress": "06:ea:32:00:00:86",
            "netmask": "255.255.255.0",
            "networkid": "bd666a36-fe9d-4f2d-ab6f-088aedd204bd",
            "secondaryip": [
                {
                    "id": "05836edf-6954-4faa-ae1b-85585e2478c8",
                    "ipaddress": "159.100.241.252"
                }
            ],
            "virtualmachineid": "33d5700b-f778-4bdc-af6d-8cbeb4f3a3de"
        },
        {
            "deviceid": "1",
            "id": "73e68307-2b67-4499-ad84-8b130e7601b8",
            "isdefault": false,
            "macaddress": "0a:08:44:00:00:de",
            "networkid": "82637916-ac56-43e5-8f75-5303037c548e",
            "virtualmachineid": "33d5700b-f778-4bdc-af6d-8cbeb4f3a3de"
        }
    ]
}

Tags

GET createTags Async

Description

Creates resource tag(s)

Request Parameters

Parameter Description Required
resourceids

list of resources to create the tags for

resourcetype

type of the resource

tags

Map of tags (key/value pairs)

customer

identifies client specific tag. When the value is not null, the tag can’t be used by cloudStack code internally

Answer

{
    "jobid": "<ID to use with queryAsyncJobResult>"
}

GET deleteTags Async

Description

Deleting resource tag(s)

Request Parameters

Parameter Description Required
resourceids

Delete tags for resource id(s)

resourcetype

Delete tag by resource type

tags

Delete tags matching key/value pairs

Answer

{
    "jobid": "<ID to use with queryAsyncJobResult>"
}

GET listTags

Description

List resource tag(s)

Request Parameters

Parameter Description Required
customer

list by customer name

key

list by key

keyword

List by keyword

page
pagesize
resourceid

list by resource id

resourcetype

list by resource type

value

list by value

Answer

No Answer

Account

GET listAccounts

Description

Lists accounts and provides detailed account information for listed accounts

Request Parameters

Parameter Description Required
accountType

list accounts by account type. Valid account types are 1 (admin), and 0 (user).

id

list account by account ID

keyword

List by keyword

name

list account by account name

page
pagesize
state

list accounts by state. Valid states are enabled, disabled, and locked.

Answer

{
    "account": [
        {
            "accounttype": 0,
            "cpuavailable": "Unlimited",
            "cpulimit": "Unlimited",
            "cputotal": 8,
            "eiplimit": "Unlimited",
            "groups": [],
            "id": "1871a41a-f770-4414-9c54-8d6009fb0929",
            "ipavailable": "0",
            "iplimit": "Unlimited",
            "iptotal": -119,
            "isdefault": false,
            "memoryavailable": "Unlimited",
            "memorylimit": "Unlimited",
            "memorytotal": 24576,
            "name": "your-account-name",
            "networkavailable": "Unlimited",
            "networklimit": "Unlimited",
            "networktotal": 3,
            "primarystorageavailable": "Unlimited",
            "primarystoragelimit": "Unlimited",
            "primarystoragetotal": 210,
            "secondarystorageavailable": "Unlimited",
            "secondarystoragelimit": "Unlimited",
            "secondarystoragetotal": -147,
            "snapshotavailable": "30",
            "snapshotlimit": "30",
            "snapshottotal": 0,
            "state": "enabled",
            "templateavailable": "10",
            "templatelimit": "10",
            "templatetotal": 0,
            "user": [
                {
                    "account": "your-account-name",
                    "accountid": "1871a41a-f770-4414-9c54-8d6009fb0929",
                    "accounttype": 0,
                    "created": "2016-03-16T10:46:26+0100",
                    "email": "your-account-name",
                    "firstname": "your-account-name",
                    "id": "7fbd8385-bdde-4d1a-a50d-2fed57f12136",
                    "isdefault": false,
                    "lastname": "your-account-name",
                    "state": "enabled",
                    "username": "your-account-name"
                }
            ],
            "vmavailable": "197",
            "vmlimit": "200",
            "vmrunning": 2,
            "vmstopped": 3,
            "vmtotal": 3,
            "volumeavailable": "Unlimited",
            "volumelimit": "Unlimited",
            "volumetotal": 124,
            "vpcavailable": "0",
            "vpclimit": "Unlimited",
            "vpctotal": 0
        }
    ],
    "count": 1
}

Network

GET createNetwork

Description

Create a network based on a network offering.

Request Parameters

Parameter Description Required
displaytext

the display text of the network

endip

the ending IP address in the network IP range. Required for managed networks.

name

the name of the network

netmask

the netmask of the network. Required for managed networks.

startip

the beginning IP address in the network IP range. Required for managed networks.

zoneid

the Zone ID for the network

Answer

{
    "network":
    {
        "account": "demo@exoscale.ch",
        "acltype": "Account",
        "broadcastdomaintype": "Vxlan",
        "canusefordeploy": true,
        "displaytext": "Private Network CH-DK2 #2",
        "endip": "10.0.0.200",
        "id": "144047bd-6749-49ce-8af6-b12e87d76ec9",
        "ispersistent": true,
        "issystem": false,
        "name": "privnet-dk2-2",
        "netmask": "255.255.255.0",
        "networkofferingavailability": "Optional",
        "networkofferingconservemode": true,
        "networkofferingdisplaytext": "Private Network",
        "networkofferingid": "2aa963bc-252b-4e97-a485-47dcf0fe05b1",
        "networkofferingname": "PrivNet",
        "physicalnetworkid": "ecff7e96-d4f6-4af4-ac0f-dfaf95b39e0d",
        "related": "144047bd-6749-49ce-8af6-b12e87d76ec9",
        "restartrequired": false,
        "service": [
            {
                "name": "PrivateNetwork"
            }
        ],
        "specifyipranges": false,
        "startip": "10.0.0.1",
        "state": "Implemented",
        "strechedl2subnet": false,
        "tags": [],
        "traffictype": "Guest",
        "type": "Isolated",
        "zoneid": "381d0a95-ed4a-4ad9-b41c-b97073c1a433",
        "zonename": "ch-dk-2"
    }
}

GET deleteNetwork Async

Description

Delete a network

Request Parameters

Parameter Description Required
id

the ID of the network

Answer

{
    "success": true
}

GET listNetworks

Description

Lists all available networks

Request Parameters

Parameter Description Required
canusefordeploy

list networks available for vm deployment

id

list networks by id

type

the type of the network. Supported values are: Isolated and Shared

zoneid

the Zone ID of the network

page
pagesize

Answer

{
    "count": 2,
    "network": [
        {
            "account": "demo@exoscale.ch",
            "acltype": "Account",
            "broadcastdomaintype": "Vxlan",
            "canusefordeploy": true,
            "displaytext": "privNetForBasicZone",
            "id": "144047bd-6749-49ce-8af6-b12e87d76ec9",
            "ispersistent": true,
            "issystem": false,
            "name": "privNetForBasicZone",
            "networkofferingavailability": "Optional",
            "networkofferingconservemode": true,
            "networkofferingdisplaytext": "Private Network",
            "networkofferingid": "2aa963bc-252b-4e97-a485-47dcf0fe05b1",
            "networkofferingname": "PrivNet",
            "physicalnetworkid": "ecff7e96-d4f6-4af4-ac0f-dfaf95b39e0d",
            "related": "144047bd-6749-49ce-8af6-b12e87d76ec9",
            "restartrequired": false,
            "service": [
                {
                    "name": "PrivateNetwork"
                }
            ],
            "specifyipranges": false,
            "state": "Implemented",
            "strechedl2subnet": false,
            "tags": [],
            "traffictype": "Guest",
            "type": "Isolated",
            "zoneid": "381d0a95-ed4a-4ad9-b41c-b97073c1a433",
            "zonename": "ch-dk-2"
        }
    ]
}

GET updateNetwork Async

Description

Update a network

Request Parameters

Parameter Description Required
id

the ID of the network

displaytext

the new display text for the network

endip

the ending IP address in the network IP range. Required for managed networks.

name

the new name for the network.

netmask

the netmask of the network. Required for managed networks.

startip

the beginning IP address in the network IP range. Required for managed networks.

Answer

{
    "network":
    {
        "account": "demo@exoscale.ch",
        "acltype": "Account",
        "broadcastdomaintype": "Vxlan",
        "canusefordeploy": true,
        "displaytext": "Private Network for LB - DK2",
        "endip": "10.0.0.200",
        "id": "144047bd-6749-49ce-8af6-b12e87d76ec9",
        "ispersistent": true,
        "issystem": false,
        "name": "privnet.lb.ch-dk-2",
        "netmask": "255.255.255.0",
        "networkofferingavailability": "Optional",
        "networkofferingconservemode": true,
        "networkofferingdisplaytext": "Private Network",
        "networkofferingid": "2aa963bc-252b-4e97-a485-47dcf0fe05b1",
        "networkofferingname": "PrivNet",
        "physicalnetworkid": "ecff7e96-d4f6-4af4-ac0f-dfaf95b39e0d",
        "related": "144047bd-6749-49ce-8af6-b12e87d76ec9",
        "restartrequired": false,
        "service": [
            {
                "name": "PrivateNetwork"
            }
        ],
        "specifyipranges": false,
        "startip": "10.0.0.1",
        "state": "Implemented",
        "strechedl2subnet": false,
        "tags": [],
        "traffictype": "Guest",
        "type": "Isolated",
        "zoneid": "381d0a95-ed4a-4ad9-b41c-b97073c1a433",
        "zonename": "ch-dk-2"
    }
}

Events

GET listEvents

Description

A command to list events.

Request Parameters

Parameter Description Required
duration

the duration of the event

endDate

the end date range of the list you want to retrieve (use format “yyyy-MM-dd” or the new format “yyyy-MM-dd HH:mm:ss”)

entryTime

the time the event was entered

id

the ID of the event

keyword

List by keyword

level

the event level (INFO, WARN, ERROR)

page
pagesize
startdate

the start date range of the list you want to retrieve (use format “yyyy-MM-dd” or the new format “yyyy-MM-dd HH:mm:ss”)

type

the event type (see event types)

Answer

No Answer

GET listEventTypes

Description

List Event Types

Request Parameters

No Request Parameters

Answer

No Answer

Jobs

GET queryAsyncJobResult

Description

Retrieves the current status of asynchronous job.

Request Parameters

Parameter Description Required
jobid

the ID of the asychronous job

Answer

No Answer

GET listAsyncJobs

Description

Lists all pending asynchronous jobs for the account.

Request Parameters

Parameter Description Required
keyword

List by keyword

page
pagesize
startdate

the start date of the async job

Answer

No Answer

Reverse DNS

GET queryReverseDnsForVirtualMachine

Description

Query the PTR DNS record(s) for the virtual machine

Request Parameters

Parameter Description Required
id

the ID of the virtual machine

Answer

{"virtualmachine": {
    "id": "...",
    "nic": [{
        "isdefault": true,
        "reversedns": [
            {
                "ipaddress": "185.150.8.3",
                "domainname": "example.exo"
            },
            {
                "ip6address": "2a04:c45:c00:68f:417:50ff:fe00:46",
                "domainname": "example.exo"
            }
        ]
    }]
}}

GET updateReverseDnsForVirtualMachine

Description

Update/create the PTR DNS record(s) for the virtual machine

Request Parameters

Parameter Description Required
id

the ID of the virtual machine

domainname

the domain name for the PTR record(s). It must have a valid TLD

Answer

No Answer

GET deleteReverseDnsFromVirtualMachine

Description

Delete the PTR DNS record(s) from the public IP address

Request Parameters

Parameter Description Required
id

the ID of the public IP address

Answer

{"success": true}

GET queryReverseDnsForPublicIpAddress

Description

Query the PTR DNS record for the public IP address

Request Parameters

Parameter Description Required
id

the ID of the public IP address

Answer

{"ipaddress": {
    "id": "...",
    "reversedns": [
        {
            "ipaddress": "185.150.8.3",
            "domainname": "example.exo"
        },
        {
            "ip6address": "2a04:c45:c00:68f:417:50ff:fe00:46",
            "domainname": "example.exo"
        }
    ]
}}

GET updateReverseDnsForPublicIpAddress

Description

Update/create the PTR DNS record for the public IP address

Request Parameters

Parameter Description Required
id

the ID of the public IP address

domainname

the domain name for the PTR record. It must have a valid TLD

Answer

No Answer

GET deleteReverseDnsFromPublicIpAddress

Description

Delete the PTR DNS record from the public IP address

Request Parameters

Parameter Description Required
id

the ID of the public IP address

Answer

{"success": true}

Cloud

GET listZones

Description

Lists zones

Request Parameters

Parameter Description Required
available

true if you want to retrieve all available Zones. False if you only want to return the Zones from which you have at least one VM. Default is false.

id

the ID of the zone

keyword

List by keyword

name

the name of the zone

networkType

the network type of the zone that the virtual machine belongs to

page
pagesize
showCapacities

flag to display the capacity of the zones

Answer

No Answer

DNS

GET createDnsDomain

Description

Create a domain

Request Parameters

Parameter Description Required
name

the name of the DNS domain.

Answer

{
  "dnsdomain": {
    "account": "account@email.com",
    "account_id": 9999,
    "accountid": "f5f42ecd-e38b-4211-937d-4fe2d40d3354",
    "autorenew": false,
    "created": "2019-08-16T10:03:50Z",
    "expires": null,
    "id": 119999,
    "name": "my-domain.com",
    "private_whois": false,
    "registrant_id": null,
    "state": "hosted",
    "token": "abf496dd48534ea4bc10c1a4f8c781d5",
    "unicodename": "my-domain.com",
    "updated": "2019-08-16T10:03:50Z"
  }
}

GET listDnsDomains

Description

List domains

Request Parameters

No Request Parameters

Answer

{
  "count": 1,
  "dnsdomain": [
    {
      "dnsdomain": {
        "account": "account@email.com",
        "account_id": 9999,
        "accountid": "f5f42ecd-e38b-4211-937d-4fe2d40d3354",
        "autorenew": false,
        "created": "2019-08-16T10:03:50Z",
        "expires": null,
        "id": 119999,
        "name": "my-domain.com",
        "private_whois": false,
        "registrant_id": null,
        "state": "hosted",
        "token": "abf496dd48534ea4bc10c1a4f8c781d5",
        "unicodename": "my-domain.com",
        "updated": "2019-08-16T10:03:50Z"
      }
    }
  ]
}

GET deleteDnsDomain

Description

Delete a domain, id or name must be provided

Request Parameters

Parameter Description Required
name

the name of the DNS domain.

id

the id of the DNS domain.

Answer

{
  "success": true
}

GET resetDnsDomainToken

Description

Reset the token of a DNS domain, id or name must be provided

Request Parameters

Parameter Description Required
name

the name of the DNS domain.

id

the id of the DNS domain.

Answer

{
  "dnsdomain": {
    "account": "account@email.com",
    "account_id": 9999,
    "accountid": "f5f42ecd-e38b-4211-937d-4fe2d40d3354",
    "autorenew": false,
    "created": "2019-08-16T10:03:50Z",
    "expires": null,
    "id": 119999,
    "name": "my-domain.com",
    "private_whois": false,
    "registrant_id": null,
    "state": "hosted",
    "token": "abf496dd48534ea4bc10c1a4f8c781d5",
    "unicodename": "my-domain.com",
    "updated": "2019-08-16T10:03:50Z"
  }
}

GET getDnsDomainZoneFile

Description

Get the DNS zone file for a domain, id or name must be provided

Request Parameters

Parameter Description Required
name

the name of the DNS domain.

id

the id of the DNS domain.

Answer

{
  "domain": {
    "account": "account@email.com",
    "accountid": "f5f42ecd-e38b-4211-937d-4fe2d40d3354",
    "id": 119999,
    "name": "my-domain.com",
    "zonefile": "$ORIGIN my-domain.com.\n$TTL 1h\nmy-domain.com. 3600 IN SOA ns1.exoscale.ch. admin.dnsimple.com. 1565949831 86400 7200 604800 300\nmy-domain.com. 3600 IN NS ns1.exoscale.ch.\nmy-domain.com. 3600 IN NS ns1.exoscale.com.\nmy-domain.com. 3600 IN NS ns1.exoscale.io.\nmy-domain.com. 3600 IN NS ns1.exoscale.net.\n"
  }
}

GET listDnsDomainRecords

Description

List domain records for a domain, id or name must be provided

Request Parameters

Parameter Description Required
name

the name of the DNS domain.

id

the id of the DNS domain.

Answer

{
  "count": 2,
  "records": [
    {
      "content": "ns1.exoscale.ch admin.dnsimple.com 1565949831 86400 7200 604800 300",
      "created_at": "2019-08-16T10:03:50Z",
      "domain_id": 118215,
      "id": 1123993,
      "name": "",
      "priority": null,
      "record_type": "SOA",
      "ttl": 3600,
      "updated_at": "2019-08-16T10:03:51Z"
    },
    {
      "content": "ns1.exoscale.ch",
      "created_at": "2019-08-16T10:03:51Z",
      "domain_id": 118215,
      "id": 1123994,
      "name": "",
      "priority": null,
      "record_type": "NS",
      "ttl": 3600,
      "updated_at": "2019-08-16T10:03:51Z"
    }
  ]
}

GET createDnsDomainRecord

Description

Create a domain record, id or name must be provided

Request Parameters

Parameter Description Required
name

the name of the DNS domain.

id

the id of the DNS domain.

record_name

the name of the record.

record_type

the type of record (A, AAAA, ALIAS, CAA, CNAME, HINFO, MX, NAPTR, NS, POOL, PTR, SPF, SRV, SSHFP, TXT, URL)

content

the record content

ttl

time to live (TTL), the number of seconds the record can be cached

priority

the record priority, the lower number is the higher priority

Answer

{
  "content": "0.0.0.0",
  "created_at": "2019-08-16T10:27:54Z",
  "domain_id": 119999,
  "id": 199999,
  "name": "test",
  "priority": null,
  "record_type": "A",
  "ttl": 300,
  "updated_at": "2019-08-16T10:27:54Z"
}

GET getDnsDomainRecord

Description

Get a domain record, domain id or name must be provided with the record_id

Request Parameters

Parameter Description Required
name

the name of the DNS domain.

id

the id of the DNS domain.

record_id

the id of the record.

Answer

{
  "content": "0.0.0.0",
  "created_at": "2019-08-16T10:27:54Z",
  "domain_id": 119999,
  "id": 199999,
  "name": "test",
  "priority": null,
  "record_type": "A",
  "ttl": 300,
  "updated_at": "2019-08-16T10:27:54Z"
}

GET deleteDnsDomainRecord

Description

Delete a domain record, domain id or name must be provided with the record_id

Request Parameters

Parameter Description Required
name

the name of the DNS domain.

id

the id of the DNS domain.

record_id

the id of the record.

Answer

{
  "success": true
}

GET updateDnsDomainRecord

Description

Create a domain record, domain id or name must be provided with the record_id

Request Parameters

Parameter Description Required
name

the name of the DNS domain.

id

the id of the DNS domain.

record_id

the id of the record.

record_name

the name of the record.

record_type

the type of record (A, AAAA, ALIAS, CAA, CNAME, HINFO, MX, NAPTR, NS, POOL, PTR, SPF, SRV, SSHFP, TXT, URL)

content

the record content

ttl

time to live (TTL), the number of seconds the record can be cached

priority

the record priority, the lower number is the higher priority

Answer

{
  "content": "0.0.0.0",
  "created_at": "2019-08-16T10:27:54Z",
  "domain_id": 119999,
  "id": 199999,
  "name": "test",
  "priority": null,
  "record_type": "A",
  "ttl": 300,
  "updated_at": "2019-08-16T10:27:54Z"
}

IAM

GET createApiKey

Description

Create a new API key for the current organization.

Request Parameters

Parameter Description Required
name

the name of the key

operations

comma-separated list of operations available for the key

Answer

{
  "apikey": {
    "key": "EXO1235b51e0a0d2988dd4f182d",
    "name": "test",
    "operations": [
      "compute/*",
      "iam/*"
    ],
    "secret": "7oEJI0vd0PAXg8MNgcELStczPdBc30WO_KSBjKmbe-o",
    "type": "restricted"
  }
}

GET revokeApiKey

Description

Revoke an existing API key.

Request Parameters

Parameter Description Required
key

the access key to be revoked

Answer

{
  "success": true
}

GET listApiKeys

Description

List of API keys.

Request Parameters

No Request Parameters

Answer

{
  "apikey": [
    {
      "key": "EXO3063f2f9741381aef12100cc",
      "name": "test1",
      "type": "unrestricted"
    },
    {
      "key": "EXO0f3596b7b3132ca82c7ba4c9",
      "name": "test2",
      "operations": [
        "compute/*",
        "iam/*"
      ],
      "type": "restricted"
    }
  ],
  "count": 2
}

GET listApiKeyOperations

Description

List of operations allowed for the current API key.

Request Parameters

No Request Parameters

Answer

{
  "operations": [
    "compute/*",
    "compute/activateIp6",
    "compute/addIpToNic",
    "compute/addNicToVirtualMachine",
    "compute/associateIpAddress",
    "dns/createDnsDomain",
    "dns/resetDnsDomainToken",
    "dns/updateDnsDomainRecord",
    "iam/*",
    "iam/createApiKey",
    "iam/listApiKeyOperations",
    "iam/listApiKeys",
    "iam/revokeApiKey",
    "sos/*"
  ]
}

Instance Pools

GET createInstancePool

Description

Create an Instance Pool.

Request Parameters

Parameter Description Required
name

the name of the Instance Pool

serviceofferingid

the size of the managed instances, e.g. Tiny, Small, Medium, Large etc

templateid

the ID of the template to use when creating managed instances

size

the number of instances to be managed by the Instance Pool

zoneid

the zone ID to deploy the instance pool into

description

the description of the Instance Pool

securitygroupids

a list of Security Group IDs to apply to managed instances

networkids

a list of Private Network IDs to attach managed instances to

keypair

the name of the SSH key to install when creating instances

userdata

a cloud-init user data configuration (base64-encoded) to apply when creating managed instances

rootdisksize

the disk size of the managed instances

Answer

{
    "description": "my instance pool",
    "id": "9ffe22db-7faf-53da-88b8-eed13e521ecd",
    "name": "my-instance-pool",
    "rootdisksize": 10,
    "serviceofferingid": "5e5fb3c6-e076-429d-9b6c-b71f7b27760b",
    "size": 3,
    "state": "creating",
    "templateid": "7cd26036-7c26-4083-878f-b5386ef83f2e",
    "zoneid": "de88c980-78f6-467c-a431-71bcc88e437f"
}

GET updateInstancePool

Description

Update an Instance Pool’s properties.

Request Parameters

Parameter Description Required
id

the ID of the Instance Pool to update

zoneid

the ID of the zone where the Instance Pool is located in

name

update the Instance Pool name

description

update the Instance Pool description

templateid

update the ID of the template to use when creating managed instances

userdata

update the Instance Pool cloud-init

rootdisksize

the disk size of the managed instances

Answer

{
    "success": true
}

GET scaleInstancePool

Description

Scale an Instance Pool.

Request Parameters

Parameter Description Required
id

the Instance Pool ID to scale

zoneid

the zone ID where the Instance Pool is

size

the new number of instances to be managed by the Instance Pool

Answer

{
    "success": true
}

GET destroyInstancePool

Description

Destroy an Instance Pool.

Request Parameters

Parameter Description Required
id

the Instance Pool ID to destroy

zoneid

the ID of the zone where the Instance Pool is located in

Answer

{
    "success": true
}

GET getInstancePool

Description

Get an Instance Pool’s properties.

Request Parameters

Parameter Description Required
id

the Instance Pool ID to get

zoneid

the ID of the zone where the Instance Pool is located in

Answer

{
    "count": 1,
    "instancepool": [
      {
        "description": "my instance pool",
        "id": "9ffe22db-7faf-53da-88b8-eed13e521ecd",
        "name": "my-instance-pool",
        "rootdisksize": 10,
        "serviceofferingid": "5e5fb3c6-e076-429d-9b6c-b71f7b27760b",
        "size": 3,
        "state": "running",
        "templateid": "7cd26036-7c26-4083-878f-b5386ef83f2e",
        "virtualmachines": [
           ... 
        ],
        "zoneid": "de88c980-78f6-467c-a431-71bcc88e437f"
      }
    ]
}

GET listInstancePools

Description

List Instance Pools.

Request Parameters

Parameter Description Required
zoneid

the ID of the zone to list Instance Pools into

Answer

{
    "count": 1,
    "instancepool": [
      {
        "description": "my instance pool",
        "id": "9ffe22db-7faf-53da-88b8-eed13e521ecd",
        "name": "my-instance-pool",
        "rootdisksize": 10,
        "serviceofferingid": "5e5fb3c6-e076-429d-9b6c-b71f7b27760b",
        "size": 3,
        "state": "running",
        "templateid": "7cd26036-7c26-4083-878f-b5386ef83f2e",
        "virtualmachines": [
           ... 
        ],
        "zoneid": "de88c980-78f6-467c-a431-71bcc88e437f"
      }
    ]
}