Skip to content

API reference

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

Send a request

#

Use the HTTP API guide for authentication and a first request. For terminal or agent access, see CLI, SSH or MCP.

Responses

#

Management responses contain version and either data or error. Changes can return an operation; follow its ID with Read an operation.

Requests by resource

#

Use All commands to look up a command name or All endpoints for an HTTP method and path. The OpenAPI document provides machine-readable types.

Computers

#
ResourceWhat it is
ComputersA Computer is a persistent Linux virtual machine with root access, running in a pool.
SnapshotsA snapshot records a Computer's disk at a point in time for restoration or copying.
Run and exportGuest execution runs commands and transfers files inside a Computer.
TemplatesA template is a named image for creating Computers.

Pools and capacity

#
ResourceWhat it is
PoolsA pool supplies shared CPU, RAM and storage to its Computers.
Pool snapshotsA pool snapshot is a set of Computer disk snapshots captured separately.
CapacityCapacity is purchased CPU, RAM and storage allocated to pools.

Networking

#
ResourceWhat it is
DomainsA domain connects names you control to Computer websites through DNS records.
Static addressesA static IPv4 address belongs to an organization and can be attached to a Computer, pool or account.

Organization

#
ResourceWhat it is
OrganizationsAn organization owns pools and Computers and pays for their capacity.
TeamsA team is a group of organization members who can own Computers and share access to resources.
BillingAn organization pays for monthly capacity through its subscription, and hourly capacity and excess internet egress through its prepaid wallet.
IntegrationsAn integration gives Computers access to a service through Heaven.

Your account

#
ResourceWhat it is
AccountYour account identifies you across organizations and sign-ins.
SSH keysAn SSH key authenticates SSH connections and signed API requests with your permissions.
API keysAn API key lets a program act as you within one organization, limited to its allowed commands and resources.
Connect codesA connect code lets an agent request sign-in.

The API itself

#
ResourceWhat it is
OperationsAn operation records an accepted change, its progress and result.
Key permissionsA command permission lets an API key run an action within your access and the key's resource scope.
FeedbackFeedback sends a private message to the Heaven team.