# API reference

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

Heaven's API manages Computers, pools, organizations and related resources.

## Send a request

Use the [HTTP API guide](https://heaven.dev/docs/http-api) for authentication and a first request. For terminal or agent access, see [CLI](https://heaven.dev/docs/cli), [SSH](https://heaven.dev/docs/ssh) or [MCP](https://heaven.dev/docs/mcp).

## Responses

Management responses contain `version` and either `data` or `error`. Changes can return an operation; follow its ID with [Read an operation](https://heaven.dev/docs/reference/operations/read).

## Requests by resource

Use [All commands](https://heaven.dev/docs/reference/commands) to look up a command name or [All endpoints](https://heaven.dev/docs/reference/endpoints) for an HTTP method and path. The [OpenAPI document](https://heaven.dev/docs/openapi.json) provides machine-readable types.

## Computers

| Resource | What it is |
| --- | --- |
| [Computers](https://heaven.dev/docs/reference/computers) | A Computer is a persistent Linux virtual machine with root access, running in a pool. |
| [Snapshots](https://heaven.dev/docs/reference/snapshots) | A snapshot records a Computer's disk at a point in time for restoration or copying. |
| [Run and export](https://heaven.dev/docs/reference/exec) | Guest execution runs commands and transfers files inside a Computer. |
| [Templates](https://heaven.dev/docs/reference/templates) | A template is a named image for creating Computers. |

## Pools and capacity

| Resource | What it is |
| --- | --- |
| [Pools](https://heaven.dev/docs/reference/pools) | A pool supplies shared CPU, RAM and storage to its Computers. |
| [Pool snapshots](https://heaven.dev/docs/reference/pool-snapshots) | A pool snapshot is a set of Computer disk snapshots captured separately. |
| [Capacity](https://heaven.dev/docs/reference/capacity) | Capacity is purchased CPU, RAM and storage allocated to pools. |

## Networking

| Resource | What it is |
| --- | --- |
| [Domains](https://heaven.dev/docs/reference/domains) | A domain connects names you control to Computer websites through DNS records. |
| [Static addresses](https://heaven.dev/docs/reference/addresses) | A static IPv4 address belongs to an organization and can be attached to a Computer, pool or account. |

## Organization

| Resource | What it is |
| --- | --- |
| [Organizations](https://heaven.dev/docs/reference/organizations) | An organization owns pools and Computers and pays for their capacity. |
| [Teams](https://heaven.dev/docs/reference/teams) | A team is a group of organization members who can own Computers and share access to resources. |
| [Billing](https://heaven.dev/docs/reference/billing) | An organization pays for monthly capacity through its subscription, and hourly capacity and excess internet egress through its prepaid wallet. |
| [Integrations](https://heaven.dev/docs/reference/integrations) | An integration gives Computers access to a service through Heaven. |

## Your account

| Resource | What it is |
| --- | --- |
| [Account](https://heaven.dev/docs/reference/account) | Your account identifies you across organizations and sign-ins. |
| [SSH keys](https://heaven.dev/docs/reference/ssh-keys) | An SSH key authenticates SSH connections and signed API requests with your permissions. |
| [API keys](https://heaven.dev/docs/reference/api-keys) | An API key lets a program act as you within one organization, limited to its allowed commands and resources. |
| [Connect codes](https://heaven.dev/docs/reference/connect-codes) | A connect code lets an agent request sign-in. |

## The API itself

| Resource | What it is |
| --- | --- |
| [Operations](https://heaven.dev/docs/reference/operations) | An operation records an accepted change, its progress and result. |
| [Key permissions](https://heaven.dev/docs/reference/command) | A command permission lets an API key run an action within your access and the key's resource scope. |
| [Feedback](https://heaven.dev/docs/reference/feedback) | Feedback sends a private message to the Heaven team. |
