Introduction
Welcome to the Tilaa API reference
This public API can be used to automate the management of Tilaa virtual machines (VPS). A list of available RESTful API calls is listed below. We use standard HTTP response codes where applicable and responses are always encoded in JSON format. Each response message always includes the status attribute to indicate success (OK) or failure (ERROR) and optionally a message attribute to give further information about the result of your request. Input validation errors for POST queries are returned in an additional errors array (parameter as key, error message as value). Each API call is versioned, so that future changes will not break existing client implementations.
Authentication
All endpoints require Basic Authentication. For security reasons you cannot use your main Tilaa user account to access this API. Instead, you should add an API user to your customer account and use the specified login credentials to authenticate. This will require a unique and validated email address, which we will also use to notify you about important API related announcements, such as deprecation notifications, new features and maintenance windows. Always use HTTPS when calling the API to prevent eavesdropping and only store your API credentials in a private and secure location.
Billing and invoicing
All Tilaa services are pre-paid services. To be able to order new services through the API you will need to have sufficient funds on your account. Account credit can easily be added to your account by making a payment through the Tilaa dashboard. The Tilaa dashboard also allows you to make changes to other billing settings, such as your billing period (1 month by default). Billing and invoicing occurs each day at 0:00AM (Europe/Amsterdam timezone), during which the account credit is used to fulfill the invoice.
General usage
Getting familiar with and testing the API is easy using the curl command, as available by default on Linux and OS/X platforms. We recommend installing the excellent jq tool (available in Homebrew on OS/X) for reading, querying and filtering the JSON output of the Tilaa API. For example, the following query will list all IP's of all your virtual machines in a single command: curl -su email:password https://api.tilaa.com/v1/virtual_machines | jq .virtual_machines[].network[].address. All GET endpoints can of course be queried with your internet browser as well. (POST queries are more difficult to simulate using your internet browser and will require browser extensions.)
Community and support
If you've made a client implementation for your favourite language, please consider sharing it with the Tilaa community at large by putting it on a public repository (such as the excellent GitHub). If you'd like some assistance while implementing this API or would just like to give us some general feedback, please get in touch!
Endpoints
List users
This method returns a list of all the users under your account.
Usage
GET /v1/users
Example
curl -su email:password https://api.tilaa.com/v1/users{ "status": "OK", "users": [ { "id": 42, "email": "myuser@domain.com", "first_name": "John", "last_name": "Doe" } ] }
List virtual machines
Usage
GET /v1/virtual_machines
Example
curl -su email:password https://api.tilaa.com/v1/virtual_machines{ "status": "OK", "virtual_machines": [ { "id": 42, "name": "myserver", "cpu": { "count": 2, "cap": 80 }, "ram": 2048, "storage": { "size": 20, "type": "hdd" }, "site": { "id": 4, "name": "Haarlem, NL, CO2 Neutral" }, "template": { "id": 255, "name": "Scientific Linux 6.2, 64 bit" }, "network": [ { "id": 323, "family": 4, "address": "127.0.0.1", "dns_name": "myserver.tilaa.cloud" }, { "id": 324, "family": 6, "address": "fe80::1", "dns_name": "myserver.tilaa.cloud" } ], "admin": { "account": "root", "initial_password": "qwerty123" }, "is_managed": 0, "locked": 0, "status": "running", "created": "2010-01-01T00:00:00+01:00", "cancelled": "2014-04-01T00:00:00+01:00" }, ... ] }
Add virtual machine
This method can be used to order a new virtual machine (VPS).
Usage
POST /v1/virtual_machines
POST parameters
| Parameter |
Description |
name |
Name of the VPS (for internal use) |
dns_name |
DNS name of the VPS |
ram |
RAM size in MB |
storage |
Storage size in GB |
storage_type |
Storage type (hdd or ssd) |
template |
Template id to provision |
snapshot |
Snapshot id to provision |
site |
Site id to provision in |
cpu_count |
Number of CPU cores |
cpu_cap |
CPU capacity limit in percent |
Notes
- The
name parameter is optional. When unspecified, a value will be auto-generated.
- The
dns_name parameter is also optional. When unspecified, a value will be auto-generated based on the VPS name ([name].tilaa.cloud).
- If the
dns_name is set to a fqdn within the .tilaa.cloud subdomain, A (IPv4), AAAA (IPv6) and PTR (IPv4+IPv6) records will be automatically created. Otherwise only PTR records will be created (for obvious reasons).
- The
snapshot parameter is optional. When used, the template parameter doesn't need to be specified. Its value will be inherited from the snapshot.
- The
site parameter is optional (and can onluy be used when at least one VPS already exists on your account). When unspecified, a site will be auto-selected.
- The
cpu_count and cpu_cap parameters are optional. When unspecified, the default values for the selected RAM amount will be used.
- All other parameters are required.
- Valid values for the
ram, cpu_count, cpu_cap, storage and storage_type parameters can be queried with the GET /v1/presets API call.
- Valid values for the
template parameter can be queried with the GET /v1/templates API call.
- Valid values for the
snapshot parameter can be queried with the GET /v1/snapshots API call.
- Valid values for the
site parameter can be queried with the GET /v1/sites API call.
Example
curl -su email:password https://api.tilaa.com/v1/virtual_machines -d name=newvm -d ram=1024 -d storage=20 -d storage_type=hdd -d template=381{ "id": 42, "message": "The virtual machine has been created", "status": "OK" }
View virtual machine
This method returns all information of a specific virtual machine (VPS).
Usage
GET /v1/virtual_machines/[id]
Example
curl -su emailPassword https://api.tilaa.com/v1/virtual_machines/[id]{ "status": "OK", "virtual_machine": { "id": 42, "name": "myserver", "cpu": { "count": 2, "cap": 80 }, "ram": 2048, "storage": { "size": 20, "type": "hdd" }, "site": { "id": 4, "name": "Haarlem, NL, CO2 Neutral" }, "template": { "id": 255, "name": "Scientific Linux 6.2, 64 bit" }, "network": [ { "id": 323, "family": 4, "address": "127.0.0.1", "dns_name": "myserver.tilaa.cloud" }, { "id": 324, "family": 6, "address": "fe80::1", "dns_name": "myserver.tilaa.cloud" } ], "admin": { "account": "root", "initial_password": "qwerty123" }, "is_managed": 0, "locked": 0, "status": "running", "created": "2010-01-01T00:00:00+01:00", "cancelled": "2014-04-01T00:00:00+01:00" } }
Edit virtual machine
This method can be used to re-install and/or edit the name, ram, storage and template settings for a specific virtual machine (VPS).
Usage
POST /v1/virtual_machines/[id]
POST parameters
| Parameter |
Description |
name |
Name of the VPS (not used for provisioning) |
ram |
RAM size in MB |
storage |
Storage size in GB |
template |
Template id to provision |
reinstall |
Re-install the virtual machine |
confirm_reinstall |
Confirmation for destructive changes |
cpu_count |
Number of CPU cores |
cpu_cap |
CPU capacity limit in percent |
Notes
- All parameters are optional. When unspecified, the existing value is maintained.
- If the
ram parameter is modified, the cpu_count and cpu_cap values will be (re)set to the default values, if unspecified.
- Destructive changes will not be applied by default, unless the
confirm_reinstall parameter is specified (any non-zero value will do).
- Shrinking storage is not supported and will triger a re-install of the virtual machine (but only if the
confirm_reinstall has been specified).
- Valid values for the
ram, cpu_count, cpu_cap and storage parameters can be queried with the GET /v1/presets API call.
- Valid values for the
template parameter can be queried with the GET /v1/templates API call.
Example
curl -su email:password https://api.tilaa.com/v1/virtual_machines/[id] -d name=newname -d ram=1024{ "status": "OK", "message": "The virtual machine has been updated" }
Cancel virtual machine
This method can be used to cancel the subscription for a specific virtual machine (VPS).
Usage
POST /v1/virtual_machines/[id]/cancel
POST parameters
| Parameter |
Description |
date |
Date of the cancellation |
Notes
- A list of possible cancel dates can be queried with the
GET /v1/virtual_machines/[id]/cancel API call.
- A cancelled subscription cannot be modified. To change the cancel date or other virtual machine parameters, undo the cancellation first.
- To remove an existing cancellation, use a value of
0 for the date parameter.
Example
To list possible cancel dates
curl -su email:password https://api.tilaa.com/v1/virtual_machines/[id]/cancel
To undo an existing cancellation
curl -su email:password https://api.tilaa.com/v1/virtual_machines/[id]/cancel -d date=0
To cancel a subscription
curl -su email:password https://api.tilaa.com/v1/virtual_machines/[id]/cancel -d date=2014-04-01{ "message": "Service has been cancelled", "status": "OK" }
Run virtual machine task
This method can be used to execute a task for a specific virtual machine (VPS).
Usage
GET /v1/virtual_machines/[id]/[task]
Valid tasks
| Task |
Description |
start |
Start the virtual machine |
stop |
Gracefully shut down the virtual machine |
restart |
Gracefully restart the virtual machine |
poweroff |
Immediately shut down the virtual machine |
rescue |
Reboot the virtual machine into a rescue environment |
Notes
- To reinstall or otherwise modify a virtual machine, use the
POST /v1/virtual_machines/[id] API call.
Example
curl -su email:password https://api.tilaa.com/v1/virtual_machines/[id]/[task]{ "status": "OK" }
Create snapshot
This method can be used to create a snapshot from a specific virtual machine (VPS).
The VPS will be shut down while the snapshot is being created. We do this to ensure all applications have written their data to disk and the filesystem is marked clean, before creating a copy of the disk.
You can force an online snapshot by specifying the online parameter. With an online snapshot the VPS will remain available, while a copy of the disk is being created in the background. Because in this case a copy is being made of open files this could lead to corruption of your data. This could lead to problems with restoring databases, for example.
Usage
POST /v1/virtual_machines/[id]/create_snapshot
POST parameters
| Parameter |
Description |
name |
Name of the snapshot |
online |
Create an online snapshot (any non-zero value will do) |
overwrite |
If the VPS has an associated snapshot, overwrite it instead of creating a new one (any non-zero value will do) |
Notes
- All parameters are optional.
Example
curl -su email:password https://api.tilaa.com/v1/virtual_machines/[id]/create_snapshot -d name=mysnap{ "status": "OK", "message": "The virtual machine snapshot is being created" }
Restore snapshot
This method can be used to restore a snapshot to a specific virtual machine (VPS).
Usage
POST /v1/virtual_machines/[id]/restore_snapshot
POST parameters
| Parameter |
Description |
snapshot |
Snapshot id to restore |
Notes
- Valid values for the
snapshot parameter can be queried with the GET /v1/snapshots API call.
Example
curl -su email:password https://api.tilaa.com/v1/virtual_machines/[id]/restore_snapshot -d snapshot=42{ "status": "OK", "message": "The virtual machine snapshot is being restored" }
List snapshots
This method returns a list of all the virtual machine snapshots available under your account.
Usage
GET /v1/snapshots
Example
curl -su email:password https://api.tilaa.com/v1/snapshots{ "status": "OK", "snapshots": [ { "created": "2014-06-02T11:59:58+02:00", "status": "success", "template": { "name": "Scientific Linux 6.2, 64 bit", "id": 42 }, "storage": 80, "ram": 1024, "name": "myserver (Scientific Linux 6.2, 64 bit)", "id": 42 }, ... ] }
View snapshot
This method returns all information of a specific virtual machine snapshot.
Usage
GET /v1/snapshots/[id]
Example
curl -su email:password https://api.tilaa.com/v1/snapshots/[id]{ "status": "OK", "snapshot": { "created": "2014-06-02T11:59:58+02:00", "status": "success", "template": { "name": "Scientific Linux 6.2, 64 bit", "id": 42 }, "storage": 80, "ram": 1024, "name": "myserver (Scientific Linux 6.2, 64 bit)", "id": 42 } }
Edit snapshot
This method can be used to edit the name for a specific virtual machine snapshot.
Usage
POST /v1/snapshots/[id]
POST parameters
| Parameter |
Description |
name |
Name of the snapshot |
Example
curl -su email:password https://api.tilaa.com/v1/snapshots/[id] -d name=newname{ "status": "OK", "message": "The virtual machine snapshot has been updated" }
Delete snapshot
This method can be used to delete a specific virtual machine snapshot.
Usage
DELETE /v1/snapshots/[id]
Example
curl -su email:password https://api.tilaa.com/v1/snapshots/[id] -X DELETE{ "status": "OK", "message": "The virtual machine snapshot has been deleted" }
List presets
This method returns a list of all valid ram, storage type and storage size values, used to create a new virtual machine (VPS) or to resize an existing one.
Usage
GET /v1/presets
Example
curl -su email:password https://api.tilaa.com/v1/presets{ "status": "OK", "presets": { "ram": { "sizes": [ 512, 1024, 2048, ... ] }, "storage": [ { "type": "hdd", "sizes": [ 20, 30, ... ] }, { "type": "ssd", "sizes": [ 20, 30, ... ] } ] } }
List sites
This method returns a list of all sites that are available for provisioning of a new virtual machine (VPS).
Usage
GET /v1/sites
Example
curl -su email:password https://api.tilaa.com/v1/sites{ "status": "OK", "sites": [ { "id": 4, "name": "Haarlem, NL, CO2 Neutral" }, { "id": 5, "name": "Amsterdam, NL, CO2 Neutral" } ] }
List metadata
This method returns a list of all user data profiles available under your account.
Usage
GET /v1/metadata
Example
curl -su email:password https://api.tilaa.com/v1/metadata{ "status": "OK", "metadata": [ { "id": 1, "name": "myprofile1", "user_data": "#cloud-config...", "created": "2015-10-12T10:14:29+02:00", "modified": "2015-10-12T14:03:29+02:00" }, { "id": 2, "name": "myprofile2", "user_data": "#cloud-config...", "created": "2015-10-12T10:27:03+02:00", "modified": "2015-10-13T02:41:54+02:00" } ] }
Add metadata
This method can be used to create a new user data profile for use with our metadata service.
Usage
POST /v1/metadata
POST parameters
| Parameter |
Description |
name |
Name of the user data profile |
user_data |
User data profile |
Example
curl -su email:password https://api.tilaa.com/v1/metadata -d name=newprofile -d user_data="#cloud-config…"{ "id": 1, "status": "OK", "message": "Metadata has been created successfully" }
View metadata
This method returns all information of a specific user data profile.
Usage
GET /v1/metadata/[id]
Example
curl -su email:password https://api.tilaa.com/v1/metadata/[id]{ "status": "OK", "metadata": { "id": 1, "name": "myprofile", "user_data": "#cloud-config…", "created": "2015-10-12T10:14:29+02:00", "modified": "2015-10-12T14:03:29+02:00" } }
Edit metadata
This method can be used to update an existing user data profile.
Usage
POST /v1/metadata/[id]
POST parameters
| Parameter |
Description |
name |
Name of the user data profile |
user_data |
User data profile |
Example
curl -su email:password https://api.tilaa.com/v1/metadata/[id] -d name=myprofile -d user_data="#cloud-config…"{ "id": 1, "status": "OK", "message": "Metadata has been updated successfully" }
Delete metadata
This method can be used to delete a specific user data profile.
Usage
DELETE /v1/metadata/[id]
Example
curl -su email:password https://api.tilaa.com/v1/metadata/[id] -X DELETE{ "status": "OK", "message": "Metadata has been deleted successfully" }
List SSH keys
This method returns a list of all SSH keys available under your account.
Usage
GET /v1/ssh_keys
Example
curl -su email:password https://api.tilaa.com/v1/ssh_keys{ "status": "OK", "ssh_keys": [ { "id": 1, "user_id": 1337, "label": "mykey1", "key": "ssh-rsa AAAAB…", "created": "2015-10-01T12:49:33+02:00", "modified": "2015-10-01T12:49:33+02:00" }, { "id": 2, "user_id": 1338, "label": "mykey2", "key": "ssh-rsa AAAAB…", "created": "2015-10-1T03:57:13+02:00", "modified": "2015-10-1T03:57:13+02:00" } ] }
Add SSH key
This method can be used to add a new SSH key.
Usage
POST /v1/ssh_keys
POST parameters
| Parameter |
Description |
user_id |
ID of the user to bind this key to |
label |
Label for the SSH key |
key |
OpenSSH public key |
Example
curl -su email:password https://api.tilaa.com/v1/ssh_keys -d label=newkey -d key="ssh-rsa AAAAB…"{ "status": "OK", "message": "SSH key has been added" }
View SSH key
This method returns all information of a specific SSH key.
Usage
GET /v1/ssh_keys/[id]
Example
curl -su email:password https://api.tilaa.com/v1/ssh_keys/[id]{ "status": "OK", "ssh_key": { "id": 1, "user_id": 1337, "label": "mykey", "key": "ssh-rsa AAAAB…", "created": "2015-10-01T12:49:33+02:00", "modified": "2015-10-01T12:49:33+02:00" } }
Edit SSH key
This method can be used to update an SSH key.
Usage
POST /v1/ssh_keys/[id]
POST parameters
| Parameter |
Description |
user_id |
ID of the user to bind this key to |
label |
Label that describes the SSH key |
key |
OpenSSH public key |
Example
Delete SSH key
This method can be used to delete an SSH key.
Usage
DELETE /v1/ssh_keys/[id]
Example
curl -su email:password https://api.tilaa.com/v1/ssh_keys/[id] -X DELETE{ "status": "OK", "message": "SSH key has been deleted" }
