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

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

Not authorised to access this API.

application/json

{
    "error": "Not authorised"
}

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

{
    "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 202 response from a Provision Server request for information on how to check provisioning status.

application/json

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

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

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

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

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

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

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

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

{
    "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 202 response from a Provision Server request for information on how to check provisioning status.

application/json

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

{
    "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 202 response from a Provision Server request for information on how to check provisioning status.

application/json

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

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

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

{
    "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 202 response from a Provision Server request for information on how to check provisioning status.

application/json

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

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

Invalid model number

application/json

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

{
    "error": "Error provisioning server"
}

Support Index

Page contents