Virtual Server Provisioning API

OpenAPI YAML

This API enables provisioning and managing of virtual servers in the Mythic Beasts Cloud.

Servers provisioned using this API use on demand pricing. They can be created and cancelled at any time, and you will be charged on a per-second basis.

All requests need to be authenticated using a Bearer token obtained from our auth service.

The base URL for this service is:

  • https://api.mythic-beasts.com/beta

The endpoints listed below should be appended to the above URL.

Endpoints

get /vps/servers

https://api.mythic-beasts.com/beta/vps/servers

Lists all virtual servers associated with this account.

Responses

CodeDescription
200

Server information

An object with keys giving the name of all virtual servers associated with this account. Values are objects with additional information about the server.

application/json

{
    "vps1": {
        "identifier": "vps1",
        "product": "VPSX4",
        "name": null,
        "dormant": true
    },
    "vps2": {
        "identifier": "vps2",
        "product": "VPSX256",
        "name": "web-server-01",
        "dormant": false
    }
}
403

Not authorised to access this API.

application/json

{
    "error": "Not authorised"
}

post /vps/servers

https://api.mythic-beasts.com/beta/vps/servers

Provisions a new virtual server with an autogenerated identifier.

This operation is performed asynchronously (see documentation for 202 response).

Parameters

NameLocationDescription
identifier string path

A unique identifier for the server. This will form part of the hostname for the server, and should consist only of alphanumerics and _.

Request Body JSON

NameDescription
product string

(Required) Virtual server product code; valid values from products endpoint
name string

(Optional) Friendly name for server

Default: null
host_server string

(Optional) Name of private cloud host server to provision on; refer to hosts endpoint for valid names

Default: null
hostname string

(Optional) Hostname the new server should be installed with

Default: "{identifier}.vs.mythic-beasts.com"
set_forward_dns boolean

(Optional) Whether to automatically add A/AAAA records for the server's IP addresses to the selected hostname

Default: false
set_reverse_dns boolean

(Optional) Whether to automatically set reverse DNS for the server's IP addresses to the selected hostname

Default: false
disk_type string

(Optional) Disk type

Possible values:
  • "ssd"
  • "hdd"
Default: "ssd"
disk_size integer

(Required) Disk size, in MB; valid values returned by disk sizes endpoint
extra_cores integer

(Optional) Number of CPU cores in addition to the ones provided by the base product (private cloud only)
ipv4 boolean

(Optional) Whether or not to allocate an IPv4 address for this server; an IPv6 address will always be allocated; IPv4 is a chargeable option -- see the pricing endpoint

Default: false
zone string

(Optional) Zone (datacentre) code; valid values from zones endpoint

Default: "any"
image string

(Optional) Operating system image name; valid values from images endpoint; if this is unspecified, no OS will be installed and server will be left powered off

Default: null
user_data string

(Optional) Stored user data ID or name from user data endpoint

Default: null
user_data_string string

(Optional) User data (as a literal string)

Default: null
ssh_keys string

(Optional) Public SSH key(s) to be added to /root/.ssh/authorized_keys on server

Default: null
vnc object

(Optional) VNC settings
mode string

(Optional) VNC mode

Possible values:
  • "local"
  • "remote"
  • "disabled"
Default: "disabled"
password string

(Optional) VNC password; auto-generated if unspecified

Default: null
admin_console object

(Optional) Admin console authentication
password string

(Optional) Admin console password; password login will be disabled if unspecified

Default: null
ssh_keys string

(Optional) Admin console SSH key(s)

Default: null
cpu_mode string

(Optional) CPU mode

Possible values:
  • "performance"
  • "compatibility"
  • "performance-dangerous"
Default: "performance"
net_device string

(Optional) Virtual network device type

Possible values:
  • "virtio"
  • "e1000"
  • "rtl8139"
  • "ne2k_pci"
Default: "virtio"
Example

application/json

