components:
  securitySchemes:
    Bearer: {in: header, name: Authorization, type: apiKey}
info:
  contact: {email: support@mythic-beasts.com}
  description: "\nThis API enables provisioning and managing of servers in the Mythic\
    \ Beasts\nRaspberry Pi Cloud.  \n\nServers provisioned using this API use **on\
    \ demand** pricing.  They can be\ncreated and cancelled at any time, and you will\
    \ be charged on a per-second\nbasis. \n\nAll requests need to be authenticated\
    \ using a Bearer\ntoken obtained from our [auth service](auth).\n\nThe base URL\
    \ for this service is:\n\n*  **https://api.mythic-beasts.com/beta**\n\nThe endpoints\
    \ listed below should be appended to the above URL.\n\n\n"
  termsOfService: https://www.mythic-beasts.com/article/terms
  title: Raspberry PI Server Management API
  version: 0.2.0
openapi: 3.0.0
paths:
  /pi/images/{model}:
    get:
      description: '

        Gets a list of available operating system images for the specified model.


        '
      parameters:
      - description: Model identifier (`3` or `4`)
        in: path
        name: model
        required: true
        schema: {example: 3, type: integer}
      responses:
        '200':
          content:
            application/json:
              schema:
                additionalProperties: {description: OS image description (key is image
                    name), type: string}
                example: {raspian-buster: Raspbian Buster, raspian-jessie: Raspbian
                    Jessie}
                type: object
          description: 'Operating system image list


            '
        '400':
          content:
            application/json:
              schema:
                properties:
                  error: {description: A description of the error, example: Invalid
                      model, type: string}
                type: object
          description: Invalid model number
      summary: Get OS images
      tags: [Pi]
  /pi/models:
    get:
      description: Lists all available Raspberry Pi server models and their specs.
      parameters: []
      responses:
        '200':
          content:
            application/json:
              schema:
                example:
                  models:
                  - {cpu_speed: 1200, memory: 1024, model: 3, nic_speed: 100}
                  - {cpu_speed: 1500, memory: 4096, model: 4, nic_speed: 1000}
                properties:
                  models:
                    additionalProperties:
                      description: Model details (key will match model)
                      properties:
                        cpu_speed: {description: CPU speed (in MHz), type: integer}
                        memory: {description: Amount of RAM (in MB), type: integer}
                        model: {description: Raspberry Pi model, type: integer}
                        nic_speed: {description: NIC speed (in Mbps), type: integer}
                      type: object
                    type: object
                type: object
          description: List of server models and specs
        '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 server models and specs
      tags: [Pi]
  /pi/servers:
    get:
      description: Lists all Raspberry Pi servers associated with this account.
      parameters: []
      responses:
        '200':
          content:
            application/json:
              schema:
                example:
                  servers:
                    pi1: {cpu_speed: 1200, memory: 1024, model: 3}
                    pi2: {cpu_speed: 1500, memory: 4096, model: 4}
                properties:
                  servers:
                    additionalProperties:
                      description: Raspberry Pi server details
                      properties:
                        cpu_speed: {description: CPU speed (in MHz), type: integer}
                        memory: {description: Amount of RAM (in MB), type: integer}
                        model: {description: Raspberry Pi model, type: integer}
                      type: object
                    type: object
                type: object
          description: 'Server information


            An object with keys giving the name of all Raspberry Pi

            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: [Pi]
    post:
      description: 'Provisions a new Raspberry Pi cloud server with an

        automatically-generated service identifier.  DNS for the service will

        become available at `{identifier}.hostedpi.com`.  The spec of the new server

        will be the lowest available spec matching all of `model`, `memory`, and

        `cpu_speed`.


        This operation is performed asynchronously (see documentation for `202`

        response).


        The final response includes an SSH port which can be to make an SSH

        connection over IPv4 to `ssh.{identifier}.hostedpi.com`.

        SSH connections can be made directly over IPv6 on port 22 to

        `{identifier}.hostedpi.com` which will resolve to the server''s IPv6

        address.


        You can use the `wait_for_dns` parameter if you wish to SSH to the

        server by DNS name immediately after provisioning.

        '
      parameters: []
      requestBody:
        content:
          application/json:
            schema:
              properties:
                cpu_speed:
                  default: [see description]
                  description: CPU speed in MHz
                  example: 2000
                  format: int64
                  type: integer
                disk: {default: 10, description: 'Disk space size, in GB.  Must be
                    a multiple of 10', example: 20, format: int64, type: integer}
                memory:
                  default: [see description]
                  description: RAM size in MB
                  example: 8192
                  format: int64
                  type: integer
                model: {default: 3, description: Raspberry Pi model (3 or 4), example: 4,
                  format: int64, type: integer}
                os_image: {description: Operating system image, example: raspbian-buster,
                  type: string}
                ssh_key: {description: Public SSH key(s) to be added to /root/.ssh/authorized_keys
                    on server, example: ssh-rsa AAAAB.... user@example.com, type: string}
                wait_for_dns: {default: false, description: Whether to wait for DNS
                    records under hostedpi.com to become available before completing
                    provisioning., example: true, type: boolean}
      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 (which will be the same URL as the

            `POST` was sent to)


            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
                      model number, 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
        '503':
          content:
            application/json:
              schema:
                properties:
                  error: {description: A description of the error, example: We do
                      not have any servers of the specified type available, type: string}
                type: object
          description: Out of stock.  Returned if no servers with the required specification
            are available.
      summary: Provision server
      tags: [Pi]
  /pi/servers/{identifier}:
    delete:
      description: "Unprovisions a Raspberry Pi server.  The associated disk will\
        \ be\npermanently deleted.  \n\nOnly servers that were created using this\
        \ API can be unprovisioned\nusing this method.\n\n"
      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
        '409':
          content:
            application/json:
              schema:
                properties:
                  error: {description: A description of the error, example: Server
                      is not fully provisioned, type: string}
                type: object
          description: Server is not fully provisioned.  This error will be reported
            if this endpoint is used immediately after provisioning.  See documentation
            of the `202` response from a [Provision Server](#ep-post-serverspiserver)
            request for information on how to check provisioning status.
      summary: Unprovision server
      tags: [Pi]
    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:
                  boot_progress: {description: String indicating the status of the
                      current reboot operation., example: Waiting for initial DHCP,
                    type: string}
                  disk_size: {description: Size of disk in GB, example: '10.00', type: string}
                  initialized_keys: {description: Set to true if the server has an
                      SSH key installed, example: true, type: boolean}
                  ip: {description: IPv6 address for server, example: '2a00:1098:8:ffff::1',
                    type: string}
                  is_booting: {description: Indicates whether a reboot is in progress.,
                    example: true, type: boolean}
                  location: {description: Data centre in which server is located,
                    example: MER, type: string}
                  model: {description: Raspberry Pi model, example: 3, type: integer}
                  power: {description: Indicates whether server is powered on, example: true,
                    type: boolean}
                  ssh_port: {description: 'Port for accessing SSH via IPv4 relay.  Server
                      is accessible on ssh.{identifier}.hostedpi.com.', example: 5001,
                    type: integer}
                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
        '409':
          content:
            application/json:
              schema:
                properties:
                  error: {description: A description of the error, example: Server
                      is not fully provisioned, type: string}
                type: object
          description: Server is not fully provisioned.  This error will be reported
            if this endpoint is used immediately after provisioning.  See documentation
            of the `202` response from a [Provision Server](#ep-post-serverspiserver)
            request for information on how to check provisioning status.
      security:
      - Bearer: []
      summary: Get server information
      tags: [Pi]
    post:
      description: 'Provisions a new Raspberry Pi cloud server with a given unique

        service identifier.  DNS for the service will become available at

        `{identifier}.hostedpi.com`.  The spec of the new server will be the

        lowest available spec matching all of `model`, `memory`, and

        `cpu_speed`.


        This operation is performed asynchronously (see documentation for `202`

        response).


        The final response includes an SSH port which can be to make an SSH

        connection over IPv4 to `ssh.{identifier}.hostedpi.com`.

        SSH connections can be made directly over IPv6 on port 22 to

        `{identifier}.hostedpi.com` which will resolve to the server''s IPv6

        address.


        You can use the `wait_for_dns` parameter if you wish to SSH to the

        server by DNS name immediately after provisioning.


        If a server of the given name exists, a 400 error will be returned.


        '
      parameters:
      - description: A unique identifier for the server.  This will form part of the
          hostname for the server, and should consist only of alphanumerics and `-`.
        in: path
        name: identifier
        required: true
        schema: {type: string}
      requestBody:
        content:
          application/json:
            schema:
              properties:
                cpu_speed:
                  default: [see description]
                  description: CPU speed in MHz
                  example: 2000
                  format: int64
                  type: integer
                disk: {default: 10, description: 'Disk space size, in GB.  Must be
                    a multiple of 10', example: 20, format: int64, type: integer}
                memory:
                  default: [see description]
                  description: RAM size in MB
                  example: 8192
                  format: int64
                  type: integer
                model: {default: 3, description: Raspberry Pi model (3 or 4), example: 4,
                  format: int64, type: integer}
                os_image: {description: Operating system image, example: raspbian-buster,
                  type: string}
                ssh_key: {description: Public SSH key(s) to be added to /root/.ssh/authorized_keys
                    on server, example: ssh-rsa AAAAB.... user@example.com, type: string}
                wait_for_dns: {default: false, description: Whether to wait for DNS
                    records under hostedpi.com to become available before completing
                    provisioning., example: true, type: boolean}
      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 (which will be the same URL as the

            `POST` was sent to)


            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
                      model number, 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
        '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
        '503':
          content:
            application/json:
              schema:
                properties:
                  error: {description: A description of the error, example: We do
                      not have any servers of the specified type available, type: string}
                type: object
          description: Out of stock.  Returned if no servers with the required specification
            are available.
      summary: Provision server with specified identifier
      tags: [Pi]
  /pi/servers/{identifier}/power:
    put:
      description: Turn power on or off
      parameters:
      - description: Server identifier
        in: path
        name: identifier
        required: true
        schema: {type: string}
      requestBody:
        content:
          application/json:
            schema:
              properties:
                power: {description: 'Power status (true = on, false = off)', example: true,
                  required: true, type: boolean}
      responses:
        '200':
          content:
            application/json:
              schema:
                properties:
                  message: {description: Response message, example: Server powered
                      on, type: string}
                type: object
          description: Server power set
        '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
        '409':
          content:
            application/json:
              schema:
                properties:
                  error: {description: A description of the error, example: Server
                      is not fully provisioned, type: string}
                type: object
          description: Server is not fully provisioned.  This error will be reported
            if this endpoint is used immediately after provisioning.  See documentation
            of the `202` response from a [Provision Server](#ep-post-serverspiserver)
            request for information on how to check provisioning status.
      summary: Power on/off
      tags: [Pi]
  /pi/servers/{identifier}/reboot:
    post:
      description: '

        Physically reboots the server by removing then restoring power.


        This method returns as soon as the reboot has been initiated.

        Progress of the reboot can be monitored via the `boot_progress` and

        `is_booting` [status fields](#ep-get-serverspiserver).


        '
      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 power cycled
        '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
        '409':
          content:
            application/json:
              schema:
                properties:
                  error: {description: A description of the error, example: Reboot
                      in progress, type: string}
                type: object
          description: The server is already being rebooted, or the server is not
            fully provisioned.
      summary: Power cycle
      tags: [Pi]
  /pi/servers/{identifier}/ssh-key:
    get:
      parameters:
      - description: Server identifier
        in: path
        name: identifier
        required: true
        schema: {type: string}
      responses:
        '200':
          content:
            application/json:
              schema:
                properties:
                  ssh_key: {description: The contents of `/root/.ssh/authorized_keys`
                      on the server., example: ssh-rsa AAAAB.... user@example.com,
                    type: string}
                type: object
          description: SSH keys returned
        '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
        '409':
          content:
            application/json:
              schema:
                properties:
                  error: {description: A description of the error, example: Server
                      is not fully provisioned, type: string}
                type: object
          description: Server is not fully provisioned.  This error will be reported
            if this endpoint is used immediately after provisioning.  See documentation
            of the `202` response from a [Provision Server](#ep-post-serverspiserver)
            request for information on how to check provisioning status.
      summary: Get SSH keys
      tags: [Pi]
    put:
      parameters:
      - description: Unique identifier for server
        in: path
        name: identifier
        required: true
        schema: {type: string}
      requestBody:
        content:
          application/json:
            schema:
              properties:
                ssh_key: {description: Public SSH key(s). The value of this parameter
                    will replace the contents of /root/.ssh/authorized_keys on server,
                  example: ssh-rsa AAAAB.... user@example.com, required: true, type: string}
      responses:
        '200':
          content:
            application/json:
              schema:
                properties:
                  ssh_key: {description: The contents of `/root/.ssh/authorized_keys`
                      on the server., example: ssh-rsa AAAAB.... user@example.com,
                    type: string}
                type: object
          description: SSH keys updated
        '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
        '409':
          content:
            application/json:
              schema:
                properties:
                  error: {description: A description of the error, example: Server
                      is not fully provisioned, type: string}
                type: object
          description: Server is not fully provisioned.  This error will be reported
            if this endpoint is used immediately after provisioning.  See documentation
            of the `202` response from a [Provision Server](#ep-post-serverspiserver)
            request for information on how to check provisioning status.
      summary: Set SSH keys
      tags: [Pi]
  /queue/pi/{task}:
    get:
      description: '

        Gets the status of an asynchronous request.  This is used following a 202
        response from a [Provision Server](#ep-post-serverspiserver) 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: Get request status
      tags: [Pi]
servers:
- {url: 'https://api.mythic-beasts.com/beta'}
tags:
- {description: Raspberry Pi provisioning, name: Pi}
