Raspberry Pi Provisioning API

OpenAPI YAML

This API enables provisioning and managing of servers in the Mythic Beasts Raspberry Pi Cloud.

Servers provisioned using this API use on demand pricing. They can be created and cancelled at any time, and you will be charged on a per-second basis.

All requests need to be authenticated using a Bearer token obtained from our auth service.

The base URL for this service is:

  • https://api.mythic-beasts.com/beta

The endpoints listed below should be appended to the above URL.

Endpoints

get /pi/servers

https://api.mythic-beasts.com/beta/pi/servers

Lists all Raspberry Pi servers associated with this account.

Responses

CodeDescription
200

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.

application/json

NameDescription
servers object
* object

Raspberry Pi server details
model integer

Raspberry Pi model
memory integer

Amount of RAM (in MB)
cpu_speed integer

CPU speed (in MHz)
Example
{
    "servers": {
        "pi1": {
            "model": 3,
            "memory": 1024,
            "cpu_speed": 1200
        },
        "pi2": {
            "model": 4,
            "memory": 4096,
            "cpu_speed": 1500
        }
    }
}
403

Not authorised to access this API.

application/json

NameDescription
error string

A description of the error
Example
{
    "error": "Not authorised"
}

post /pi/servers

https://api.mythic-beasts.com/beta/pi/servers

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.

Request Body JSON

NameDescription
disk integer

(Optional) Disk space size, in GB. Must be a multiple of 10

Default: 10
ssh_key string

(Optional) Public SSH key(s) to be added to /root/.ssh/authorized_keys on server
model integer

(Optional) Raspberry Pi model (3 or 4)

Default: 3
memory integer

(Optional) RAM size in MB

Default: ["see description"]
cpu_speed integer

(Optional) CPU speed in MHz

Default: ["see description"]
os_image string

(Optional) Operating system image
wait_for_dns boolean

(Optional) Whether to wait for DNS records under hostedpi.com to become available before completing provisioning.

Default: false
Example

application/json

{
    "disk": 20,
    "ssh_key": "ssh-rsa AAAAB.... user@example.com",
    "model": 4,
    "memory": 8192,
    "cpu_speed": 2000,
    "os_image": "raspbian-buster",
    "wait_for_dns": true
}

Responses

CodeDescription
202

Provisioning request accepted.

The response will include a Location header specifying a URL which can be polled for provisioning status.