{
    "product": "VPSX16",
    "name": "web-server-01",
    "host_server": "priv-vds-host-1",
    "hostname": "my-new-server.example.com",
    "set_forward_dns": true,
    "set_reverse_dns": true,
    "disk_type": "hdd",
    "disk_size": 20,
    "extra_cores": 4,
    "ipv4": false,
    "zone": "cam",
    "image": "01-cloudinit-debian-buster.raw.gz",
    "user_data": 2513,
    "user_data_string": "#cloud-config\n\npackages:\n  - apache2\n\n",
    "ssh_keys": "ssh-rsa AAAAB.... user@example.com",
    "vnc": {
        "mode": "local",
        "password": null
    },
    "admin_console": {
        "password": null,
        "ssh_keys": "ssh-rsa AAAAB.... user@example.com"
    },
    "cpu_mode": "performance",
    "net_device": "virtio"
}

Responses

CodeDescription
202

Provisioning request accepted.

The response will include a Location header specifying a URL which can be polled for provisioning status.

When provisioning is complete, this URL will return 303 See Other with a Location header indicating the URL from which server information can be obtained.

Provisioning typically takes 2-3 minutes. The server may not be fully booted when the poll URL returns 303.

In the event of a provisioning error, the polled URL will return 500, with details of the error in the body.
400

Invalid parameters

application/json

{
    "error": "Invalid parameter disk_type: must be one of ssd, hdd"
}
403

Not authorised to provision server or insufficient on-demand service limit

application/json

{
    "error": "Not authorised"
}
409

Server name already exists

application/json

{
    "error": "Server name already exists"
}

get /vps/servers/{identifier}

https://api.mythic-beasts.com/beta/vps/servers/{identifier}

Returns information about the specified server.

Parameters

NameLocationDescription
identifier string path

The server identifier

Responses

CodeDescription
200

Server information

application/json

{
    "identifer": "c10524v123",
    "name": "web-server-01",
    "status": "running",
    "host_server": "vds-cam-i",
    "zone": {
        "code": "cam",
        "name": "Cambridge, UK"
    },
    "product": "VPSX8",
    "cpu_mode": "performance",
    "net_device": "virtio",
    "disk_bus": "virtio",
    "price": 10.18,
    "iso_image": "automated-install-config",
    "dormant": false,
    "boot_device": "hd",
    "ipv4": [
        "93.93.131.39"
    ],
    "ipv6": [
        "2a00:1098:0:86:1000:6a:0:1"
    ],
    "specs": {
        "disk_type": "ssd",
        "disk_size": 10240,
        "cores": 2,
        "extra_cores": 4,
        "ram": 2048
    },
    "macs": [
        "54:54:00:de:32:99"
    ],
    "admin_console": {
        "username": "vps01",
        "hostname": "admin.vps01.vs.mythic-beasts.com"
    },
    "ssh_proxy": {
        "hostname": "admin.vps01.vs.mythic-beasts.com",
        "port": 10046
    },
    "vnc": {
        "mode": "local",
        "password": "iyeew7Zo",
        "ipv4": "46.235.224.236",
        "ipv6": "2a00:1098:0:86:1000::d",
        "port": 6046,
        "display": 146
    }
}
403

Not authorised to access server or server does not exist

application/json

{
    "error": "Not authorised"
}

post /vps/servers/{identifier}

https://api.mythic-beasts.com/beta/vps/servers/{identifier}

Provisions a new virtual server with the specified identifier. DNS for the service will become available at {identifier}.vs.mythic-beasts.com.

This operation is performed asynchronously (see documentation for 202 response).

If a server with the given identifier exists, a 409 error will be returned.

Parameters

NameLocationDescription
identifier string path

A unique identifier for the server. This will form part of the hostname for the server, and should consist only of alphanumerics and _.

Request Body JSON

NameDescription
product string

(Required) Virtual server product code; valid values from products endpoint
name string

