Quick start guide

The page provides a walk through guide for provisioning a server using the VPS Provisioning API.

  • Create an API key using the customer control panel.

  • Set some evironment variables. Use the key details from the control panel, and set the path to your own SSH public key if different.

$ API_USER="abcd1234"
$ API_PASS="efgh5678"
$ SSH_KEY=~/.ssh/id_rsa.pub
  • Get an access token from the auth server:
$ TOKEN=$(curl -s -d 'grant_type=client_credentials' -u "$API_USER:$API_PASS" https://auth.mythic-beasts.com/login | jq -r .access_token)
  • Find a server product that fits your needs (e.g., 1G of RAM):
$ PRODUCT=$(curl -s -H "Authorization: Bearer $TOKEN" https://api.mythic-beasts.com/beta/vps/products | jq -r '.[] | select(.specs.ram == 1024) | .code')
$ echo $PRODUCT
  • Find the image for the operating system that you'd like to use (e.g., Sympl on Debian):
$ IMAGE=$(curl -s -H "Authorization: Bearer $TOKEN" https://api.mythic-beasts.com/beta/vps/images | jq -r '.[] | select(.description | test("Sympl")) | .name')
$ echo $IMAGE
  • Find a suitable disk size (e.g., smallest SSD size — SSD is the default disk type):
$ SIZE=$(curl -s -H "Authorization: Bearer $TOKEN" https://api.mythic-beasts.com/beta/vps/disk-sizes | jq -r '.ssd | min')
$ echo $SIZE
  • Create the server:
$ curl -D- -X POST -d "{\"product\": \"$PRODUCT\", \"image\": \"$IMAGE\", \"ssh_keys\": \"$(cat $SSH_KEY)\", \"disk_size\": $SIZE}" -H "Content-Type: application/json" -H "Authorization: Bearer $TOKEN" https://api.mythic-beasts.com/beta/vps/servers
HTTP/1.1 202 Accepted
Location: https://api.mythic-beasts.com/beta/queue/vps/41
Content-Type: application/json

  • Poll the URL provided in the Location header.
$ curl -D- -H "Authorization: Bearer $TOKEN" https://api.mythic-beasts.com/beta/queue/vps/41
HTTP/1.1 200 OK
Content-Type: application/json

{"identifier":"c10524vtjv","status":"Waiting for DNS and DHCP updates (118 seconds remaining)"}
  • Poll again (after a minute or so):
$ curl -D- -H "Authorization: Bearer $TOKEN" https://api.mythic-beasts.com/beta/queue/vps/41
HTTP/1.1 200 OK
Content-Type: application/json

{"identifier":"c10524vtjv","status":"OS installation 45% complete"}
  • Poll again (after a few more minutes):
$ curl -D- -H "Authorization: Bearer $TOKEN" https://api.mythic-beasts.com/beta/queue/vps/41
HTTP/1.1 303 See other
Location: https://api.mythic-beasts.com/beta/vps/servers/c10524vtjv
Content-Type: application/json

  • Get server details from the indicated URL and extract the identifier:
$ curl -s -H "Authorization: Bearer $TOKEN" https://api.mythic-beasts.com/beta/vps/servers/c10524vtjv | jq
  "boot_device": "hd",
  "vnc": {
    "ipv6": "2a00:1098:3d::1",
    "display": 148,
    "port": 6048,
    "ipv4": "",
    "mode": "disabled",
    "password": "aiRu4Ahj"
  "ipv4": [],
  "net_device": "virtio",
  "specs": {
    "cores": 1,
    "disk_size": 5120,
    "ram": 1024,
    "disk_type": "ssd"
  "cpu_mode": "performance",
  "ipv6": [
  "zone": {
    "name": "Cambridge, UK",
    "code": "cam"
  "iso_image": "automated-install-config",
  "disk_bus": "virtio",
  "product": "VPSX4",
  "name": null,
  "identifier": "c10524vtjv",
  "host_server": "vdstesthost",
  "status": "running",
  "price": 5.63,
  "admin_console": {
    "hostname": "admin.c10524vtjv.vs.mythic-beasts.com",
    "username": "c10524vtjv"
  "ssh_proxy": {
    "hostname": "admin.c10524vtjv.vs.mythic-beasts.com",
    "port": 10048
  "macs": [
$ SERVER=$(curl -s -H "Authorization: Bearer $TOKEN" https://api.mythic-beasts.com/beta/vps/servers/c10524vtjv | jq -r .identifier)
$ echo $SERVER
  • This server is IPv6-only (we did not request an IPv4 address), so if you have an IPv6 connection, you can login now:
$ ssh root@$SERVER.vs.mythic-beasts.com
  • Otherwise, you can grab the SSH proxy port number from the server details response above:
$ PORT=$(curl -s -H "Authorization: Bearer $TOKEN" https://api.mythic-beasts.com/beta/vps/servers/c10524vtjv | jq -r .ssh_proxy.port)
$ echo $PORT
  • And use that to login:
$ ssh -p $PORT root@admin.$SERVER.vs.mythic-beasts.com
The authenticity of host '[admin.c10524vtjv.vs.mythic-beasts.com]:10048 ([]:10048)' can't be established.
ECDSA key fingerprint is SHA256:UmD8UxNB5iA6EbrutR2WA5Rs5x0dEoU8yBZdnShpTgE.
Are you sure you want to continue connecting (yes/no)? yes
Warning: Permanently added '[admin.c10524vtjv.vs.mythic-beasts.com]:10048,[]:10048' (ECDSA) to the list of known hosts.
Linux c10524vtjv.vs.mythic-beasts.com 4.19.0-13-amd64 #1 SMP Debian 4.19.160-2 (2020-11-28) x86_64

The programs included with the Debian GNU/Linux system are free software;
the exact distribution terms for each program are described in the
individual files in /usr/share/doc/*/copyright.

Debian GNU/Linux comes with ABSOLUTELY NO WARRANTY, to the extent
permitted by applicable law.
  • Once you are done with the server, you can cancel it:
$ curl -D- -X DELETE -H "Authorization: Bearer $TOKEN" https://api.mythic-beasts.com/beta/vps/servers/c10524vtjv
HTTP/1.1 200 OK
Content-Type: application/json

{"message":"Service unprovisioned"}

For more information, please see the full API docs.