Virtual Server Provisioning API

get /vps/servers

https://api.mythic-beasts.com/beta/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

Name	Description
* object	Server information (key will match identifier)
identifier string	Server identifier
product string	Product code
family string	Product family code
period string	Billing period
name string	Friendly name for server
dormant boolean	Whether the server is dormant

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

Name	Description
error string	A description of the error

Example

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

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: `None`
host_server string	(Optional) Name of private cloud host server to provision on; refer to hosts endpoint for valid names Default: `None`
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)
extra_ram integer	(Optional) Amount of RAM (in MB, must be a multiple of 1024) in addition to the RAM 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: `None`
user_data string	(Optional) Stored user data ID or name from user data endpoint Default: `None`
user_data_string string	(Optional) User data (as a literal string) Default: `None`
ssh_keys string	(Optional) Public SSH key(s) to be added to `/root/.ssh/authorized_keys` on server Default: `None`
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: `None`
admin_console object	(Optional) Admin console authentication
password string	(Optional) Admin console password; password login will be disabled if unspecified Default: `None`
ssh_keys string	(Optional) Admin console SSH key(s) Default: `None`
cpu_mode string	(Optional) CPU mode Possible values: `performance` `compatibility` Default: `performance`
net_device string	(Optional) Virtual network device type Possible values: `virtio` `e1000` `rtl8139` `ne2k_pci` Default: `virtio`
disk_bus string	(Optional) Virtual disk bus adapter type Possible values: `virtio` `sata` `scsi` `ide` Default: `virtio`
tablet boolean	(Optional) Tablet mode for VNC mouse pointer Default: `True`

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,
    "extra_ram": 2048,
    "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",
    "disk_bus": "virtio",
    "tablet": false
}

Responses

Code Description

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

Name	Description
error string	A description of the error

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

Name	Description
error string	A description of the error

Example

{
    "error": "Not authorised"
}

409

Server name already exists

application/json

Name	Description
error string	A description of the error

Example

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

Name	Location	Description
identifier string	path	Server identifier

Responses

Code Description

200

Server information

application/json

Name	Description
identifier string	Server identifier
name string	Friendly server name
status string	Server status
host_server string	Host server name
zone object
code string	Zone (datacentre) code
name string	Zone (datacentre) name
product string	Product code
family string	Product family code
cpu_mode string	CPU mode
net_device string	Virtual network device type
disk_bus string	Disk bus device type
tablet boolean	Tablet mode for VNC mouse pointer
price float	Price of server (pence per billing period)
period string	Billing period
iso_image string	ISO image currently in virtual CD drive
dormant boolean	Whether the server is dormant
boot_device string	Boot device
ipv4 array	List of IPv4 addresses
ipv6 array	List of IPv6 addresses
specs object
disk_type string	Disk type
disk_size integer	Disk size in MB
cores integer	Number of virtual CPU cores
extra_cores integer	Number of CPU cores in addition to the ones provided by the base product (private cloud only)
extra_ram integer	Amount of RAM (in MB) in addition to the RAM provided by the base product (private cloud only)
ram integer	RAM size in MB
upgrade_specs object	For non-on-demand servers, this section will be present if there are pending upgrades and will indicate the specs post-upgrade
disk_type string	Disk type (only if disk upgrade is pending)
disk_size integer	Disk size in MB (only if disk upgrade is pending)
cores integer	Number of virtual CPU cores (only if spec upgrade is pending)
ram integer	RAM size in MB (only if spec upgrade is pending)
macs array	List of MAC addresses
admin_console object
username string	Admin console username
hostname string	Admin console hostname
ssh_proxy object
hostname string	SSH proxy hostname (for IPv4 access to IPv6-only servers)
port integer	SSH proxy port
vnc object
mode string	VNC mode
password string	VNC password
ipv4 string	VNC IPv4 address
ipv6 string	VNC IPv6 address
port integer	VNC port number
display integer	VNC display number

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",
    "tablet": true,
    "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,
        "extra_ram": 2048,
        "ram": 2048
    },
    "upgrade_specs": {
        "disk_type": "ssd",
        "disk_size": 20480,
        "cores": 4,
        "ram": 16384
    },
    "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

Name	Description
error string	A description of the error

