Quick start guide

The page provides a walk through guide for provisioning a server using the Raspberry Pi Provisioning API.

  • Create an API key using the customer control panel.

  • Set some evironment variables. Use the key details from the control panel, choose your own server name, and path to your own SSH public key if different.

  • Get an access token from the auth server:
TOKEN=`curl -s -d 'grant_type=client_credentials' -u "$API_USER:$API_PASS" https://auth.mythic-beasts.com/login | jq -r .access_token`
  • Create a server:
$ curl -D- -H "Authorization: Bearer $TOKEN"  -X POST https://api.mythic-beasts.com/beta/pi/servers/$SERVER_NAME
HTTP/1.1 202 Accepted
Location: https://api.mythic-beasts.com/beta/queue/pi/8
Content-Type: application/json

  • Poll the URL provided in the Location header.
$ curl -D- -H "Authorization: Bearer $TOKEN" https://api.mythic-beasts.com/beta/queue/pi/8
HTTP/1.1 200 OK
Content-Type: application/json

{"status":"Installing operating system"}
  • Poll again (after a minute or so):
$ curl -D- -H "Authorization: Bearer $TOKEN" https://api.mythic-beasts.com/beta/queue/pi/8
HTTP/1.1 303 See other
Location: https://api.mythic-beasts.com/beta/pi/servers/test-pi-14535
Content-Type: application/json

  • Get server details from the indicated URL:
$ curl -s -H "Authorization: Bearer $TOKEN" https://api.mythic-beasts.com/beta/pi/servers/test-pi-14535 | jq
  "disk_size": "10.00",
  "status": "live",
  "location": "MER",
  "initialised_keys": false,
  "power": true,
  "model": 3,
  "ip": "2a00:1098:0008:0099:0000:0000:0000:0001",
  "ssh_port": 5153
  • Set an SSH key (this can also be done in the initial POST to create the server)
$ curl -D- -d "{\"ssh_key\": \"$(cat $SSH_KEY)\"}" -H "Content-Type: application/json" -H "Authorization: Bearer $TOKEN"  -X PUT https://api.mythic-beasts.com/beta/pi/servers/$SERVER_NAME/ssh-key
HTTP/1.1 200 OK
  • If you have an IPv6 connection, you can login now:
$ ssh root@$SERVER_NAME.hostedpi.com
  • Otherwise, we can grab the port number from the server details response above:
$ PORT=`curl -s -H "Authorization: Bearer $TOKEN" https://api.mythic-beasts.com/beta/pi/servers/test-pi-14535 | jq -r .ssh_port`
  • And use that to login via the IPv4 proxy:
$ ssh -p $PORT root@ssh.$SERVER_NAME.hostedpi.com
The authenticity of host '[ssh.test-pi-14535.hostedpi.com]:5153 ([]:5153)' can't be established.
ECDSA key fingerprint is SHA256:2reFdstKrXN21QtrvoSSbI+ymmvPgzWMbyl+fpVIjz4.
Are you sure you want to continue connecting (yes/no)? yes
Warning: Permanently added '[ssh.test-pi-14535.hostedpi.com]:5153,[]:5153' (ECDSA) to the list of known hosts.
Linux raspberrypi 4.19.50-v7+ #896 SMP Thu Jun 20 16:11:44 BST 2019 armv7l

The programs included with the Debian GNU/Linux system are free software;
the exact distribution terms for each program are described in the
individual files in /usr/share/doc/*/copyright.

Debian GNU/Linux comes with ABSOLUTELY NO WARRANTY, to the extent
permitted by applicable law.
Last login: Mon Jul  1 14:58:15 2019 from

For more information, please see the full API docs.