API documentatie

Onze openbare API kan gebruikt worden om het beheer van Tilaa virtuele machines (VPS) te automatiseren. Hieronder vind je een lijst met beschikbare RESTful API-calls.

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

curl -su email:password https://api.tilaa.com/v1/ssh_keys/[id] -d label=mykey -d key="ssh-rsa AAAAB…"{ "status": "OK", "message": "SSH key has been updated" }

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" }

Miscellaneous

Virtual machine states

API status Dashboard description
pending not installed yet
create_failed install failed
destroyed destroyed
creating installing
stopped stopped
starting starting
restarting restarting
running running
running_rescue rescue mode
stopping stopping
resize_failed resize failed
destroying destroying
destroy_failed destroy failed
resizing resizing
migrating migrating
livemigrating migrating (live)
migrate_failed migration failed
paused not responding
creating_snapshot creating snapshot
restoring_snapshot restoring snapshot
restore_snapshot_failed restore snapshot failed