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 /servers/pi

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

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

{
    "pi1": {
        "model": 3
    },
    "pi2": {
        "model": 4
    }
}
403

Not authorised to access this API.

application/json

{
    "message": "Not authorised"
}

get /servers/pi/{server}

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

Returns information about the specified server.

Parameters

NameLocationDescription
server string path

The server identifier

Responses

CodeDescription
200

Server information

application/json

{
    "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

{
    "message": "Not authorised"
}

post /servers/pi/{server}

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

Provisions a new Raspberry Pi cloud server. Each server requires a unique service identifier. DNS for the service will become available at {server}.hostedpi.com.

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:

{server}.hostedpi.com

SSH connections can be made directly over IPv6 on port 22 to {server}.hostedpi.com which will resolve to the server's IPv6 address.

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

Parameters

NameLocationDescription
server 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
os_image string

(Optional) Operating system image

Example

application/json

{
    "disk": 20,
    "ssh_key": "ssh-rsa AAAAB.... user@example.com",
    "model": 4,
    "os_image": "raspbian-buster"
}

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

{
    "message": "Invalid model number"
}
403

Not authorised to provision server

application/json

{
    "message": "Not authorised"
}
409

Server name already exists

application/json

{
    "message": "Server name already exists"
}
503

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

application/json

{
    "message": "We do not have any servers of the specified type available"
}

delete /servers/pi/{server}

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

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
server string path

Unique identifier for server

Responses

CodeDescription
200

Server deleted

403

Not authorised to access server or server does not exist

application/json

{
    "message": "Not authorised"
}

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

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

Parameters

NameLocationDescription
server string path

Server identifier

Responses

CodeDescription
200

SSH keys returned

application/json

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

Not authorised to access server or server does not exist

application/json

{
    "message": "Not authorised"
}

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

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

Parameters

NameLocationDescription
server 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

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

Not authorised to access server or server does not exist

application/json

{
    "message": "Not authorised"
}

post /servers/pi/{server}/reboot

https://api.mythic-beasts.com/beta/servers/pi/{server}/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
server string path

Server identifier

Responses

CodeDescription
200

Server power cycled

application/json

{
    "message": "Operation successful"
}
403

Not authorised to access server or server does not exist

application/json

{
    "message": "Not authorised"
}

put /servers/pi/{server}/power

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

Turn power on or off

Parameters

NameLocationDescription
server 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

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

Bad request

application/json

{
    "message": "Missing parameter 'power'"
}
403

Not authorised to access server or server does not exist

application/json

{
    "message": "Not authorised"
}

get /servers/pi-os-images/:model

https://api.mythic-beasts.com/beta/servers/pi-os-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

{
    "raspian-buster": "Raspbian Buster",
    "raspian-jessie": "Raspbian Jessie"
}
400

Invalid model number

application/json

{
    "message": "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

{
    "message": "Error provisioning server"
}

Common errors