When provisioning is complete, this URL will return 303 See Other with a Location header indicating the URL from which server information can be obtained (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

Invalid parameters

application/json

NameDescription
error string

A description of the error
Example
{
    "error": "Invalid model number"
}
403

Not authorised to provision server

application/json

NameDescription
error string

A description of the error
Example
{
    "error": "Not authorised"
}
503

Out of stock. Returned if no servers with the required specification are available.

application/json

NameDescription
error string

A description of the error
Example
{
    "error": "We do not have any servers of the specified type available"
}

get /pi/servers/{identifier}

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

Returns information about the specified server.

Parameters

NameLocationDescription
identifier string path

The server identifier

Responses

CodeDescription
200

Server information

application/json

NameDescription
ip string

IPv6 address for server
ssh_port integer

Port for accessing SSH via IPv4 relay. Server is accessible on ssh.{identifier}.hostedpi.com.
disk_size string

Size of disk in GB
initialized_keys boolean

Set to true if the server has an SSH key installed
location string

Data centre in which server is located
power boolean

Indicates whether server is powered on
model integer

Raspberry Pi model
is_booting boolean

Indicates whether a reboot is in progress.
boot_progress string

String indicating the status of the current reboot operation.
Example
{
    "ip": "2a00:1098:8:ffff::1",
    "ssh_port": 5001,
    "disk_size": "10.00",
    "initialized_keys": true,
    "location": "MER",
    "power": true,
    "model": 3,
    "is_booting": true,
    "boot_progress": "Waiting for initial DHCP"
}
403

Not authorised to access server or server does not exist

application/json

NameDescription
error string

A description of the error
Example
{
    "error": "Not authorised"
}
409

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 request for information on how to check provisioning status.

application/json

NameDescription
error string

A description of the error
Example
{
    "error": "Server is not fully provisioned"
}

post /pi/servers/{identifier}

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

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

NameLocationDescription
identifier string path

A unique identifier for the server. This will form part of the hostname for the server, and should consist only of alphanumerics and -.

Request Body JSON

NameDescription
disk integer

(Optional) Disk space size, in GB. Must be a multiple of 10

Default: 10
ssh_key string

(Optional) Public SSH key(s) to be added to /root/.ssh/authorized_keys on server
model integer

(Optional) Raspberry Pi model (3 or 4)

Default: 3
memory integer

(Optional) RAM size in MB

Default: ["see description"]
cpu_speed integer

(Optional) CPU speed in MHz

Default: ["see description"]
os_image string

(Optional) Operating system image
wait_for_dns boolean

(Optional) Whether to wait for DNS records under hostedpi.com to become available before completing provisioning.

Default: false
Example

application/json

{
    "disk": 20,
    "ssh_key": "ssh-rsa AAAAB.... user@example.com",
    "model": 4,
    "memory": 8192,
    "cpu_speed": 2000,
    "os_image": "raspbian-buster",
    "wait_for_dns": true
}

Responses

CodeDescription
202

Provisioning request accepted.

The response will include a Location header specifying a URL which can be polled for provisioning status.

When provisioning is complete, this URL will return 303 See Other with a Location header indicating the URL from which server information can be obtained (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

Invalid parameters

application/json

NameDescription
error string

A description of the error
Example
{
    "error": "Invalid model number"
}
403

Not authorised to provision server

application/json

NameDescription
error string

A description of the error
Example
{
    "error": "Not authorised"
}
409

Server name already exists

application/json

NameDescription
error string

A description of the error
Example
{
    "error": "Server name already exists"
}
503

Out of stock. Returned if no servers with the required specification are available.

application/json

NameDescription
error string

A description of the error
Example
{
    "error": "We do not have any servers of the specified type available"
}

delete /pi/servers/{identifier}

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

Unprovisions a Raspberry Pi server. The associated disk will be permanently deleted.

Only servers that were created using this API can be unprovisioned using this method.

Parameters

NameLocationDescription
identifier string path

Unique identifier for server

Responses

CodeDescription
200

Server deleted
403

Not authorised to access server or server does not exist

application/json

NameDescription
error string

A description of the error
Example
{
    "error": "Not authorised"
}
409

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 request for information on how to check provisioning status.

application/json

NameDescription
error string

A description of the error
Example
{
    "error": "Server is not fully provisioned"
}

get /pi/models

https://api.mythic-beasts.com/beta/pi/models

Lists all available Raspberry Pi server models and their specs.

Responses

CodeDescription
200

List of server models and specs

application/json

NameDescription
models object
* object

Model details (key will match model)
model integer

Raspberry Pi model
memory integer

Amount of RAM (in MB)
nic_speed integer

NIC speed (in Mbps)
cpu_speed integer

CPU speed (in MHz)
Example
{
    "models": [
        {
            "model": 3,
            "memory": 1024,
            "nic_speed": 100,
            "cpu_speed": 1200
        },
        {
            "model": 4,
            "memory": 4096,
            "nic_speed": 1000,
            "cpu_speed": 1500
        }
    ]
}
403

Not authorised to access this API.

application/json

NameDescription
error string

A description of the error
Example
{
    "error": "Not authorised"
}

get /pi/servers/{identifier}/ssh-key

https://api.mythic-beasts.com/beta/pi/servers/{identifier}/ssh-key

Parameters

NameLocationDescription
identifier string path

Server identifier

Responses

CodeDescription
200

SSH keys returned

application/json

NameDescription
ssh_key string

The contents of /root/.ssh/authorized_keys on the server.
Example
{
    "ssh_key": "ssh-rsa AAAAB.... user@example.com"
}
403

Not authorised to access server or server does not exist

application/json

NameDescription
error string

A description of the error
Example
{
    "error": "Not authorised"
}
409

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 request for information on how to check provisioning status.

application/json

NameDescription
error string

A description of the error
Example
{
    "error": "Server is not fully provisioned"
}

put /pi/servers/{identifier}/ssh-key

https://api.mythic-beasts.com/beta/pi/servers/{identifier}/ssh-key

Parameters

NameLocationDescription
identifier string path

Unique identifier for server

Request Body JSON

NameDescription
ssh_key string

(Required) Public SSH key(s). The value of this parameter will replace the contents of /root/.ssh/authorized_keys on server
Example

application/json

{
    "ssh_key": "ssh-rsa AAAAB.... user@example.com"
}

Responses

CodeDescription
200

SSH keys updated

application/json

NameDescription
ssh_key string

The contents of /root/.ssh/authorized_keys on the server.
Example
{
    "ssh_key": "ssh-rsa AAAAB.... user@example.com"
}
403

Not authorised to access server or server does not exist

application/json

NameDescription
error string

A description of the error
Example
{
    "error": "Not authorised"
}
409

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 request for information on how to check provisioning status.

application/json

NameDescription
error string

A description of the error
Example
{
    "error": "Server is not fully provisioned"
}

post /pi/servers/{identifier}/reboot

https://api.mythic-beasts.com/beta/pi/servers/{identifier}/reboot

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.

Parameters

NameLocationDescription
identifier string path

Server identifier

Responses

CodeDescription
200

Server power cycled

application/json

NameDescription
message string

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

Not authorised to access server or server does not exist

application/json

NameDescription
error string

A description of the error
Example
{
    "error": "Not authorised"
}
409

The server is already being rebooted, or the server is not fully provisioned.

application/json

NameDescription
error string

A description of the error
Example
{
    "error": "Reboot in progress"
}

put /pi/servers/{identifier}/power

https://api.mythic-beasts.com/beta/pi/servers/{identifier}/power

Turn power on or off

Parameters

NameLocationDescription
identifier string path

Server identifier

Request Body JSON

NameDescription
power boolean

(Required) Power status (true = on, false = off)
Example

application/json

{
    "power": true
}

Responses

CodeDescription
200

Server power set

application/json

NameDescription
message string

Response message
Example
{
    "message": "Server powered on"
}
400

Bad request

application/json

NameDescription
error string

A description of the error
Example
{
    "error": "Missing parameter 'power'"
}
403

Not authorised to access server or server does not exist

application/json

NameDescription
error string

A description of the error
Example
{
    "error": "Not authorised"
}
409

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 request for information on how to check provisioning status.

application/json

NameDescription
error string

A description of the error
Example
{
    "error": "Server is not fully provisioned"
}

get /pi/images/{model}

https://api.mythic-beasts.com/beta/pi/images/{model}

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

Parameters

NameLocationDescription
model integer path

Model identifier (3 or 4)

Responses

CodeDescription
200

Operating system image list

application/json

NameDescription
* string

OS image description (key is image name)
Example
{
    "raspian-buster": "Raspbian Buster",
    "raspian-jessie": "Raspbian Jessie"
}
400

Invalid model number

application/json

NameDescription
error string

A description of the error
Example
{
    "error": "Invalid model"
}

get /queue/pi/{task}

https://api.mythic-beasts.com/beta/queue/pi/{task}

Gets the status of an asynchronous request. This is used following a 202 response from a Provision Server request.

Parameters

NameLocationDescription
task integer path

Task identifier

Responses

CodeDescription
303

Async request complete

The Location header will provide a URL with the response to the asynchronous request.
500

Async request failed

The reason for failure will be given in the error field of the JSON body.

application/json

NameDescription
error string

A description of the error
Example
{
    "error": "Error provisioning server"
}

Support Index

Page contents