Getting started

The API does everything the dashboard does: create and run Computers, share them, and manage pools, keys and organizations over HTTPS.

Overview

A Computer is a persistent Linux machine with root access. Its files stay, and its services keep running after you disconnect. Computers run in a pool, a share of CPU, memory and storage that its Computers use together, so a busy Computer can use what its idle neighbors aren't using. You make pools from capacity you buy on a server.

The API runs the same commands as the dashboard, the heaven program and ssh heaven.dev, with the same names, permissions and errors.

Base URL

https://heaven.dev/v1

Examples on these pages use this site's own address, so you can paste them as they are.

Quickstart

1. Create an API key

   With an SSH key added on the dashboard, create a key that can list and create Computers. It's shown once, so keep it.

   Terminal

   ssh heaven.dev api-key create --label quickstart --expires 7d \
     --command view --command create

   No SSH key? Sign in with a code instead.

2. Make your first request

   Terminal

   export HEAVEN_API_KEY=heaven1.…
   curl https://heaven.dev/v1/computer/ \
     -H "Authorization: Bearer $HEAVEN_API_KEY"

   The response lists the Computers you can reach: {"version":1,"data":{"computers":[…]}}.

3. Create a Computer

   Give it a name and pick one of your pools. GET /v1/pool/ lists them. If you have only one pool, you can leave pool out.

   Terminal

   curl https://heaven.dev/v1/computer/create \
     -H "Authorization: Bearer $HEAVEN_API_KEY" \
     --json '{"name":"my-site","pool":"web"}'

   The response is an operation. The Computer is ready when its state is running, usually within a minute:

   Terminal

   curl 'https://heaven.dev/v1/computer/?computer=my-site' \
     -H "Authorization: Bearer $HEAVEN_API_KEY"

4. Use it

   Connect with ssh my-site@heaven.dev, or run a command through the API with exec. Its website is https://my-site.heaven.dev.

Endpoints

Each resource has one endpoint. A GET reads it, and a POST to /create, /modify or /delete changes it.

Every read and action

Each endpoint's page explains how the resource works, then gives every read and action its own section with a request you can copy. Try requests sends real requests from your browser, signed in as you. The same details are in the API's OpenAPI document, for code generators and API tools.

Next