Skip to content

HTTP API

Heaven's HTTP API manages resources under https://heaven.dev/v1/. Reads use GET with query fields; changes use POST with a JSON body.

Authentication

#

In the 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:

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:

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:

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.

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:

curl --silent --show-error --get 'https://heaven.dev/v1/operation/' \
  -H "Authorization: Bearer $HEAVEN_API_KEY" \
  --data-urlencode 'operation=OPERATION_ID'
StateMeaning
acceptedWork is in progress.
completeWork finished.
failedWork failed; the operation includes an error.
supersededA newer change replaced this operation.

Read an operation 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 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 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 return bytes. Guest commands have no request-ID replay; inspect the Computer before repeating a command whose response was lost.

The OpenAPI document supplies request and response types for client generation.