Tilaa API Reference – Tilaa Support desk

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 includes the status attribute to indicate success (OK) or failure (ERROR) and optionally a message attribute to give further information. Input validation errors for POST queries are returned in an additional errors array.

Serverless Containers:
For information on Tilaa's GraphQL-API for use with our Serverless Containers platform, visit the GraphQL API knowledge base page.

1. Introduction

Authentication

All endpoints require Basic Authentication.

API User Required:
For security reasons, you cannot use your main Tilaa user account to access this API. Instead, you must add an API user to your customer account and use the specified login credentials to authenticate.

This requires a unique and validated email address, used to notify you about important API announcements (deprecation, maintenance windows).
Always use HTTPS when calling the API to prevent eavesdropping.
Only store your API credentials in a private and secure location.

Billing and Invoicing

All Tilaa services are pre-paid. To order new services through the API you need to have sufficient funds on your account. Account credit can be added by making a payment through the Tilaa dashboard. Billing occurs each day at 0:00AM (Europe/Amsterdam timezone).

General Usage

Getting familiar with and testing the API is easy using the curl command. We recommend installing the jq tool for reading, querying, and filtering the JSON output.

For example, list all IPs of your virtual machines:

curl -su email:password https://api.tilaa.com/v1/virtual_machines | jq .virtual_machines[].network[].address

2. Users

List users

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

3. Virtual Machines

List virtual machines

Usage:

GET /v1/virtual_machines

Example:

curl -su email:password https://api.tilaa.com/v1/virtual_machines

Add virtual machine

Order a new virtual machine (VPS).

Usage:

POST /v1/virtual_machines

Parameter	Description
`name`	Name of the VPS (Auto-generated if unspecified).
`dns_name`	DNS name of the VPS (Auto-generated as `[name].tilaa.cloud` if unspecified).
`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 (Overrides template if specified).
`site`	Site id to provision in.
`cpu_count`	Number of CPU cores.
`cpu_cap`	CPU capacity limit in percent.

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

View virtual machine

Returns all information of a specific virtual machine.

Usage:

GET /v1/virtual_machines/[id]

Example:

curl -su email:password https://api.tilaa.com/v1/virtual_machines/[id]

Edit virtual machine

Re-install and/or edit the name, ram, storage, and template settings for a VPS.

Usage:

POST /v1/virtual_machines/[id]

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 (Any non-zero value).
`cpu_count`	Number of CPU cores.
`cpu_cap`	CPU capacity limit in percent.

Example:

curl -su email:password https://api.tilaa.com/v1/virtual_machines/[id] -d name=newname -d ram=1024

Cancel virtual machine

Cancel the subscription for a specific virtual machine.

Usage:

POST /v1/virtual_machines/[id]/cancel

Parameter	Description
`date`	Date of the cancellation. Use `0` to undo an existing cancellation.

Examples:

# List possible cancel dates
curl -su email:password https://api.tilaa.com/v1/virtual_machines/[id]/cancel

# Cancel a subscription
curl -su email:password https://api.tilaa.com/v1/virtual_machines/[id]/cancel -d date=2024-04-01

# Undo an existing cancellation
curl -su email:password https://api.tilaa.com/v1/virtual_machines/[id]/cancel -d date=0

Run virtual machine task

Execute a task for a specific virtual machine.

Usage:

GET /v1/virtual_machines/[id]/[task]

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.

Example:

curl -su email:password https://api.tilaa.com/v1/virtual_machines/[id]/restart

4. Snapshots

Create snapshot

Create a snapshot from a specific virtual machine. The VPS will be shut down while the snapshot is created to ensure data consistency.

Usage:

POST /v1/virtual_machines/[id]/create_snapshot

Parameter	Description
`name`	Name of the snapshot.
`online`	Create an online snapshot (any non-zero value). WARNING: Copies open files, can lead to data corruption.
`overwrite`	Overwrite the associated snapshot instead of creating a new one (any non-zero value).

Example:

curl -su email:password https://api.tilaa.com/v1/virtual_machines/[id]/create_snapshot -d name=mysnap

Restore snapshot

Usage:

POST /v1/virtual_machines/[id]/restore_snapshot

Example:

curl -su email:password https://api.tilaa.com/v1/virtual_machines/[id]/restore_snapshot -d snapshot=42

List snapshots

Usage:

GET /v1/snapshots

View snapshot

Usage:

GET /v1/snapshots/[id]

Edit snapshot

Usage:

POST /v1/snapshots/[id]

Example:

curl -su email:password https://api.tilaa.com/v1/snapshots/[id] -d name=newname

Delete snapshot

Usage:

DELETE /v1/snapshots/[id]

Example:

curl -su email:password https://api.tilaa.com/v1/snapshots/[id] -X DELETE

5. Presets & Sites

List presets

Returns a list of all valid ram, storage type, and storage size values.

Usage:

GET /v1/presets

List sites

Returns a list of all sites available for provisioning.

Usage:

GET /v1/sites

6. Metadata (User Data Profiles)

List metadata

Usage:

GET /v1/metadata

Add metadata

Create a new user data profile (cloud-config) for use with the metadata service.

Usage:

POST /v1/metadata

Example:

curl -su email:password https://api.tilaa.com/v1/metadata -d name=newprofile -d user_data="#cloud-config..."

View metadata

Usage:

GET /v1/metadata/[id]

Edit metadata

Usage:

POST /v1/metadata/[id]

Example:

curl -su email:password https://api.tilaa.com/v1/metadata/[id] -d name=myprofile -d user_data="#cloud-config..."

Delete metadata

Usage:

DELETE /v1/metadata/[id]

7. SSH Keys

List SSH keys

Usage:

GET /v1/ssh_keys

Add SSH key

Usage:

POST /v1/ssh_keys

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

View SSH key

Usage:

GET /v1/ssh_keys/[id]

Edit SSH key

Usage:

POST /v1/ssh_keys/[id]

Delete SSH key

Usage:

DELETE /v1/ssh_keys/[id]

8. 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

api, rest, endpoint, virtual machine, ssh keys, metadata, snapshot, automation, reference