(Optional) Friendly name for server

Default: null
host_server string

(Optional) Name of private cloud host server to provision on; refer to hosts endpoint for valid names

Default: null
hostname string

(Optional) Hostname the new server should be installed with

Default: "{identifier}.vs.mythic-beasts.com"
set_forward_dns boolean

(Optional) Whether to automatically add A/AAAA records for the server's IP addresses to the selected hostname

Default: false
set_reverse_dns boolean

(Optional) Whether to automatically set reverse DNS for the server's IP addresses to the selected hostname

Default: false
disk_type string

(Optional) Disk type

Possible values:
  • "ssd"
  • "hdd"
Default: "ssd"
disk_size integer

(Required) Disk size, in MB; valid values returned by disk sizes endpoint
extra_cores integer

(Optional) Number of CPU cores in addition to the ones provided by the base product (private cloud only)
ipv4 boolean

(Optional) Whether or not to allocate an IPv4 address for this server; an IPv6 address will always be allocated; IPv4 is a chargeable option -- see the pricing endpoint

Default: false
zone string

(Optional) Zone (datacentre) code; valid values from zones endpoint

Default: "any"
image string

(Optional) Operating system image name; valid values from images endpoint; if this is unspecified, no OS will be installed and server will be left powered off

Default: null
user_data string

(Optional) Stored user data ID or name from user data endpoint

Default: null
user_data_string string

(Optional) User data (as a literal string)

Default: null
ssh_keys string

(Optional) Public SSH key(s) to be added to /root/.ssh/authorized_keys on server

Default: null
vnc object

(Optional) VNC settings
mode string

(Optional) VNC mode

Possible values:
  • "local"
  • "remote"
  • "disabled"
Default: "disabled"
password string

(Optional) VNC password; auto-generated if unspecified

Default: null
admin_console object

(Optional) Admin console authentication
password string

(Optional) Admin console password; password login will be disabled if unspecified

Default: null
ssh_keys string

(Optional) Admin console SSH key(s)

Default: null
cpu_mode string

(Optional) CPU mode

Possible values:
  • "performance"
  • "compatibility"
  • "performance-dangerous"
Default: "performance"
net_device string

(Optional) Virtual network device type

Possible values:
  • "virtio"
  • "e1000"
  • "rtl8139"
  • "ne2k_pci"
Default: "virtio"
Example

application/json

{
    "product": "VPSX16",
    "name": "web-server-01",
    "host_server": "priv-vds-host-1",
    "hostname": "my-new-server.example.com",
    "set_forward_dns": true,
    "set_reverse_dns": true,
    "disk_type": "hdd",
    "disk_size": 20,
    "extra_cores": 4,
    "ipv4": false,
    "zone": "cam",
    "image": "01-cloudinit-debian-buster.raw.gz",
    "user_data": 2513,
    "user_data_string": "#cloud-config\n\npackages:\n  - apache2\n\n",
    "ssh_keys": "ssh-rsa AAAAB.... user@example.com",
    "vnc": {
        "mode": "local",
        "password": null
    },
    "admin_console": {
        "password": null,
        "ssh_keys": "ssh-rsa AAAAB.... user@example.com"
    },
    "cpu_mode": "performance",
    "net_device": "virtio"
}

Responses

CodeDescription
202

Provisioning request accepted.

The response will include a Location header specifying a URL which can be polled for provisioning status.

When provisioning is complete, this URL will return 303 See Other with a Location header indicating the URL from which server information can be obtained.

Provisioning typically takes 2-3 minutes. The server may not be fully booted when the poll URL returns 303.

In the event of a provisioning error, the polled URL will return 500, with details of the error in the body.
400

Invalid parameters

application/json

{
    "error": "Invalid parameter disk_type: must be one of ssd, hdd"
}
403

Not authorised to provision server or insufficient on-demand service limit

application/json

{
    "error": "Not authorised"
}
409

