Virtual Server Provisioning API
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
Lists all virtual servers associated with this account.
Responses
Code | Description | ||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
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
Example{ "vps1": { "identifier": "vps1", "product": "VPSX4", "family": "VPS-4", "period": "on-demand", "name": "web-server-01", "dormant": false }, "vps2": { "identifier": "vps2", "product": "VPSX16", "family": "VPS-16", "period": "on-demand", "name": "database-server", "dormant": false } } |
||||||||||||||||
403 | Not authorised to access this API. application/json
Example{ "error": "Not authorised" } |
post /vps/servers
Provisions a new virtual server with an autogenerated identifier.
This operation is performed asynchronously (see documentation for 202
response).
Parameters
Name | Location | Description |
---|---|---|
identifier string | path |
A unique identifier for the server. This will form part of the hostname for the server, and must consist only of lower-case letters and digits and be at most 20 characters long. |
Request Body JSON
Name | Description |
---|---|
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:
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 Default:
null |
vnc object |
(Optional) VNC settings |
mode string |
(Optional) VNC mode
Possible values:
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:
Default:
"performance" |
net_device string |
(Optional) Virtual network device type
Possible values:
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
Code | Description | ||||
---|---|---|---|---|---|
202 | Provisioning request accepted. The response will include a When provisioning is complete, this URL will return Provisioning typically takes 2-3 minutes. The server may not be
fully booted when the poll URL returns In the event of a provisioning error, the polled URL will return
|
||||
400 | Invalid parameters application/json
Example{ "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
Example{ "error": "Not authorised" } |
||||
409 | Server name already exists application/json
Example{ "error": "Server name already exists" } |
get /vps/servers/{identifier}
Returns information about the specified server.
Parameters
Name | Location | Description |
---|---|---|
identifier string | path |
The server identifier |
Responses
Code | Description | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
200 | Server information application/json
Example{ "identifier": "c10524v123", "name": "web-server-01", "status": "running", "host_server": "vds-cam-i", "zone": { "code": "cam", "name": "Cambridge, UK" }, "product": "VPSX8", "family": "VPS-8", "cpu_mode": "performance", "net_device": "virtio", "disk_bus": "virtio", "price": 1018, "period": "on-demand", "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
Example{ "error": "Not authorised" } |
post /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
Name | Location | Description |
---|---|---|
identifier string | path |
A unique identifier for the server. This will form part of the hostname for the server, and must consist only of lower-case letters and digits and be at most 20 characters long. |
Request Body JSON
Name | Description |
---|---|
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:
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 Default:
null |
vnc object |
(Optional) VNC settings |
mode string |
(Optional) VNC mode
Possible values:
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:
Default:
"performance" |
net_device string |
(Optional) Virtual network device type
Possible values:
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
Code | Description | ||||
---|---|---|---|---|---|
202 | Provisioning request accepted. The response will include a When provisioning is complete, this URL will return Provisioning typically takes 2-3 minutes. The server may not be
fully booted when the poll URL returns In the event of a provisioning error, the polled URL will return
|
||||
400 | Invalid parameters application/json
Example{ "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
Example{ "error": "Not authorised" } |
||||
409 | Server name already exists application/json
Example{ "error": "Server name already exists" } |
patch /vps/servers/{identifier}
Updates VNC and admin console settings, server name, and server spec.
Parameters
Name | Location | Description |
---|---|---|
identifier string | path |
Unique identifier for server |
Request Body JSON
Name | Description |
---|---|
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 |
boot_device string |
(Optional) Boot device; changing requires VPS to be powered off
Possible values:
|
iso_image string |
(Optional) ISO image (set to |
admin_console object |
(Optional) Admin console settings |
ssh_keys string |
(Optional) SSH keys for admin console |
password string |
(Optional) Admin console password (set to |
vnc object |
(Optional) VNC settings |
mode string |
(Optional) VNC mode
Possible values:
|
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
Code | Description | ||||
---|---|---|---|---|---|
200 | Settings updated application/json
Example{ "message": "Operation successful" } |
||||
400 | Bad request application/json
Example{ "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
Example{ "error": "Not authorised" } |
delete /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
Name | Location | Description |
---|---|---|
identifier string | path |
Unique identifier for server |
Responses
Code | Description | ||||
---|---|---|---|---|---|
200 | Server deleted |
||||
403 | Not authorised to access server or server does not exist application/json
Example{ "error": "Not authorised" } |
get /vps/servers/{identifier}/iso-images
Lists available ISO images for this server. These can be used for manually installing an operating system.
Responses
Code | Description | ||||||||
---|---|---|---|---|---|---|---|---|---|
200 | List of ISO images application/json
Example{ "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
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
Name | Location | Description |
---|---|---|
identifier string | path |
Server identifier |
Responses
Code | Description | ||||
---|---|---|---|---|---|
200 | Server rebooted application/json
Example{ "message": "Operation successful" } |
||||
403 | Not authorised to access server or server does not exist application/json
Example{ "error": "Not authorised" } |
put /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
Name | Location | Description |
---|---|---|
identifier string | path |
Server identifier |
Request Body JSON
Name | Description |
---|---|
power string |
(Required) Power status
Possible values:
|
Example
application/json
{ "power": "shutdown" }
Responses
Code | Description | ||||
---|---|---|---|---|---|
200 | Server power set application/json
Example{ "message": "Operation successful" } |
||||
400 | Bad request application/json
Example{ "error": "Missing parameter: power" } |
||||
403 | Not authorised to access server or server does not exist application/json
Example{ "error": "Not authorised" } |
get /vps/servers/{identifier}/console-output
Get server console output.
Parameters
Name | Location | Description |
---|---|---|
identifier string | path |
Server identifier |
limit integer | query |
Line limit (maximum number of lines of output to return; default 100, maximum 1000) |
Responses
Code | Description | ||||||
---|---|---|---|---|---|---|---|
200 | Console output (as a single string) application/json
Example{ "console_output": "20210223T125726: Debian GNU/Linux 10 apitest01.vs.mythic-beasts.com ttyS0\n20210223T125727: avfapi1 login:\n", "limit": 2 } |
||||||
400 | Bad request application/json
Example{ "error": "Invalid limit (must be numeric)" } |
||||||
403 | Not authorised to access server or server does not exist application/json
Example{ "error": "Not authorised" } |
put /vps/servers/{identifier}/dormant
Decommissions server but retains storage and IP addresses, or makes the server active again.
Parameters
Name | Location | Description |
---|---|---|
identifier string | path |
Server identifier |
Request Body JSON
Name | Description |
---|---|
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
Code | Description | ||||
---|---|---|---|---|---|
200 | Server made dormant application/json
Example{ "message": "Operation successful" } |
||||
400 | Invalid state application/json
Example{ "error": "Server is already dormant" } |
get /vps/images
Gets a list of available operating system images for virtual servers.
Responses
Code | Description | ||||||||
---|---|---|---|---|---|---|---|---|---|
200 | Operating system image list application/json
Example{ "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
Gets a list of available virtual servers products.
Parameters
Name | Location | Description |
---|---|---|
period string | query |
Product period Possible values:
Defaults to |
Responses
Code | Description | ||||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
200 | Product list application/json
Example{ "VPSX16": { "name": "VPS 4", "description": "Virtual Server, VPS 4 [ 2 cores, 4GB RAM, 2T/month ]", "code": "VPSX16", "family": "VPS-16", "period": "on-demand", "specs": { "cores": 2, "ram": 4096, "bandwidth": 2048 } } } |
||||||||||||||||||||||
400 | Invalid period application/json
Example{ "error": "Invalid period; valid options are month, on-demand, quarter, year, all" } |
get /vps/disk-sizes
Gets a list of available disk sizes.
Responses
Code | Description | ||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|
200 | Disk size list application/json
Example{ "hdd": [ 10240, 20480 ], "ssd": [ 5120, 6144 ] } |
get /vps/zones
Gets a list of available zones (datacentres) for virtual servers.
Responses
Code | Description | ||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|
200 | Zone list application/json
Example{ "cam": { "name": "cam", "description": "Cambridge, UK", "parents": [ "uk" ] } } |
get /vps/hosts
Gets a list of available private cloud host servers.
Responses
Code | Description | ||||||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
200 | Private cloud host list application/json
Example{ "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
Gets a list of prices (in pence per month) for on-demand virtual server products, disk space (price per specified number of GB), and IPv4 addresses.
Responses
Code | Description | ||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
200 | Price list application/json
Example{ "disk": { "ssd": { "price": 9, "extent": 1 }, "hdd": { "price": 23, "extent": 10 } }, "ipv4": 230, "products": { "VPSX4": 518, "VPSX8": 805 } } |
get /vps/user-data
Gets a list of user data snippets for automated virtual server installation.
Responses
Code | Description | ||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|
200 | User data snippet list application/json
Example{ "user_data": { "12": { "name": "test1", "id": 12, "size": 129 } } } |
post /vps/user-data
Creates a new user data snippet.
Request Body JSON
Name | Description |
---|---|
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
Code | Description | ||||
---|---|---|---|---|---|
200 | User data snippet created |
||||
400 | Invalid parameters application/json
Example{ "error": "Missing parameter: name" } |
||||
403 | Not authorised to manage user data application/json
Example{ "error": "Not authorised" } |
||||
409 | User data already exists application/json
Example{ "error": "User data 'database-server' already exists" } |
get /vps/user-data/{id}
Returns the specified user data snippet.
Parameters
Name | Location | Description |
---|---|---|
id integer | path |
User data identifier |
Responses
Code | Description | ||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|
200 | User data snippet application/json
Example{ "id": 2513, "name": "web-server", "size": 38, "data": "#cloud-config\n\npackages:\n - apache2\n\n" } |
||||||||||
400 | Invalid parameters application/json
Example{ "error": "Invalid user data ID" } |
||||||||||
403 | Not authorised to manage user data application/json
Example{ "error": "Not authorised" } |
||||||||||
404 | User data snippet not found application/json
Example{ "error": "User data not found" } |
put /vps/user-data/{id}
Updates an existing user data snippet.
Request Body JSON
Name | Description |
---|---|
data string |
(Required) Snippet data |
Example
application/json
{ "data": "#cloud-config\n\npackages:\n - apache2\n\n" }
Responses
Code | Description | ||||
---|---|---|---|---|---|
200 | User data snippet updated |
||||
400 | Invalid parameters application/json
Example{ "error": "Missing parameter: data" } |
||||
403 | Not authorised to manage user data application/json
Example{ "error": "Not authorised" } |
delete /vps/user-data/{id}
Deletes a user data snippet.
Parameters
Name | Location | Description |
---|---|---|
id string | path |
User data identifier |
Responses
Code | Description | ||||
---|---|---|---|---|---|
200 | User data deleted |
||||
403 | Not authorised to manage user data application/json
Example{ "error": "Not authorised" } |
||||
404 | User data snippet not found application/json
Example{ "error": "User data not found" } |
get /queue/vps/{task}
Gets the status of an asynchronous request. This is used following a 202 response from a Provision Server request.
Parameters
Name | Location | Description |
---|---|---|
task integer | path |
Task identifier |
Responses
Code | Description | ||||
---|---|---|---|---|---|
303 | Async request complete The |
||||
500 | Async request failed The reason for failure will be given in the application/json
Example{ "error": "Error provisioning server" } |