Example

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

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: `None`
host_server string	(Optional) Name of private cloud host server to provision on; refer to hosts endpoint for valid names Default: `None`
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)
extra_ram integer	(Optional) Amount of RAM (in MB, must be a multiple of 1024) in addition to the RAM 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: `None`
user_data string	(Optional) Stored user data ID or name from user data endpoint Default: `None`
user_data_string string	(Optional) User data (as a literal string) Default: `None`
ssh_keys string	(Optional) Public SSH key(s) to be added to `/root/.ssh/authorized_keys` on server Default: `None`
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: `None`
admin_console object	(Optional) Admin console authentication
password string	(Optional) Admin console password; password login will be disabled if unspecified Default: `None`
ssh_keys string	(Optional) Admin console SSH key(s) Default: `None`
cpu_mode string	(Optional) CPU mode Possible values: `performance` `compatibility` Default: `performance`
net_device string	(Optional) Virtual network device type Possible values: `virtio` `e1000` `rtl8139` `ne2k_pci` Default: `virtio`
disk_bus string	(Optional) Virtual disk bus adapter type Possible values: `virtio` `sata` `scsi` `ide` Default: `virtio`
tablet boolean	(Optional) Tablet mode for VNC mouse pointer Default: `True`

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,
    "extra_ram": 2048,
    "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",
    "disk_bus": "virtio",
    "tablet": false
}

Responses

Code Description

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

Name	Description
error string	A description of the error

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

Name	Description
error string	A description of the error

Example

{
    "error": "Not authorised"
}

409

Server name already exists

application/json

Name	Description
error string	A description of the error

Example

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

