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.
On this page
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'| 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 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.