Getting started

Reads are GETs, changes are POSTs, and every response has the same shape.

One shape for every endpoint

Each resource has one endpoint, with four ways to use it:

Pools, organizations and integrations work the same way. A /modify request carries exactly one action and that action's fields. A field that belongs to another action is refused (invalid).

Some Computer actions, and /v1/computer/delete, take computers to act on several Computers at once. See changing Computers.

curl https://heaven.dev/v1/computer/modify \
  -H "Authorization: Bearer $HEAVEN_API_KEY" \
  --json '{"computer":"my-site","action":"rename","name":"my-shop"}'

Sending fields

• A POST sends a JSON object with Content-Type: application/json, which curl --json sets. A body can be up to 512 KiB, or 2 MiB for exec.
• A GET sends the same fields in its query: ?computer=my-site&view=usage&range=7d. For a list, repeat the field (?tags=web&tags=prod). For a switch, write true or false.
• Field names are snake_case. A field that takes several values is plural: tags, users, computers.
• Sizes and times are strings: "30d", "12h", "8GiB".

Naming things

You can name anything by its name or its ID: "computer":"my-site" and "computer":"7cd4a3ec-…" are the same request. IDs never change, so use them in automation. Otherwise a rename could point a later request at something else.

• A Computer's name is unique across Heaven, since it becomes NAME.heaven.dev. It has 3 to 63 letters, digits and hyphens, and can't start or end with a hyphen. Case doesn't matter. Some names, such as www, api, blog and staging, are reserved.
• A pool's name is unique only in its account, so a pool shared with you can have the same name as one of yours. A name that matches two pools is refused, and the error lists each one's ID.

Which account

You have a personal account and can belong to up to 10 organizations. A request about a Computer or pool acts in the account that owns it, so naming the Computer or pool is enough.

A request about an account itself, such as making a pool, billing, static addresses, integrations or members, takes "organization": "NAME". Without it, the request acts in your personal account. Buying capacity, charges, billing details and account deletion act in your personal account only, and take no organization.

Reads without organization return everything you can reach, in every account, and each item names its account.

Views

A GET of one Computer, of your pools or of your account returns everything about it that you can read. For a Computer, that's its access, domains, ports, mail and snapshots. Parts your key can't read are listed in withheld, and parts that couldn't be read at that moment in unavailable. The rest is still returned. To read one part instead, add view:

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

Each endpoint's reference lists its views. Each view is its own command, so a key can be allowed some views and not others.

Responses

Success is HTTP 200 with the result in data:

{"version": 1, "data": {…}}

A refusal or failure has an error instead, and an HTTP status that matches the error's kind:

{
  "version": 1,
  "error": {
    "kind": "not_found",
    "message": "No Computer \"nope\" that you can access. Run `view` to list your Computers."
  }
}

• New fields can appear in version 1 responses. Ignore ones you don't know.
• null means unknown, never zero. A measurement nobody took is null, and an empty list is [].
• Times are RFC 3339. Large counters, such as traffic, are decimal strings.
• Text instead of JSON. With Accept: text/plain, a command returns what ssh heaven.dev COMMAND prints, with the same HTTP status. A snapshot change then waits until it finishes, as it does over SSH.
• Heaven-Exit-Status, on every JSON or text response, is the exit status the command has over SSH. It's 0, or 1 for a refusal or for a change where some targets failed. For exec, it's the command's own exit status.

Changes return an operation

Heaven saves a change to a Computer, such as create, start, stop, rename or a snapshot, before it responds. The change finishes on the Computer's server shortly after. The response is an operation:

{
  "version": 1,
  "data": {
    "request_id": "f4515dc8-125c-45d4-9000-fcb344896108",
    "operation": {
      "id": "8540e6f2-9f39-4d39-89b5-eeac80d0ac97",
      "kind": "create",
      "computer_id": "0098166a-9908-43ab-967b-4111c45c3b33",
      "revision": 1,
      "state": "accepted"
    }
  }
}

accepted means saved, not finished. Operations and retries shows how to follow it. Other changes, such as adding a domain or an SSH key, take effect at once. They return what they made, or {"updated": true}.