Name	Location	Description
identifier string	path	Server identifier

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)
extra_ram integer	(Optional) Amount of RAM (in MB, must be a multiple of 1024) in addition to the RAM 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` `network`
iso_image string	(Optional) ISO image (set to `null` to remove); changing requires VPS to be powered off; available images from ISO images endpoint
cpu_mode string	(Optional) CPU mode; changing requires VPS to be powered off Possible values: `performance` `compatibility`
net_device string	(Optional) Virtual network device type; changing requires VPS to be powered off Possible values: `virtio` `e1000` `rtl8139` `ne2k_pci`
disk_bus string	(Optional) Virtual disk bus adapter type; changing requires VPS to be powered off Possible values: `virtio` `sata` `scsi` `ide` Default: `virtio`
tablet boolean	(Optional) Tablet mode for VNC mouse pointer; changing requires VPS to be powered off
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,
        "extra_ram": 2048
    },
    "name": "web-server-01",
    "boot_device": "cdrom",
    "iso_image": "debian-10.10.0-amd64-netinst",
    "cpu_mode": "performance",
    "net_device": "virtio",
    "disk_bus": "virtio",
    "tablet": true,
    "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

Name	Description
message string	Response message

Example

{
    "message": "Operation successful"
}

400

Bad request

application/json

Name	Description
error string	A description of the error

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

Name	Description
error string	A description of the error

Example

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

Name	Location	Description
identifier string	path	Server identifier

Responses

Code Description

200

Server deleted

403

Not authorised to access server or server does not exist

application/json

Name	Description
error string	A description of the error

Example

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

Code Description

200

List of ISO images

application/json

Name	Description
* object	ISO image details (key will match name)
name string	ISO image name
description string	ISO image description

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

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

Name	Location	Description
identifier string	path	Server identifier

Responses

Code Description

200

Server rebooted

application/json

Name	Description
message string	Response message

Example

{
    "message": "Operation successful"
}

403

Not authorised to access server or server does not exist

application/json

Name	Description
error string	A description of the error

Example

{
    "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. For non-on-demand servers, powering on will automatically apply any pending RAM and CPU upgrades.

Parameters

Name	Location	Description
identifier string	path	Server identifier

Request Body JSON

Name	Description
power string	(Required) Power status Possible values: `power-on` `power-off` `shutdown`

Example

application/json

{
    "power": "shutdown"
}

Responses

Code Description

200

Server powered on

application/json

Name	Description
message string	Response message

Example

{
    "message": "Operation successful"
}

400

Bad request

application/json

Name	Description
error string	A description of the error

Example

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

403

Not authorised to access server or server does not exist

application/json

Name	Description
error string	A description of the error

Example

{
    "error": "Not authorised"
}

post /vps/servers/{identifier}/upgrade-disk

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

For non-on-demand servers, apply a pending disk upgrade.

Parameters

Name	Location	Description
identifier string	path	Server identifier

Responses

Code Description

200

Disk upgraded

application/json

Name	Description
message string	Response message

Example

{
    "message": "Operation successful"
}

400

Bad request

application/json

Name	Description
error string	A description of the error

Example

{
    "error": "No disk upgrade pending"
}

403

Not authorised to access server or server does not exist

application/json

Name	Description
error string	A description of the error

Example

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

Name	Location	Description
identifier string	path	Server identifier
limit integer	query	(Optional) Line limit (maximum number of lines of output to return; maximum 1000) Default: `100`

Responses

Code Description

200

Console output (as a single string)

application/json

Name	Description
console_output string	Console output
limit integer	Line limit

Example

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

400

Bad request

application/json

Name	Description
error string	A description of the error

Example

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

403

Not authorised to access server or server does not exist

application/json

Name	Description
error string	A description of the error

Example

{
    "error": "Not authorised"
}

get /vps/servers/{identifier}/console

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

Get virtual console capabilities

Parameters

Name	Location	Description
identifier string	path	Server identifier

Responses

Code Description

200

Serial console capabilities

application/json

Name	Description
has_state boolean	Whether the console has a state websocket (will always be `false` for VPS consoles)
supports_baudrate boolean	Whether the console supports reading and setting baud rate (will always be `false` for VPS consoles)
supports_breaks boolean	Whether the console supports sending breaks (will always be `false` for VPS consoles)
supports_line_state boolean	Whether the console supports reading serial line state (will always be `false` for VPS consoles)

Example

{
    "has_state": false,
    "supports_baudrate": false,
    "supports_breaks": false,
    "supports_line_state": false
}

403

Not authorised to access server or server does not exist

application/json

Name	Description
error string	A description of the error

Example

{
    "error": "Not authorised"
}

get /vps/servers/{identifier}/console/log

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

Get server console output for virtual servers on new-style hosts.

Eventually, all hosts will become new-style and the console output endpoint, which currently redirects to this endpoint for new-style hosts, will become deprecated.

Parameters

Name	Location	Description
identifier string	path	Server identifier
limit integer	query	(Optional) Line limit (maximum number of lines of output to return; maximum 1000) Default: `100`
timestamps boolean	query	(Optional) Whether or not to include timestamps in the console output Default: `True`

Responses

Code Description

200

Console output (as a single string)

application/json

Name	Description
console_output string	Console output
limit integer	Line limit

Example

{
    "console_output": "2021-02-23 12:57:26: Debian GNU/Linux 10 apitest01.vs.mythic-beasts.com ttyS0\r2021-02-23 12:57:27: apitest01 login: ",
    "limit": 2
}

400

Bad request

application/json

Name	Description
error string	A description of the error

Example

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

403

Not authorised to access server or server does not exist

application/json

Name	Description
error string	A description of the error

Example

{
    "error": "Not authorised"
}

get /vps/servers/{identifier}/vnc

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

Return a URL to a websocket connected to the server's VNC console.

Will only work for servers on new-style hosts. All servers will be migrated in due course.

Parameters

Name	Location	Description
identifier string	path	Server identifier

Responses

Code Description

200

Websocket URL

application/json

Name	Description
url string	Websocket URL
expires string	Websocket URL expiry time
password string	VNC password

Example

{
    "url": "wss://vds-cam-xx.consoles.mythic-beasts.com/?token=9d45e1de1ef4f4d2eee2318549341ebedbd9530a63f4df9e01bc3f95be2603b4",
    "expires": "2025-03-26T11:23:54",
    "password": "f8sqNVp9"
}

403

Not authorised to access server or server does not exist

application/json

Name	Description
error string	A description of the error

Example

{
    "error": "Not authorised"
}

get /vps/servers/{identifier}/console/websocket

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

Returns a URL of a websocket attached to the virtual console of the server.

Will only work for servers on new-style hosts. All servers will be migrated in due course.

Parameters

Name	Location	Description
identifier string	path	Server identifier
type	query	(Optional) Websocket type (plain serial data, or wrapped in Telnet) Possible values: `serial` `telnet` Default: `serial`

Responses

Code Description

200

Websocket URL

application/json

Name	Description
url string	Websocket URL
expires string	Websocket URL expiry time

Example

{
    "url": "wss://vds-cam-xx.consoles.mythic-beasts.com/?token=fd7be1f1b03602fd30817bc05c7279e5341b1716e2b1b170ea953f1e0aaf278c",
    "expires": "2025-03-26T10:56:41"
}

403

Not authorised to access server or server does not exist

application/json

Name	Description
error string	A description of the error

Example

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

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

Name	Description
message string	Response message

Example

{
    "message": "Operation successful"
}

400

Invalid state

application/json

Name	Description
error string	A description of the error

Example

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

Code Description

200

Operating system image list

application/json

Name	Description
* object	OS image details (key will match name)
name string	OS image name
description string	OS image description

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

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

Gets a list of available virtual servers products.

Parameters

Name Location Description

period string

query

(Optional)

Product period

Possible values:

month for monthly-billed products
quarter for quarterly-billed products
year for yearly-billed products
on-demand for on-demand products
all to return everything

Defaults to on-demand, which returns the products that can be provisioned via this API

Responses

Code Description

200

Product list

application/json

Name	Description
* object	Product details (key will match code)
name string	Product name
description string	Product description
code string	Product code
family string	Product family code
period string	Product billing period
specs object	Product specifications
cores integer	Number of CPU cores
ram integer	Amount of RAM (in MB)
bandwidth integer	Bandwidth allowance (in GB)

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

Name	Description
error string	A description of the error

Example

{
    "error": "Invalid period; valid options are month, on-demand, quarter, year, all"
}

get /vps/disk-sizes

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

Gets a list of available disk sizes.

Responses

Code Description

200

Disk size list

application/json

Name	Description
hdd array	Available HDD sizes (in MB)
ssd array	Available SSD sizes (in MB)
hdd-private array	Available HDD sizes (in MB) for private cloud (only shown if you have a private cloud)
ssd-private array	Available SSD sizes (in MB) for private cloud (only shown if you have a private cloud)

Example

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

Code Description

200

Zone list

application/json

Name	Description
* object	Zone details (key will match name)
name string	Zone name
description string	Zone description
parents array	List of parent zone names

Example

{
    "cam": {
        "name": "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

Code Description

200

Private cloud host list

application/json

Name	Description
* object	Private cloud host details (key will match name)
name string	Private cloud host name
cores integer	Total Number of CPU cores
ram integer	Total amount of memory (in MB)
disk object	Total disk space
ssd integer	Total SSD space (in MB)
hdd integer	Total HDD space (in MB)
free_ram integer	Amount of free memory (in MB)
free_disk object	Free disk space
ssd integer	Free SSD space (in MB)
hdd integer	Free HDD space (in MB)

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

https://api.mythic-beasts.com/beta/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

Name	Description
ssd object	SSD pricing
price integer	Price (in pence for month) per unit of SSD space
extent integer	GB per unit of SSD space
hdd object	HDD pricing
price integer	Price (in pence for month) per unit of HDD space
extent integer	GB per unit of HDD space
ipv4 integer	Price (in pence per month) for one IPv4 address
products object	Prices (in pence per month) of virtual server products (key is the product code)
* integer	Price (in pence per month) of virtual server product corresponding to key

Example

{
    "disk": {
        "ssd": {
            "price": 9,
            "extent": 1
        },
        "hdd": {
            "price": 23,
            "extent": 10
        }
    },
    "ipv4": 230,
    "products": {
        "VPSX4": 518,
        "VPSX8": 805
    }
}

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

Code Description

200

User data snippet list

application/json

Name	Description
* object	User data details (key will match identifier)
id string	User data identifier
name string	User data name
size integer	User data size (in bytes)

Example

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

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

Name	Description
error string	A description of the error

Example

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

403

Not authorised to manage user data

application/json

Name	Description
error string	A description of the error

Example

{
    "error": "Not authorised"
}

409

User data already exists

application/json

Name	Description
error string	A description of the error

Example

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

Name	Location	Description
id integer	path	User data identifier

Responses

Code Description

200

User data snippet

application/json

Name	Description
id string	User data identifier
name string	User data name
size integer	User data size (in bytes)
data string	User data snippet

Example

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

400

Invalid parameters

application/json

Name	Description
error string	A description of the error

Example

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

403

Not authorised to manage user data

application/json

Name	Description
error string	A description of the error

Example

{
    "error": "Not authorised"
}

404

User data snippet not found

application/json

Name	Description
error string	A description of the error

Example

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

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

Name	Description
error string	A description of the error

Example

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

403

Not authorised to manage user data

application/json

Name	Description
error string	A description of the error

Example

{
    "error": "Not authorised"
}

delete /vps/user-data/{id}

https://api.mythic-beasts.com/beta/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

Name	Description
error string	A description of the error

Example

{
    "error": "Not authorised"
}

404

User data snippet not found

application/json

Name	Description
error string	A description of the error

Example

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

Name	Location	Description
task integer	path	Task identifier

Responses

Code Description

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

Name	Description
error string	A description of the error

Example

{
    "error": "Error provisioning server"
}

Virtual Server Provisioning API

Endpoints

get /vps/servers

Responses

Example

Example

post /vps/servers

Parameters

Request Body JSON

Example

Responses

Example

Example

Example

get /vps/servers/{identifier}

Parameters

Responses

Example

Example

post /vps/servers/{identifier}

Parameters

Request Body JSON

Example

Responses

Example

Example

Example

patch /vps/servers/{identifier}

Parameters

Request Body JSON

Example

Responses

Example

Example

Example

delete /vps/servers/{identifier}

Parameters

Responses

Example

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

Responses

Example

post /vps/servers/{identifier}/reboot

Parameters

Responses

Example

Example

put /vps/servers/{identifier}/power

Parameters

Request Body JSON

Example

Responses

Example

Example

Example

post /vps/servers/{identifier}/upgrade-disk

Parameters

Responses

Example

Example

Example

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

Parameters

Responses

Example

Example

Example

get /vps/servers/{identifier}/console

Parameters

Responses

Example

Example

get /vps/servers/{identifier}/console/log

Parameters

Responses

Example

Example

Example

get /vps/servers/{identifier}/vnc

Parameters