components: securitySchemes: Bearer: {in: header, name: Authorization, type: apiKey} info: contact: {email: support@mythic-beasts.com} description: ' 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](auth). The base URL for this service is: * **https://api.mythic-beasts.com/beta** The endpoints listed below should be appended to the above URL. ' termsOfService: https://www.mythic-beasts.com/article/terms title: Virtual Server Management API version: 0.0.1 openapi: 3.0.0 paths: /queue/vps/{task}: get: description: ' Gets the status of an asynchronous request. This is used following a 202 response from a [Provision Server](#ep-post-vpsservers) request. ' parameters: - description: Task identifier in: path name: task required: true schema: {type: integer} responses: '303': {description: 'Async request complete The `Location` header will provide a URL with the response to the asynchronous request. '} '500': content: application/json: schema: properties: error: {description: A description of the error, example: Error provisioning server, type: string} type: object description: 'Async request failed The reason for failure will be given in the `error` field of the JSON body. ' summary: Request status tags: [VPS] /vps/disk-sizes: get: description: ' Gets a list of available disk sizes. ' parameters: [] responses: '200': content: application/json: schema: example: hdd: [10240, 20480] ssd: [5120, 6144] properties: hdd: {description: Available HDD sizes (in MB), type: array} hdd-private: {description: Available HDD sizes (in MB) for private cloud (only shown if you have a private cloud), type: array} ssd: {description: Available SSD sizes (in MB), type: array} ssd-private: {description: Available SSD sizes (in MB) for private cloud (only shown if you have a private cloud), type: array} type: object description: 'Disk size list ' summary: Disk sizes tags: [VPS] /vps/hosts: get: description: ' Gets a list of available private cloud host servers. ' parameters: [] responses: '200': content: application/json: schema: additionalProperties: description: Private cloud host details (key will match name) properties: cores: {description: Total Number of CPU cores, type: integer} disk: description: Total disk space properties: hdd: {description: Total HDD space (in MB), type: integer} ssd: {description: Total SSD space (in MB), type: integer} type: object free_disk: description: Free disk space properties: hdd: {description: Free HDD space (in MB), type: integer} ssd: {description: Free SSD space (in MB), type: integer} type: object free_ram: {description: Amount of free memory (in MB), type: integer} name: {description: Private cloud host name, type: string} ram: {description: Total amount of memory (in MB), type: integer} type: object example: priv-vds-host-1: cores: 8 disk: {hdd: 310984, ssd: 0} free_disk: {hdd: 280264, ssd: 0} free_ram: 12328 name: priv-vds-host-1 ram: 32768 type: object description: 'Private cloud host list ' summary: Private cloud hosts tags: [VPS] /vps/images: get: description: ' Gets a list of available operating system images for virtual servers. ' parameters: [] responses: '200': content: application/json: schema: additionalProperties: description: OS image details (key will match name) properties: description: {description: OS image description, type: string} name: {description: OS image name, type: string} type: object example: 01-cloudinit-debian-buster.raw.gz: {description: Debian Buster (10), name: 01-cloudinit-debian-buster.raw.gz} 03-cloudinit-ubuntu-focal.raw.gz: {description: Ubuntu Focal (20.04), name: 03-cloudinit-ubuntu-focal.raw.gz} type: object description: 'Operating system image list ' summary: OS images tags: [VPS] /vps/pricing: get: description: ' 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. ' parameters: [] responses: '200': content: application/json: schema: example: disk: hdd: {extent: 10, price: 23} ssd: {extent: 1, price: 9} ipv4: 230 products: {VPSX4: 518, VPSX8: 805} properties: hdd: description: HDD pricing properties: extent: {description: GB per unit of HDD space, type: integer} price: {description: Price (in pence for month) per unit of HDD space, type: integer} type: object ipv4: {description: Price (in pence per month) for one IPv4 address, type: integer} products: additionalProperties: {description: Price (in pence per month) of virtual server product corresponding to key, type: integer} description: Prices (in pence per month) of virtual server products (key is the product code) type: object ssd: description: SSD pricing properties: extent: {description: GB per unit of SSD space, type: integer} price: {description: Price (in pence for month) per unit of SSD space, type: integer} type: object type: object description: 'Price list ' summary: Pricing tags: [VPS] /vps/products: get: description: ' Gets a list of available virtual servers products. ' parameters: - description: '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 ' in: query name: period schema: {type: string} responses: '200': content: application/json: schema: additionalProperties: description: Product details (key will match code) properties: code: {description: Product code, type: string} description: {description: Product description, type: string} family: {description: Product family code, type: string} name: {description: Product name, type: string} period: {description: Product billing period, type: string} specs: description: Product specifications properties: bandwidth: {description: Bandwidth allowance (in GB), type: integer} cores: {description: Number of CPU cores, type: integer} ram: {description: Amount of RAM (in MB), type: integer} type: object type: object example: VPSX16: code: VPSX16 description: Virtual Server, VPS 4 [ 2 cores, 4GB RAM, 2T/month ] family: VPS-16 name: VPS 4 period: on-demand specs: {bandwidth: 2048, cores: 2, ram: 4096} type: object description: 'Product list ' '400': content: application/json: schema: properties: error: {description: A description of the error, example: 'Invalid period; valid options are month, on-demand, quarter, year, all', type: string} type: object description: Invalid period summary: Products tags: [VPS] /vps/servers: get: description: Lists all virtual servers associated with this account. parameters: [] responses: '200': content: application/json: schema: additionalProperties: description: Server information (key will match identifier) properties: dormant: {description: Whether the server is dormant, type: boolean} family: {description: Product family code, type: string} identifier: {description: Server identifier, type: string} name: {description: Friendly name for server, type: string} period: {description: Billing period, type: string} product: {description: Product code, type: string} type: object example: vps1: {dormant: false, family: VPS-4, identifier: vps1, name: web-server-01, period: on-demand, product: VPSX4} vps2: {dormant: false, family: VPS-16, identifier: vps2, name: database-server, period: on-demand, product: VPSX16} type: object description: '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. ' '403': content: application/json: schema: properties: error: {description: A description of the error, example: Not authorised, type: string} type: object description: Not authorised to access this API. security: - Bearer: [] summary: List servers tags: [VPS] post: description: 'Provisions a new virtual server with an autogenerated identifier. This operation is performed asynchronously (see documentation for `202` response). ' parameters: [] requestBody: content: application/json: schema: properties: admin_console: description: Admin console authentication properties: password: {default: null, description: Admin console password; password login will be disabled if unspecified, example: null, type: string} ssh_keys: {default: null, description: Admin console SSH key(s), example: ssh-rsa AAAAB.... user@example.com, type: string} type: object cache: default: none description: Host cache for disk IO enum: [none, writethrough, writeback] example: none type: string cpu_mode: default: performance description: CPU mode enum: [performance, compatibility] example: performance type: string disk_bus: default: virtio description: Virtual disk bus adapter type enum: [virtio, sata, scsi, ide] example: virtio type: string disk_size: {description: 'Disk size, in MB; valid values returned by [disk sizes endpoint](#ep-get-vpsdisk-sizes)', example: 20, format: int64, required: true, type: integer} disk_type: default: ssd description: Disk type enum: [ssd, hdd] example: hdd type: string extra_cores: {description: Number of CPU cores in addition to the ones provided by the base product (private cloud only), example: 4, type: integer} host_server: {default: null, description: 'Name of private cloud host server to provision on; refer to [hosts endpoint](#ep-get-vpshosts) for valid names', example: priv-vds-host-1, required: false, type: string} hostname: {default: '{identifier}.vs.mythic-beasts.com', description: Hostname the new server should be installed with, example: my-new-server.example.com, required: false, type: string} image: {default: null, description: 'Operating system image name; valid values from [images endpoint](#ep-get-vpsimages); if this is unspecified, no OS will be installed and server will be left powered off', example: 01-cloudinit-debian-buster.raw.gz, type: string} ipv4: {default: false, description: '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](#ep-get-vpspricing)', example: false, type: boolean} name: {default: null, description: Friendly name for server, example: web-server-01, required: false, type: string} net_device: default: virtio description: Virtual network device type enum: [virtio, e1000, rtl8139, ne2k_pci] example: virtio type: string product: {description: 'Virtual server product code; valid values from [products endpoint](#ep-get-vpsproducts)', example: VPSX16, required: true, type: string} set_forward_dns: {default: false, description: Whether to automatically add A/AAAA records for the server's IP addresses to the selected hostname, example: true, required: false, type: boolean} set_reverse_dns: {default: false, description: Whether to automatically set reverse DNS for the server's IP addresses to the selected hostname, example: true, required: false, type: boolean} ssh_keys: {default: null, description: Public SSH key(s) to be added to `/root/.ssh/authorized_keys` on server, example: ssh-rsa AAAAB.... user@example.com, type: string} tablet: {default: true, description: Tablet mode for VNC mouse pointer, example: false, type: boolean} user_data: {default: null, description: 'Stored user data ID or name from [user data endpoint](#ep-get-vpsuser-data)', example: 2513, type: string} user_data_string: {default: null, description: User data (as a literal string), example: "#cloud-config\n\npackages:\n - apache2\n\n", type: string} vnc: description: VNC settings properties: mode: default: disabled description: VNC mode enum: [local, remote, disabled] example: local type: string password: {default: null, description: VNC password; auto-generated if unspecified, example: null, type: string} type: object zone: {default: any, description: 'Zone (datacentre) code; valid values from [zones endpoint](#ep-get-vpszones)', example: cam, type: string} responses: '202': {description: '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': content: application/json: schema: properties: error: {description: A description of the error, example: 'Invalid parameter disk_type: must be one of ssd, hdd', type: string} type: object description: Invalid parameters '403': content: application/json: schema: properties: error: {description: A description of the error, example: Not authorised, type: string} type: object description: Not authorised to provision server or insufficient on-demand service limit '409': content: application/json: schema: properties: error: {description: A description of the error, example: Server name already exists, type: string} type: object description: Server name already exists security: - Bearer: [] summary: Provision server tags: [VPS] /vps/servers/{identifier}: delete: description: 'Unprovisions a virtual server. The associated disk will be permanently deleted. Only on-demand servers can be unprovisioned using this method. ' parameters: - description: Unique identifier for server in: path name: identifier required: true schema: {type: string} responses: '200': {description: Server deleted} '403': content: application/json: schema: properties: error: {description: A description of the error, example: Not authorised, type: string} type: object description: Not authorised to access server or server does not exist summary: Unprovision server tags: [VPS] get: description: ' Returns information about the specified server. ' parameters: - description: The server identifier in: path name: identifier required: true schema: {type: string} responses: '200': content: application/json: schema: properties: admin_console: properties: hostname: {description: Admin console hostname, example: admin.vps01.vs.mythic-beasts.com, type: string} username: {description: Admin console username, example: vps01, type: string} type: object boot_device: {description: Boot device, example: hd, type: string} cache: {description: Host cache for disk IO, example: none, type: string} cpu_mode: {description: CPU mode, example: performance, type: string} disk_bus: {description: Disk bus device type, example: virtio, type: string} dormant: {description: Whether the server is dormant, example: false, type: boolean} family: {description: Product family code, example: VPS-8, type: string} host_server: {description: Host server name, example: vds-cam-i, type: string} identifier: {description: Server identifier, example: c10524v123, type: string} ipv4: description: List of IPv4 addresses example: [93.93.131.39] type: array ipv6: description: List of IPv6 addresses example: ['2a00:1098:0:86:1000:6a:0:1'] type: array iso_image: {description: ISO image currently in virtual CD drive, example: automated-install-config, type: string} macs: description: List of MAC addresses example: ['54:54:00:de:32:99'] type: array name: {description: Friendly server name, example: web-server-01, type: string} net_device: {description: Virtual network device type, example: virtio, type: string} period: {description: Billing period, example: on-demand, type: string} price: {description: Price of server (pence per billing period), example: 1018, type: float} product: {description: Product code, example: VPSX8, type: string} specs: properties: cores: {description: Number of virtual CPU cores, example: 2, type: integer} disk_size: {description: Disk size in MB, example: 10240, type: integer} disk_type: {description: Disk type, example: ssd, type: string} extra_cores: {description: Number of CPU cores in addition to the ones provided by the base product (private cloud only), example: 4, type: integer} ram: {description: RAM size in MB, example: 2048, type: integer} type: object ssh_proxy: properties: hostname: {description: SSH proxy hostname (for IPv4 access to IPv6-only servers), example: admin.vps01.vs.mythic-beasts.com, type: string} port: {description: SSH proxy port, example: 10046, type: integer} type: object status: {description: Server status, example: running, type: string} tablet: {description: Tablet mode for VNC mouse pointer, example: true, type: boolean} upgrade_specs: description: For non-on-demand servers, this section will be present if there are pending upgrades and will indicate the specs post-upgrade properties: cores: {description: Number of virtual CPU cores (only if spec upgrade is pending), example: 4, type: integer} disk_size: {description: Disk size in MB (only if disk upgrade is pending), example: 20480, type: integer} disk_type: {description: Disk type (only if disk upgrade is pending), example: ssd, type: string} ram: {description: RAM size in MB (only if spec upgrade is pending), example: 16384, type: integer} type: object vnc: properties: display: {description: VNC display number, example: 146, type: integer} ipv4: {description: VNC IPv4 address, example: 46.235.224.236, type: string} ipv6: {description: VNC IPv6 address, example: '2a00:1098:0:86:1000::d', type: string} mode: {description: VNC mode, example: local, type: string} password: {description: VNC password, example: iyeew7Zo, type: string} port: {description: VNC port number, example: 6046, type: integer} type: object zone: properties: code: {description: Zone (datacentre) code, example: cam, type: string} name: {description: Zone (datacentre) name, example: 'Cambridge, UK', type: string} type: object type: object description: Server information '403': content: application/json: schema: properties: error: {description: A description of the error, example: Not authorised, type: string} type: object description: Not authorised to access server or server does not exist security: - Bearer: [] summary: Server information tags: [VPS] patch: description: 'Updates VNC and admin console settings, server name, and server spec. ' parameters: - description: Unique identifier for server in: path name: identifier required: true schema: {type: string} requestBody: content: application/json: schema: properties: admin_console: description: Admin console settings properties: password: {description: Admin console password (set to `null` to disable), example: ed2Jae7k, required: false, type: string} ssh_keys: {description: SSH keys for admin console, example: ssh-rsa AAAAB.... user@example.com, required: false, type: string} type: object boot_device: description: Boot device; changing requires VPS to be powered off enum: [hd, cdrom, network] example: cdrom type: string cache: description: Host cache for disk IO; changing requires VPS to be powered off enum: [none, writeback, writethrough] example: none type: string cpu_mode: description: CPU mode; changing requires VPS to be powered off enum: [performance, compatibility] example: performance type: string disk_bus: default: virtio description: Virtual disk bus adapter type; changing requires VPS to be powered off enum: [virtio, sata, scsi, ide] example: virtio type: string iso_image: {description: 'ISO image (set to `null` to remove); changing requires VPS to be powered off; available images from [ISO images endpoint](#ep-get-vpsserversidentifieriso-images)', example: debian-10.10.0-amd64-netinst, type: string} name: {description: Friendly server name (set to `null` to remove), example: web-server-01, type: string} net_device: description: Virtual network device type; changing requires VPS to be powered off enum: [virtio, e1000, rtl8139, ne2k_pci] example: virtio type: string product: {description: 'Virtual server product code; valid values from [products endpoint](#ep-get-vpsproducts)', example: VPSX16, type: string} specs: description: Server spec properties: disk_size: {description: Disk size in MB, example: 20480, type: integer} extra_cores: {description: Number of CPU cores in addition to the ones provided by the base product (private cloud only), example: 4, type: integer} type: object tablet: {description: Tablet mode for VNC mouse pointer; changing requires VPS to be powered off, example: true, type: boolean} vnc: description: VNC settings properties: mode: description: VNC mode enum: [local, remote, disabled] example: local required: false type: string password: {description: VNC password, example: aeC8aeZ0, required: false, type: string} type: object responses: '200': content: application/json: schema: properties: message: {description: Response message, example: Operation successful, type: string} type: object description: Settings updated '400': content: application/json: schema: properties: error: {description: A description of the error, example: 'Invalid parameter admin_console.password: Password must be at least 8 characters long.', type: string} type: object description: Bad request '403': content: application/json: schema: properties: error: {description: A description of the error, example: Not authorised, type: string} type: object description: Not authorised to access server or server does not exist summary: Update server settings tags: [VPS] post: description: '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: - description: '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. ' in: path name: identifier required: true schema: {type: string} requestBody: content: application/json: schema: properties: admin_console: description: Admin console authentication properties: password: {default: null, description: Admin console password; password login will be disabled if unspecified, example: null, type: string} ssh_keys: {default: null, description: Admin console SSH key(s), example: ssh-rsa AAAAB.... user@example.com, type: string} type: object cache: default: none description: Host cache for disk IO enum: [none, writethrough, writeback] example: none type: string cpu_mode: default: performance description: CPU mode enum: [performance, compatibility] example: performance type: string disk_bus: default: virtio description: Virtual disk bus adapter type enum: [virtio, sata, scsi, ide] example: virtio type: string disk_size: {description: 'Disk size, in MB; valid values returned by [disk sizes endpoint](#ep-get-vpsdisk-sizes)', example: 20, format: int64, required: true, type: integer} disk_type: default: ssd description: Disk type enum: [ssd, hdd] example: hdd type: string extra_cores: {description: Number of CPU cores in addition to the ones provided by the base product (private cloud only), example: 4, type: integer} host_server: {default: null, description: 'Name of private cloud host server to provision on; refer to [hosts endpoint](#ep-get-vpshosts) for valid names', example: priv-vds-host-1, required: false, type: string} hostname: {default: '{identifier}.vs.mythic-beasts.com', description: Hostname the new server should be installed with, example: my-new-server.example.com, required: false, type: string} image: {default: null, description: 'Operating system image name; valid values from [images endpoint](#ep-get-vpsimages); if this is unspecified, no OS will be installed and server will be left powered off', example: 01-cloudinit-debian-buster.raw.gz, type: string} ipv4: {default: false, description: '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](#ep-get-vpspricing)', example: false, type: boolean} name: {default: null, description: Friendly name for server, example: web-server-01, required: false, type: string} net_device: default: virtio description: Virtual network device type enum: [virtio, e1000, rtl8139, ne2k_pci] example: virtio type: string product: {description: 'Virtual server product code; valid values from [products endpoint](#ep-get-vpsproducts)', example: VPSX16, required: true, type: string} set_forward_dns: {default: false, description: Whether to automatically add A/AAAA records for the server's IP addresses to the selected hostname, example: true, required: false, type: boolean} set_reverse_dns: {default: false, description: Whether to automatically set reverse DNS for the server's IP addresses to the selected hostname, example: true, required: false, type: boolean} ssh_keys: {default: null, description: Public SSH key(s) to be added to `/root/.ssh/authorized_keys` on server, example: ssh-rsa AAAAB.... user@example.com, type: string} tablet: {default: true, description: Tablet mode for VNC mouse pointer, example: false, type: boolean} user_data: {default: null, description: 'Stored user data ID or name from [user data endpoint](#ep-get-vpsuser-data)', example: 2513, type: string} user_data_string: {default: null, description: User data (as a literal string), example: "#cloud-config\n\npackages:\n - apache2\n\n", type: string} vnc: description: VNC settings properties: mode: default: disabled description: VNC mode enum: [local, remote, disabled] example: local type: string password: {default: null, description: VNC password; auto-generated if unspecified, example: null, type: string} type: object zone: {default: any, description: 'Zone (datacentre) code; valid values from [zones endpoint](#ep-get-vpszones)', example: cam, type: string} responses: '202': {description: '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': content: application/json: schema: properties: error: {description: A description of the error, example: 'Invalid parameter disk_type: must be one of ssd, hdd', type: string} type: object description: Invalid parameters '403': content: application/json: schema: properties: error: {description: A description of the error, example: Not authorised, type: string} type: object description: Not authorised to provision server or insufficient on-demand service limit '409': content: application/json: schema: properties: error: {description: A description of the error, example: Server name already exists, type: string} type: object description: Server name already exists security: - Bearer: [] summary: Provision server with specified identifier tags: [VPS] /vps/servers/{identifier}/console-output: get: description: Get server console output. parameters: - description: Server identifier in: path name: identifier required: true schema: {type: string} - description: Line limit (maximum number of lines of output to return; default 100, maximum 1000) example: 200 in: query name: limit required: false schema: {type: integer} responses: '200': content: application/json: schema: properties: console_output: {description: Console output, example: '20210223T125726: Debian GNU/Linux 10 apitest01.vs.mythic-beasts.com ttyS0 20210223T125727: avfapi1 login: ', type: string} limit: {description: Line limit, example: 2, type: integer} description: Console output (as a single string) '400': content: application/json: schema: properties: error: {description: A description of the error, example: Invalid limit (must be numeric), type: string} type: object description: Bad request '403': content: application/json: schema: properties: error: {description: A description of the error, example: Not authorised, type: string} type: object description: Not authorised to access server or server does not exist summary: Console output tags: [VPS] /vps/servers/{identifier}/dormant: put: description: ' Decommissions server but retains storage and IP addresses, or makes the server active again. ' parameters: - description: Server identifier in: path name: identifier required: true schema: {type: string} requestBody: content: application/json: schema: properties: dormant: {description: 'Whether to make server dormant (true) or re-activate (false, and specify product)', example: false, required: true, type: boolean} product: {description: 'Product code (required when re-activating server); valid values from [products endpoint](#ep-get-vpsproducts)', example: VPSX4, type: string} responses: '200': content: application/json: schema: properties: message: {description: Response message, example: Operation successful, type: string} type: object description: Server made dormant '400': content: application/json: schema: properties: error: {description: A description of the error, example: Server is already dormant, type: string} type: object description: Invalid state summary: Make dormant or re-activate tags: [VPS] /vps/servers/{identifier}/iso-images: get: description: 'Lists available ISO images for this server. These can be used for manually installing an operating system. ' parameters: [] responses: '200': content: application/json: schema: additionalProperties: description: ISO image details (key will match name) properties: description: {description: ISO image description, type: string} name: {description: ISO image name, type: string} type: object example: debian-10.10.0-amd64-netinst: {description: Debian Buster (10), name: debian-10.10.0-amd64-netinst} debian-11.0.0-amd64-netinst: {description: Debian Bullseye (11), name: debian-11.0.0-amd64-netinst} type: object description: List of ISO images summary: List ISO images tags: [VPS] /vps/servers/{identifier}/power: put: description: '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: - description: Server identifier in: path name: identifier required: true schema: {type: string} requestBody: content: application/json: schema: properties: power: description: Power status enum: [power-on, power-off, shutdown] example: shutdown required: true type: string responses: '200': content: application/json: schema: properties: message: {description: Response message, example: Operation successful, type: string} type: object description: Server powered on '400': content: application/json: schema: properties: error: {description: A description of the error, example: 'Missing parameter: power', type: string} type: object description: Bad request '403': content: application/json: schema: properties: error: {description: A description of the error, example: Not authorised, type: string} type: object description: Not authorised to access server or server does not exist summary: Power on/off tags: [VPS] /vps/servers/{identifier}/reboot: post: description: '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: - description: Server identifier in: path name: identifier required: true schema: {type: string} responses: '200': content: application/json: schema: properties: message: {description: Response message, example: Operation successful, type: string} type: object description: Server rebooted '403': content: application/json: schema: properties: error: {description: A description of the error, example: Not authorised, type: string} type: object description: Not authorised to access server or server does not exist summary: Reboot tags: [VPS] /vps/servers/{identifier}/upgrade-disk: post: description: 'For non-on-demand servers, apply a pending disk upgrade. ' parameters: - description: Server identifier in: path name: identifier required: true schema: {type: string} responses: '200': content: application/json: schema: properties: message: {description: Response message, example: Operation successful, type: string} type: object description: Disk upgraded '400': content: application/json: schema: properties: error: {description: A description of the error, example: No disk upgrade pending, type: string} type: object description: Bad request '403': content: application/json: schema: properties: error: {description: A description of the error, example: Not authorised, type: string} type: object description: Not authorised to access server or server does not exist summary: Apply pending disk upgrade tags: [VPS] /vps/user-data: get: description: ' Gets a list of user data snippets for automated virtual server installation. ' parameters: [] responses: '200': content: application/json: schema: additionalProperties: description: User data details (key will match identifier) properties: id: {description: User data identifier, type: string} name: {description: User data name, type: string} size: {description: User data size (in bytes), type: integer} type: object example: user_data: 12: {id: 12, name: test1, size: 129} type: object description: 'User data snippet list ' summary: List user data tags: [VPS] post: description: ' Creates a new user data snippet. ' parameters: [] requestBody: content: application/json: schema: properties: data: {description: Snippet data, example: "#cloud-config\n\npackages:\n\ \ - apache2\n\n", required: true, type: string} name: {description: Snippet name, example: web-server, required: true, type: string} responses: '200': {description: User data snippet created} '400': content: application/json: schema: properties: error: {description: A description of the error, example: 'Missing parameter: name', type: string} type: object description: Invalid parameters '403': content: application/json: schema: properties: error: {description: A description of the error, example: Not authorised, type: string} type: object description: Not authorised to manage user data '409': content: application/json: schema: properties: error: {description: A description of the error, example: User data 'database-server' already exists, type: string} type: object description: User data already exists summary: Create user data tags: [VPS] /vps/user-data/{id}: delete: description: 'Deletes a user data snippet. ' parameters: - description: User data identifier in: path name: id required: true schema: {type: string} responses: '200': {description: User data deleted} '403': content: application/json: schema: properties: error: {description: A description of the error, example: Not authorised, type: string} type: object description: Not authorised to manage user data '404': content: application/json: schema: properties: error: {description: A description of the error, example: User data not found, type: string} type: object description: User data snippet not found summary: Delete user data tags: [VPS] get: description: ' Returns the specified user data snippet. ' parameters: - description: User data identifier in: path name: id required: true schema: {type: integer} responses: '200': content: application/json: schema: properties: data: {description: User data snippet, example: "#cloud-config\n\ \npackages:\n - apache2\n\n", type: string} id: {description: User data identifier, example: 2513, type: string} name: {description: User data name, example: web-server, type: string} size: {description: User data size (in bytes), example: 38, type: integer} type: object description: 'User data snippet ' '400': content: application/json: schema: properties: error: {description: A description of the error, example: Invalid user data ID, type: string} type: object description: Invalid parameters '403': content: application/json: schema: properties: error: {description: A description of the error, example: Not authorised, type: string} type: object description: Not authorised to manage user data '404': content: application/json: schema: properties: error: {description: A description of the error, example: User data not found, type: string} type: object description: User data snippet not found summary: Show user data tags: [VPS] put: description: ' Updates an existing user data snippet. ' parameters: [] requestBody: content: application/json: schema: properties: data: {description: Snippet data, example: "#cloud-config\n\npackages:\n\ \ - apache2\n\n", required: true, type: string} responses: '200': {description: User data snippet updated} '400': content: application/json: schema: properties: error: {description: A description of the error, example: 'Missing parameter: data', type: string} type: object description: Invalid parameters '403': content: application/json: schema: properties: error: {description: A description of the error, example: Not authorised, type: string} type: object description: Not authorised to manage user data summary: Update user data tags: [VPS] /vps/zones: get: description: ' Gets a list of available zones (datacentres) for virtual servers. ' parameters: [] responses: '200': content: application/json: schema: additionalProperties: description: Zone details (key will match name) properties: description: {description: Zone description, type: string} name: {description: Zone name, type: string} parents: {description: List of parent zone names, type: array} type: object example: cam: description: Cambridge, UK name: cam parents: [uk] type: object description: 'Zone list ' summary: Zones tags: [VPS] servers: - {url: 'https://api.mythic-beasts.com/beta'} tags: - {description: Virtual server provisioning, name: VPS}