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": "Name already taken"
}

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
}
403

Not authorised to access server or server does not exist

application/json

{
    "message": "Name already taken"
}

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
Example

application/json

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

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": "Name already taken"
}
403

Not authorised to provision server

application/json

{
    "message": "Name already taken"
}
409

Server name already exists

application/json

{
    "message": "Name already taken"
}
503

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

application/json

{
    "message": "Name already taken"
}

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": "Name already taken"
}

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": "Name already taken"
}

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": "Name already taken"
}

post /servers/pi/{server}/reboot

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

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": "Name already taken"
}

get /queue/pi/:task

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

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": "Name already taken"
}

Common errors

Support Index

Page contents