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:
                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
                extra_ram:
                  description: Amount of RAM (in MB, must be a multiple of 1024) in
                    addition to the RAM provided by the base product (private cloud
                    only)
                  example: 2048
                  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
                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: Server identifier
        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: Server identifier
        in: path
        name: identifier
        required: true
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                properties:
                  boot_device:
                    description: Boot device
                    example: hd
                    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
                      extra_ram:
                        description: Amount of RAM (in MB) in addition to the RAM
                          provided by the base product (private cloud only)
                        example: 2048
                        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
                  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: Server identifier
        in: path
        name: identifier
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              properties:
                boot_device:
                  description: Boot device; changing requires VPS to be powered off
                  enum:
                  - hd
                  - cdrom
                  - network
                  example: cdrom
                  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
                    extra_ram:
                      description: Amount of RAM (in MB, must be a multiple of 1024)
                        in addition to the RAM provided by the base product (private
                        cloud only)
                      example: 2048
                      type: integer
                  type: object
                tablet:
                  description: Tablet mode for VNC mouse pointer; changing requires
                    VPS to be powered off
                  example: true
                  type: boolean
      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: /boot_device: Not in enum list: hd,
                      cdrom, network.'
                    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:
                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
                extra_ram:
                  description: Amount of RAM (in MB, must be a multiple of 1024) in
                    addition to the RAM provided by the base product (private cloud
                    only)
                  example: 2048
                  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
                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:
    get:
      description: Get virtual console capabilities
      parameters:
      - description: Server identifier
        in: path
        name: identifier
        required: true
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                properties:
                  has_state:
                    description: 'Whether the console has a state websocket

                      (will always be `false` for VPS consoles)

                      '
                    example: false
                    type: boolean
                  supports_baudrate:
                    description: 'Whether the console supports reading and setting
                      baud

                      rate (will always be `false` for VPS consoles)

                      '
                    example: false
                    type: boolean
                  supports_breaks:
                    description: 'Whether the console supports sending breaks (will

                      always be `false` for VPS consoles)

                      '
                    example: false
                    type: boolean
                  supports_line_state:
                    description: 'Whether the console supports reading serial line
                      state

                      (will always be `false` for VPS consoles)

                      '
                    example: false
                    type: boolean
          description: Serial console capabilities
        '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 capabilities
      tags:
      - VPS
  /vps/servers/{identifier}/console/log:
    get:
      description: '

        Get server console output.


        '
      parameters:
      - description: Server identifier
        in: path
        name: identifier
        required: true
        schema:
          type: string
      - default: 100
        description: Line limit (maximum number of lines of output to return; maximum
          1000)
        example: 200
        in: query
        name: limit
        required: false
        schema:
          type: integer
      - default: true
        description: Whether or not to include timestamps in the console output
        example: false
        in: query
        name: timestamps
        required: false
        schema:
          type: boolean
      responses:
        '200':
          content:
            application/json:
              schema:
                properties:
                  console_output:
                    description: Console output
                    example: "2021-02-23 12:57:26: Debian GNU/Linux 10 apitest01.vs.mythic-beasts.com\
                      \ ttyS0\r2021-02-23 12:57:27: apitest01 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}/console/websocket:
    get:
      description: '

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

        server.


        '
      parameters:
      - description: Server identifier
        in: path
        name: identifier
        required: true
        schema:
          type: string
      - default: serial
        description: Websocket type (plain serial data, or wrapped in Telnet)
        example: telnet
        in: query
        name: type
        required: false
        schema:
          enum:
          - serial
          - telnet
      responses:
        '200':
          content:
            application/json:
              schema:
                properties:
                  expires:
                    description: Websocket URL expiry time
                    example: '2025-03-26T10:56:41'
                    type: string
                  url:
                    description: Websocket URL
                    example: wss://vds-cam-xx.consoles.mythic-beasts.com/?token=fd7be1f1b03602fd30817bc05c7279e5341b1716e2b1b170ea953f1e0aaf278c
                    type: string
          description: Websocket URL
        '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 access websocket
      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/servers/{identifier}/vnc:
    get:
      description: '

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


        '
      parameters:
      - description: Server identifier
        in: path
        name: identifier
        required: true
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                properties:
                  expires:
                    description: Websocket URL expiry time
                    example: '2025-03-26T11:23:54'
                    type: string
                  url:
                    description: Websocket URL
                    example: wss://vds-cam-xx.consoles.mythic-beasts.com/?token=9d45e1de1ef4f4d2eee2318549341ebedbd9530a63f4df9e01bc3f95be2603b4
                    type: string
          description: Websocket URL
        '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: VNC websocket
      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