Server name already exists

application/json

{
    "error": "Server name already exists"
}

patch /vps/servers/{identifier}

https://api.mythic-beasts.com/beta/vps/servers/{identifier}

Updates VNC and admin console settings, server name, and server spec.

Parameters

NameLocationDescription
identifier string path

Unique identifier for server

Request Body JSON

NameDescription
product string

(Optional) Virtual server product code; valid values from products endpoint
specs object

(Optional) Server spec
disk_size integer

(Optional) Disk size in MB
extra_cores integer

(Optional) Number of CPU cores in addition to the ones provided by the base product (private cloud only)
name string

(Optional) Friendly server name (set to null to remove)
boot_device string

(Optional) Boot device; changing requires VPS to be powered off

Possible values:
  • "hd"
  • "cdrom"
iso_image string

(Optional) ISO image (set to null to remove); changing requires VPS to be powered off; available images from ISO images endpoint
admin_console object

(Optional) Admin console settings
ssh_keys string

(Optional) SSH keys for admin console
password string

(Optional) Admin console password (set to null to disable)
vnc object

(Optional) VNC settings
mode string

(Optional) VNC mode

Possible values:
  • "local"
  • "remote"
  • "disabled"
password string

(Optional) VNC password
Example

application/json

{
    "product": "VPSX16",
    "specs": {
        "disk_size": 20480,
        "extra_cores": 4
    },
    "name": "web-server-01",
    "boot_device": "cdrom",
    "iso_image": "debian-10.10.0-amd64-netinst",
    "admin_console": {
        "ssh_keys": "ssh-rsa AAAAB.... user@example.com",
        "password": "ed2Jae7k"
    },
    "vnc": {
        "mode": "local",
        "password": "aeC8aeZ0"
    }
}

Responses

CodeDescription
200

Settings updated

application/json

{
    "message": "Operation successful"
}
400

Bad request

application/json

{
    "error": "Invalid parameter admin_console.password: Password must be at least 8 characters long."
}
403

Not authorised to access server or server does not exist

application/json

{
    "error": "Not authorised"
}

delete /vps/servers/{identifier}

https://api.mythic-beasts.com/beta/vps/servers/{identifier}

Unprovisions a virtual server. The associated disk will be permanently deleted.

Only on-demand servers can be unprovisioned using this method.

Parameters

NameLocationDescription
identifier string path

Unique identifier for server

Responses

CodeDescription
200

Server deleted
403

Not authorised to access server or server does not exist

application/json

{
    "error": "Not authorised"
}

get /vps/servers/{identifier}/iso-images

https://api.mythic-beasts.com/beta/vps/servers/{identifier}/iso-images

Lists available ISO images for this server. These can be used for manually installing an operating system.

Responses

CodeDescription
200

List of ISO images

application/json

{
    "debian-10.10.0-amd64-netinst": {
        "name": "debian-10.10.0-amd64-netinst",
        "description": "Debian Buster (10)"
    },
    "debian-11.0.0-amd64-netinst": {
        "name": "debian-11.0.0-amd64-netinst",
        "description": "Debian Bullseye (11)"
    }
}

post /vps/servers/{identifier}/reboot

https://api.mythic-beasts.com/beta/vps/servers/{identifier}/reboot

Reboots the server via ACPI. This depends on ACPI support in the operating system.

This method returns as soon as the reboot has been initiated.

Parameters

NameLocationDescription
identifier string path

Server identifier

Responses

CodeDescription
200

Server rebooted

application/json

{
    "message": "Operation successful"
}
403

Not authorised to access server or server does not exist

application/json

{
    "error": "Not authorised"
}

put /vps/servers/{identifier}/power

https://api.mythic-beasts.com/beta/vps/servers/{identifier}/power

Turn power on or off, or perform ACPI shutdown. The latter depends on ACPI support in the operating system. Powering off should only be used as a last resort: it will always work, but may cause data loss.

