Raspberry Pi Provisioning API
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
Lists all Raspberry Pi servers associated with this account.
Responses
Code | Description |
---|---|
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 { "error": "Not authorised" } |
get /pi/servers/{identifier}
Returns information about the specified server.
Parameters
Name | Location | Description |
---|---|---|
identifier string | path |
The server identifier |
Responses
Code | Description |
---|---|
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 { "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 application/json { "error": "Server is not fully provisioned" } |
post /pi/servers/{identifier}
Provisions a new Raspberry Pi cloud server. Each server requires a
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
Name | Location | Description |
---|---|---|
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
Name | Description |
---|---|
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
Code | Description |
---|---|
202 | Provisioning request accepted. The response will include a When provisioning is complete, this URL will return Provisioning typically takes 2-3 minutes. The server may not be
fully booted when the poll URL returns In the event of a provisioning error, the polled URL will return
|
400 | Invalid parameters application/json { "error": "Invalid model number" } |
403 | Not authorised to provision server application/json { "error": "Not authorised" } |
409 | Server name already exists application/json { "error": "Server name already exists" } |
503 | Out of stock. Returned if no servers with the required specification are available. application/json { "error": "We do not have any servers of the specified type available" } |
delete /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
Name | Location | Description |
---|---|---|
identifier string | path |
Unique identifier for server |
Responses
Code | Description |
---|---|
200 | Server deleted |
403 | Not authorised to access server or server does not exist application/json { "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 application/json { "error": "Server is not fully provisioned" } |
get /pi/models
Lists all available Raspberry Pi server models and their specs.
Responses
Code | Description |
---|---|
200 | List of server models and specs application/json { "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 { "error": "Not authorised" } |
get /pi/servers/{identifier}/ssh-key
Parameters
Name | Location | Description |
---|---|---|
identifier string | path |
Server identifier |
Responses
Code | Description |
---|---|
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 { "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 application/json { "error": "Server is not fully provisioned" } |
put /pi/servers/{identifier}/ssh-key
Parameters
Name | Location | Description |
---|---|---|
identifier string | path |
Unique identifier for server |
Request Body JSON
Name | Description |
---|---|
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
Code | Description |
---|---|
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 { "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 application/json { "error": "Server is not fully provisioned" } |
post /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
Name | Location | Description |
---|---|---|
identifier string | path |
Server identifier |
Responses
Code | Description |
---|---|
200 | Server power cycled application/json { "message": "Operation successful" } |
403 | Not authorised to access server or server does not exist application/json { "error": "Not authorised" } |
409 | The server is already being rebooted, or the server is not fully provisioned. application/json { "error": "Reboot in progress" } |
put /pi/servers/{identifier}/power
Turn power on or off
Parameters
Name | Location | Description |
---|---|---|
identifier string | path |
Server identifier |
Request Body JSON
Name | Description |
---|---|
power boolean |
(Required) Power status (true = on, false = off) |
Example
application/json
{ "power": true }
Responses
Code | Description |
---|---|
200 | Server power set application/json { "message": "Server powered on" } |
400 | Bad request application/json { "error": "Missing parameter 'power'" } |
403 | Not authorised to access server or server does not exist application/json { "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 application/json { "error": "Server is not fully provisioned" } |
get /pi/images/{model}
Gets a list of available operating system images for the specified model.
Parameters
Name | Location | Description |
---|---|---|
model integer | path |
Model identifier ( |
Responses
Code | Description |
---|---|
200 | Operating system image list application/json { "raspian-buster": "Raspbian Buster", "raspian-jessie": "Raspbian Jessie" } |
400 | Invalid model number application/json { "error": "Invalid model" } |
get /queue/pi/{task}
Gets the status of an asynchronous request. This is used following a 202 response from a Provision Server request.
Parameters
Name | Location | Description |
---|---|---|
task integer | path |
Task identifier |
Responses
Code | Description |
---|---|
303 | Async request complete The |
500 | Async request failed The reason for failure will be given in the application/json { "error": "Error provisioning server" } |