Compute API
The Open Cloud Compute API is based on Apache CloudStack API.
Note
The Compute API V1 described here is deprecated, refer to the OpenAPI documentation for the Compute API V2.
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.com/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:
- https://api.exoscale.com/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
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.com/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 .
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 |
|
ip6 | an optional boolean attribute to request an IPv6 for the machine on the default nic. Currently defaults to |
|
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 |
|
|
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, it cannot be recovered.
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 |
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 virtual machines by tags (key/value pairs). Note: multiple tags are OR’ed, not AND’ed. |
|
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 volumes by tags (key/value pairs). Note: multiple tags are OR’ed, not AND’ed. |
|
type | the type of disk volume |
|
virtualmachineid | the ID of the virtual machine |
|
zoneid | the ID of the availability zone |
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 snapshots by tags (key/value pairs). Note: multiple tags are OR’ed, not AND’ed. |
|
volumeid | the ID of the disk volume |
|
zoneid | list snapshots by zone id |
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
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
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 | list security groups by name |
|
tags | list security groups by tags (key/value pairs). Note: multiple tags are OR’ed, not AND’ed. |
|
virtualmachineid | list 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
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
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
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 using format details[i].keyname=keyvalue. The “username” key can be used to configure the default template user. Example: |
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 templates by tags (key/value pairs). Note: multiple tags are OR’ed, not AND’ed. |
|
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
GET deleteSSHKeyPair
Description
Deletes a keypair by name
Request Parameters
Parameter | Description | Required |
---|---|---|
name | Name of the keypair |
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
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
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
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
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" } }
Jobs
GET queryAsyncJobResult
Description
Retrieves the current status of asynchronous job.
Request Parameters
Parameter | Description | Required |
---|---|---|
jobid | the ID of the asychronous job |
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
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
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
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
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
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 |
|
resources | comma-separated list of resources available for the key Only bucket supported (sos/bucket:my-bucket-name) |
Answer
{ "apikey": { "key": "EXO1235b51e0a0d2988dd4f182d", "name": "test", "operations": [ "compute/*", "iam/*", "sos/listBucket", "sos/getObject" ], "resources": [ "sos/bucket:some-bucket" ], "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 getApiKey
Description
Retrieve an API key information.
Request Parameters
Parameter | Description | Required |
---|---|---|
key | the access key to be retrieved |
Answer
GET listApiKeys
Description
List of API keys.
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
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/*", "sos/abortMultipartUpload", "sos/createBucket", "sos/deleteBucket" ] }
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. |
|
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 |
|
affinitygroupids | a list of Anti-affinity 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, "ipv6": false, "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. An anti-affinity group is limited to 8 members, so the maximum pool size can be constrained by other instances in the attached groups. |
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, "ipv6": false, "state": "running", "templateid": "7cd26036-7c26-4083-878f-b5386ef83f2e", "virtualmachines": [ ... ], "zoneid": "de88c980-78f6-467c-a431-71bcc88e437f" } ] }
SOS
GET listBucketsUsage
Description
Lists buckets and provides a usage estimate (in bytes, updated once a day) for listed buckets.