Parameters

NameLocationDescription
identifier string path

Server identifier

Request Body JSON

NameDescription
power string

(Required) Power status

Possible values:
  • "power-on"
  • "power-off"
  • "shutdown"
Example

application/json

{
    "power": "shutdown"
}

Responses

CodeDescription
200

Server power set

application/json

{
    "message": "Operation successful"
}
400

Bad request

application/json

{
    "error": "Missing parameter: power"
}
403

Not authorised to access server or server does not exist

application/json

{
    "error": "Not authorised"
}

get /vps/servers/{identifier}/console-output

https://api.mythic-beasts.com/beta/vps/servers/{identifier}/console-output

Get server console output.

Parameters

NameLocationDescription
identifier string path

Server identifier
limit integer query

Line limit (maximum number of lines of output to return)

Responses

CodeDescription
200

Console output (as a single string)

application/json

{
    "console_output": "20210223T125726: Debian GNU/Linux 10 apitest01.vs.mythic-beasts.com ttyS0\n20210223T125727: avfapi1 login:\n",
    "limit": 2
}
400

Bad request

application/json

{
    "error": "Invalid limit (must be numeric)"
}
403

Not authorised to access server or server does not exist

application/json

{
    "error": "Not authorised"
}

put /vps/servers/{identifier}/dormant

https://api.mythic-beasts.com/beta/vps/servers/{identifier}/dormant

Decommissions server but retains storage and IP addresses, or makes the server active again.

Parameters

NameLocationDescription
identifier string path

Server identifier

Request Body JSON

NameDescription
dormant boolean

(Required) Whether to make server dormant (true) or re-activate (false, and specify product)
product string

(Optional) Product code (required when re-activating server); valid values from products endpoint
Example

application/json

{
    "dormant": false,
    "product": "VPSX4"
}

Responses

CodeDescription
200

Server made dormant

application/json

{
    "message": "Operation successful"
}
400

Invalid state

application/json

{
    "error": "Server is already dormant"
}

get /vps/images

https://api.mythic-beasts.com/beta/vps/images

Gets a list of available operating system images for virtual servers.

Responses

CodeDescription
200

Operating system image list

application/json

{
    "01-cloudinit-debian-buster.raw.gz": {
        "name": "01-cloudinit-debian-buster.raw.gz",
        "description": "Debian Buster (10)"
    },
    "03-cloudinit-ubuntu-focal.raw.gz": {
        "name": "03-cloudinit-ubuntu-focal.raw.gz",
        "description": "Ubuntu Focal (20.04)"
    }
}

get /vps/products

https://api.mythic-beasts.com/beta/vps/products

Gets a list of available virtual servers products.

Responses

CodeDescription
200

Product list

application/json

{
    "VPSX16": {
        "name": "VPS 4",
        "description": "Virtual Server, VPS 4 [ 2 cores, 4GB RAM, 2T/month ]",
        "specs": {
            "cores": 2,
            "ram": 4096,
            "bandwidth": 2048
        }
    }
}

get /vps/disk-sizes

https://api.mythic-beasts.com/beta/vps/disk-sizes

Gets a list of available disk sizes.

Responses

CodeDescription
200

Disk size list

application/json

{
    "hdd": [
        10240,
        20480
    ],
    "ssd": [
        5120,
        6144
    ]
}

get /vps/zones

https://api.mythic-beasts.com/beta/vps/zones

Gets a list of available zones (datacentres) for virtual servers.

Responses

CodeDescription
200

Zone list

application/json

{
    "cam": {
        "description": "Cambridge, UK",
        "parents": [
            "uk"
        ]
    }
}

get /vps/hosts

https://api.mythic-beasts.com/beta/vps/hosts

Gets a list of available private cloud host servers.

Responses

CodeDescription
200

Private cloud host list

application/json

