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

NameDescription
* 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

NameDescription
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

NameLocationDescription
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

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)

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: 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"
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
cache string

(Optional) Host cache for disk IO

Possible values:
  • "none"
  • "writethrough"
  • "writeback"
Default: "none"
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,
    "cache": "none"
}

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

NameDescription
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

NameDescription
error string

A description of the error

Example
{
    "error": "Not authorised"
}
409

Server name already exists

application/json

NameDescription
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

NameLocationDescription
identifier string path

The server identifier

Responses

CodeDescription
200

Server information

application/json

NameDescription
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

cache string

Host cache for disk IO

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,
    "cache": "none",
    "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

NameDescription
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

NameLocationDescription
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

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)

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: 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"
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
cache string

(Optional) Host cache for disk IO

Possible values:
  • "none"
  • "writethrough"
  • "writeback"
Default: "none"
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,
    "cache": "none"
}

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

NameDescription
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

NameDescription
error string

A description of the error

Example
{
    "error": "Not authorised"
}
409

Server name already exists

application/json

NameDescription
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

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)

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

cache string

(Optional) Host cache for disk IO; changing requires VPS to be powered off

Possible values:
  • "none"
  • "writeback"
  • "writethrough"
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,
    "cache": "none",
    "admin_console": {
        "ssh_keys": "ssh-rsa AAAAB.... user@example.com",
        "password": "ed2Jae7k"
    },
    "vnc": {
        "mode": "local",
        "password": "aeC8aeZ0"
    }
}

Responses

CodeDescription
200

Settings updated

application/json

NameDescription
message string

Response message

Example
{
    "message": "Operation successful"
}
400

Bad request

application/json

NameDescription
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

NameDescription
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

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

NameDescription
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

CodeDescription
200

List of ISO images

application/json

NameDescription
* 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

NameLocationDescription
identifier string path

Server identifier

Responses

CodeDescription
200

Server rebooted

application/json

NameDescription
message string

Response message

Example
{
    "message": "Operation successful"
}
403

Not authorised to access server or server does not exist

application/json

NameDescription
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

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 powered on

application/json

NameDescription
message string

Response message

Example
{
    "message": "Operation successful"
}
400

Bad request

application/json

NameDescription
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

NameDescription
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

NameLocationDescription
identifier string path

Server identifier

Responses

CodeDescription
200

Disk upgraded

application/json

NameDescription
message string

Response message

Example
{
    "message": "Operation successful"
}
400

Bad request

application/json

NameDescription
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

NameDescription
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

NameLocationDescription
identifier string path

Server identifier

limit integer query

Line limit (maximum number of lines of output to return; default 100, maximum 1000)

Responses

CodeDescription
200

Console output (as a single string)

application/json

NameDescription
console_output string

Console output

limit integer

Line limit

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

NameDescription
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

NameDescription
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

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

NameDescription
message string

Response message

Example
{
    "message": "Operation successful"
}
400

Invalid state

application/json

NameDescription
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

CodeDescription
200

Operating system image list

application/json

NameDescription
* 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

NameLocationDescription
period string query

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

CodeDescription
200

Product list

application/json

NameDescription
* 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

NameDescription
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

CodeDescription
200

Disk size list

application/json

NameDescription
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

CodeDescription
200

Zone list

application/json

NameDescription
* 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

CodeDescription
200

Private cloud host list

application/json

NameDescription
* 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

CodeDescription
200

Price list

application/json

NameDescription
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

CodeDescription
200

User data snippet list

application/json

NameDescription
* 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

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

NameDescription
error string

A description of the error

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

Not authorised to manage user data

application/json

NameDescription
error string

A description of the error

Example
{
    "error": "Not authorised"
}
409

User data already exists

application/json

NameDescription
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

NameLocationDescription
id integer path

User data identifier

Responses

CodeDescription
200

User data snippet

application/json

NameDescription
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

NameDescription
error string

A description of the error

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

Not authorised to manage user data

application/json

NameDescription
error string

A description of the error

Example
{
    "error": "Not authorised"
}
404

User data snippet not found

application/json

NameDescription
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

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

NameDescription
error string

A description of the error

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

Not authorised to manage user data

application/json

NameDescription
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

NameLocationDescription
id string path

User data identifier

Responses

CodeDescription
200

User data deleted

403

Not authorised to manage user data

application/json

NameDescription
error string

A description of the error

Example
{
    "error": "Not authorised"
}
404

User data snippet not found

application/json

NameDescription
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

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

NameDescription
error string

A description of the error

Example
{
    "error": "Error provisioning server"
}