# HTTP API

URL: https://heaven.dev/docs/http-api
Updated: 2026-11-21

Heaven's [HTTP API](https://heaven.dev/docs/reference) manages resources under `https://heaven.dev/v1/`. Reads use `GET` with query fields; changes use `POST` with a JSON body.

## Authentication

In the [dashboard](https://heaven.dev/dashboard), open **Settings → SSH & API keys → New API key**. Select an organization, permissions and resource scope. Save the secret when shown.

These POSIX shell examples use `HEAVEN_API_KEY`:

```sh
curl --silent --show-error --include 'https://heaven.dev/v1/command/' \
  -H "Authorization: Bearer $HEAVEN_API_KEY"
```

Every API key can read this command catalog. HTTP `401` indicates a missing or invalid credential; `403` indicates insufficient permission. API keys are bound to their organization and access scope.

## Resource selection

A Computer's name or ID identifies its organization. Pool names are unique within an organization; supply `organization` for an ambiguous name, or use the pool ID.

Read pool `web` in `rivera-labs`:

```sh
curl --silent --show-error --get 'https://heaven.dev/v1/pool/' \
  -H "Authorization: Bearer $HEAVEN_API_KEY" \
  --data-urlencode 'pool=web' \
  --data-urlencode 'organization=rivera-labs' \
  --data-urlencode 'parts=none'
```

The result is in `data.pool`. `parts=none` omits supplementary views.

## Create a Computer

Choose an unused name and a request ID. The key needs permission to create Computers in the pool:

```sh
curl --silent --show-error --include 'https://heaven.dev/v1/computer/create' \
  -H "Authorization: Bearer $HEAVEN_API_KEY" \
  -H 'Idempotency-Key: my-site-create-1' \
  -H 'Content-Type: application/json' \
  --data '{"name":"my-site","pool":"web","organization":"rivera-labs"}'
```

Save the request body and ID before sending.

Requests take effect when sent. Commands that support `dry_run: true` can preview a change. Unknown or duplicate fields, `null` inputs and incorrect types are refused; omit optional fields to use their documented defaults.

Some endpoints select a command with `action` or `view`. Use the method, path and selector in the [endpoint index](https://heaven.dev/docs/reference/endpoints).

## Responses and operations

Successful management requests return HTTP `200` with `version: 1` and `data`. This create returns an operation in `data.operation`.

Read the operation using that ID:

```sh
curl --silent --show-error --get 'https://heaven.dev/v1/operation/' \
  -H "Authorization: Bearer $HEAVEN_API_KEY" \
  --data-urlencode 'operation=OPERATION_ID'
```

| State | Meaning |
| --- | --- |
| `accepted` | Work is in progress. |
| `complete` | Work finished. |
| `failed` | Work failed; the operation includes an error. |
| `superseded` | A newer change replaced this operation. |

[Read an operation](https://heaven.dev/docs/reference/operations/read) supports a bounded wait. Accepted work continues after the wait expires or the connection closes.

`Heaven-Exit-Status` reports the command's exit status. `Heaven-Request-Id` identifies the request for support.

## Lost responses and errors

Recover this create by sending the original request with the same `Idempotency-Key`. Reusing the ID with different inputs is refused. A new ID starts new work.

Only commands with documented request-ID support accept that header. Supply the ID in the header, never in the JSON body. If omitted, Heaven generates one.

[Errors](https://heaven.dev/docs/reference/errors) contain `version: 1` and `error`. Use `error.kind` for program decisions and `error.message` for the explanation. Preserve any request and operation IDs.

## Guest commands and files

[Guest execution](https://heaven.dev/docs/reference/exec/run) uses `/v1/computer/exec`. JSON responses contain base64-encoded `output` and the guest's `exit_code`. Request `Accept: application/x-ndjson` for streamed output records and a final exit code.

Downloads and [disk exports](https://heaven.dev/docs/reference/exec/export) return bytes. Guest commands have no request-ID replay; inspect the Computer before repeating a command whose response was lost.

The [OpenAPI document](https://heaven.dev/docs/openapi.json) supplies request and response types for client generation.
