# Heaven API

Source: https://heaven.dev/docs

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](https://heaven.dev/docs/pools#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

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](https://heaven.dev/dashboard/keys), create a key that can list and create Computers. It's shown once, so keep it.

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

   No SSH key? [Sign in with a code](https://heaven.dev/docs/authentication#device-sign-in) instead.

2. ### Make your first request

   ```sh
   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.

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

   The response is an [operation](https://heaven.dev/docs/operations). The Computer is ready when its `state` is `running`, usually within a minute:

   ```sh
   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](https://heaven.dev/docs/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.

| Endpoint | For |
| --- | --- |
| [`/v1/auth/`](https://heaven.dev/docs/authentication#device-sign-in) | Sign a program in with a code |
| [`/v1/account/`](https://heaven.dev/docs/account) | SSH and API keys, capacity, billing, static addresses (not offered yet), defaults, invitations, deleting your account |
| [`/v1/organization/`](https://heaven.dev/docs/organizations) | Organizations, members and teams |
| [`/v1/integration/`](https://heaven.dev/docs/integrations) | Outside services Computers call without holding secrets |
| [`/v1/pool/`](https://heaven.dev/docs/pools) | Pools, the capacity they come from, pool snapshots and the plans to buy |
| [`/v1/computer/`](https://heaven.dev/docs/computers) | Computers: create, start and stop, snapshots, sharing, domains, ports |
| [`/v1/computer/exec`](https://heaven.dev/docs/exec) | Run a command, download or upload a file; `/export` downloads the disk |
| [`/v1/operation/`](https://heaven.dev/docs/operations#read) | The progress and outcome of a change |
| [`/v1/feedback/`](https://heaven.dev/docs/feedback) | Notes to the Heaven team |
| [`/mcp`](https://heaven.dev/docs/mcp) | The same commands as tools for agents |
| [`heaven`, SSH](https://heaven.dev/docs/cli) | The same commands from a terminal, and a shell on a Computer |

## 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](https://heaven.dev/docs/try) sends real requests from your browser, signed in as you. The same details are in the API's [OpenAPI document](https://heaven.dev/docs/openapi.json), for code generators and API tools.

## Next

- [Authentication](https://heaven.dev/docs/authentication): API keys, what they can run, and signing in from a program.
- [Requests and responses](https://heaven.dev/docs/requests): How fields, names, organizations and responses work.
- [Operations and retries](https://heaven.dev/docs/operations): Follow a change, and retry without doing it twice.
- [Computers](https://heaven.dev/docs/computers): Every read and action on Computers, with examples.