{
    "priv-vds-host-1": {
        "name": "priv-vds-host-1",
        "cores": 8,
        "ram": 32768,
        "disk": {
            "ssd": 0,
            "hdd": 310984
        },
        "free_ram": 12328,
        "free_disk": {
            "ssd": 0,
            "hdd": 280264
        }
    }
}

get /vps/pricing

https://api.mythic-beasts.com/beta/vps/pricing

Gets a list of prices (in pence per month) for virtual server products, disk space (price per specified number of MB), and IPv4.

Responses

CodeDescription
200

Price list

application/json

{
    "disk": {
        "ssd": {
            "price": 0.09,
            "extent": 1
        },
        "hdd": {
            "price": 0.23,
            "extent": 10
        }
    },
    "ipv4": 2.3,
    "products": {
        "VPSX4": 5.18,
        "VPSX8": 8.05
    }
}

get /vps/user-data

https://api.mythic-beasts.com/beta/vps/user-data

Gets a list of user data snippets for automated virtual server installation.

Responses

CodeDescription
200

User data snippet list

application/json

{
    "user_data": {
        "12": {
            "name": "test1",
            "id": 12,
            "size": 129
        }
    }
}

post /vps/user-data

https://api.mythic-beasts.com/beta/vps/user-data

Creates a new user data snippet.

Request Body JSON

NameDescription
name string

(Required) Snippet name
data string

(Required) Snippet data
Example

application/json

{
    "name": "web-server",
    "data": "#cloud-config\n\npackages:\n  - apache2\n\n"
}

Responses

CodeDescription
200

User data snippet created
400

Invalid parameters

application/json

{
    "error": "Missing parameter: name"
}
403

Not authorised to manage user data

application/json

{
    "error": "Not authorised"
}
409

User data already exists

application/json

{
    "error": "User data 'database-server' already exists"
}

get /vps/user-data/{id}

https://api.mythic-beasts.com/beta/vps/user-data/{id}

Returns the specified user data snippet.

Parameters

NameLocationDescription
id integer path

User data identifier

Responses

CodeDescription
200

User data snippet

application/json

{
    "name": "web-server",
    "id": 2513,
    "size": 38,
    "data": "#cloud-config\n\npackages:\n  - apache2\n\n"
}
400

Invalid parameters

application/json

{
    "error": "Invalid user data ID"
}
403

Not authorised to manage user data

application/json

{
    "error": "Not authorised"
}
404

User data snippet not found

application/json

{
    "error": "User data not found"
}

put /vps/user-data/{id}

https://api.mythic-beasts.com/beta/vps/user-data/{id}

Updates an existing user data snippet.

Request Body JSON

NameDescription
data string

(Required) Snippet data
Example

application/json

{
    "data": "#cloud-config\n\npackages:\n  - apache2\n\n"
}

Responses

CodeDescription
200

User data snippet updated
400

Invalid parameters

application/json

{
    "error": "Missing parameter: data"
}
403

Not authorised to manage user data

application/json

{
    "error": "Not authorised"
}

delete /vps/user-data/{id}

https://api.mythic-beasts.com/beta/vps/user-data/{id}

Deletes a user data snippet.

Parameters

NameLocationDescription
id string path

User data identifier

Responses

CodeDescription
200

User data deleted
403

Not authorised to manage user data

application/json

{
    "error": "Not authorised"
}
404

User data snippet not found

application/json

{
    "error": "User data not found"
}

get /queue/vps/{task}

https://api.mythic-beasts.com/beta/queue/vps/{task}

Gets the status of an asynchronous request. This is used following a 202 response from a Provision Server request.

Parameters

NameLocationDescription
task integer path

Task identifier

Responses

CodeDescription
303

Async request complete

The Location header will provide a URL with the response to the asynchronous request.
500

Async request failed

The reason for failure will be given in the error field of the JSON body.

application/json

{
    "error": "Error provisioning server"
}

Support Index

Page contents