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 { "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
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 should consist only of alphanumerics and |
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 { "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}
Returns information about the specified server.
Parameters
Name | Location | Description |
---|---|---|
identifier string | path |
The server identifier |
Responses
Code | Description |
---|---|
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}
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 should consist only of alphanumerics and |
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 { "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}
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 { "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}
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 { "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 { "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 { "message": "Operation successful" } |
403 | Not authorised to access server or server does not exist application/json { "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 { "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
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) |
Responses
Code | Description |
---|---|
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
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 { "message": "Operation successful" } |
400 | Invalid state application/json { "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 { "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.
Responses
Code | Description |
---|---|
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
Gets a list of available disk sizes.
Responses
Code | Description |
---|---|
200 | Disk size list application/json { "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 { "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 { "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 virtual server products, disk space (price per specified number of MB), and IPv4.
Responses
Code | Description |
---|---|
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
Gets a list of user data snippets for automated virtual server installation.
Responses
Code | Description |
---|---|
200 | User data snippet list application/json { "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 { "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}
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 { "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}
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 { "error": "Missing parameter: data" } |
403 | Not authorised to manage user data application/json { "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 { "error": "Not authorised" } |
404 | User data snippet not found application/json { "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 { "error": "Error provisioning server" } |