Endpoints

Computers

A Computer is a persistent Linux machine with root access. It runs in a pool and shares the pool's CPU and memory.

Read Computers with GET /v1/computer/, and create and delete them with /create and /delete. Change one with POST /v1/computer/modify, naming the computer and one action. Each section below is one read or action.

Several at once. start, stop, restart, pause, resume, move, tag, comment, transfer, share add, share remove, snapshot create and snapshot delete take computers instead of computer. Heaven checks every name first, so a typo changes nothing. The response is HTTP 200 with one result per Computer, either an operation or an error, even when some fail. Each Computer counts against the rate limit.

Read

List or get Computers

GET/v1/computer/

Lists the Computers you can see, or returns one Computer with its recent operations and every part of it you can read.

The parts of one Computer are access, domains, ports, mail and snapshots.

Query

computer string: Read this Computer, its recent operations and everything you can read of it.
pattern string: Only names matching this pattern, such as web-*.
group string: Group the list by pool, tag, access, or (with organization) user.
organization string: Act in this organization (its name or ID) instead of your personal account.

Each Computer in the list

id, name string: Its ID and name.
pool, pool_id string: Its pool's name (when the pool is in an account you belong to) and ID.
state string: creating, preparing_image, starting, running, checking, degraded, restarting, resetting, stopping, stopped, paused, failed, image_failed, held, deleting or unknown.
state_message string: The state in a sentence, with the next step when there is one. Show this to people rather than working it out from status.
access string: Your role on it: owner, admin, root or web.
ssh_dest string: The address for ssh and scp, such as my-site@heaven.dev.
url string: Its website: https://my-site.heaven.dev.
size object: vcpus, memory_mib and disk_bytes.
image, tags: The image it was made from, and its tags.
memory_message string: Where its memory is now, such as "Asleep, 40 MB in RAM; the first request takes a moment." Present only while it's running and was measured recently.
processors_message string: How many of its vCPUs it can use while its server is busy. Absent otherwise.

When you read one Computer with computer, the response's computer is its whole view:

its record, computer, with id, name, pool_id, image, tags, comment, its network address and its creation time;
owner_id, account_id, status, disk and usage;
ssh_dest and its parts, ssh_host (port 22) and ssh_user;
tier, which says where its memory is: active, idle or asleep.

An API key needs view in its commands.

Request

curl 'https://heaven.dev/v1/computer/' \
  -H "Authorization: Bearer $HEAVEN_API_KEY"

200 The list

{
  "version": 1,
  "data": {
    "computers": [
      {
        "id": "7cd4a3ec-7411-402c-b74b-43f6d7587ae7",
        "name": "my-site",
        "pool": "web",
        "pool_id": "pool-832036a4f8a142bf",
        "state": "running",
        "state_message": "Running.",
        "memory_message": "Asleep, 40 MB in RAM; the first request takes a moment.",
        "access": "owner",
        "ssh_dest": "my-site@heaven.dev",
        "url": "https://my-site.heaven.dev",
        "size": { "vcpus": 2, "memory_mib": 4096, "disk_bytes": 20000000000 },
        "image": "heaven-ubuntu",
        "tags": ["web"]
      }
    ]
  }
}

200 One Computer: ?computer=my-site

{
  "version": 1,
  "data": {
    "computer": {
      "computer": { "id": "7cd4a3ec-…", "name": "my-site", … },
      "owner_id": "a308210e-005c-43ba-b452-db81b4034d90",
      "account_id": "ee225ef4-b631-45d3-b876-49f542ed0809",
      "access": "owner",
      "state": "running",
      "state_message": "Running.",
      "ssh_dest": "my-site@heaven.dev",
      "ssh_host": "heaven.dev",
      "ssh_user": "my-site",
      "url": "https://my-site.heaven.dev",
      …
    },
    "operations": [
      {
        "id": "7bbd53b7-8a68-4f61-a03f-db54072e591d",
        "kind": "restart",
        "state": "complete",
        "created_at": "2026-11-01T23:25:02Z",
        "completed_at": "2026-11-01T23:25:19Z"
      }
    ],
    "access": {…},
    "domains": [],
    "ports": {…},
    "mail": {
      "receiving_enabled": true,
      "reply_policy": "all",
      "sending_suspended": false
    },
    "snapshots": {…}
  }
}

Read usage

GET/v1/computer/?view=usage

Returns a Computer's CPU, memory, disk and network use over 24 hours, 7 days or 30 days.

Query

computer string required: A Computer: its name or ID.
range string: The span of history: 24h (the default), 7d or 30d.
resolution string: A point every minute (1m), five minutes (5m) or hour (1h), over any range; it wins over points. Without it, 24h has a point every 5 minutes and 7d and 30d one an hour.
points string: At most this many points in the series, but never fewer than one a day: its intervals are merged into the narrowest step that fits (a minute up to a day), so 30d returns 30 points for any N below 30. Without it or resolution, 24h has a point every 5 minutes and 7d and 30d one an hour; MCP tools ask for 24.

An API key needs usage in its commands.

Request

curl 'https://heaven.dev/v1/computer/?computer=my-site&view=usage' \
  -H "Authorization: Bearer $HEAVEN_API_KEY"

Read the boot console

GET/v1/computer/?view=logs

Returns a Computer's boot console, for the current boot or the one before.

Query

computer string required: A Computer: its name or ID.
previous boolean: The boot before the current one.

An API key needs logs in its commands.

Request

curl 'https://heaven.dev/v1/computer/?computer=my-site&view=logs' \
  -H "Authorization: Bearer $HEAVEN_API_KEY"

Open the browser terminal

GET/v1/computer/?view=terminal

Returns a link to a Computer's terminal in the browser.

The link is in url. It opens only in a browser signed in to Heaven. Programs use exec or SSH instead.

Query

computer string required: A Computer: its name or ID.

An API key needs terminal in its commands.

Request

curl 'https://heaven.dev/v1/computer/?computer=my-site&view=terminal' \
  -H "Authorization: Bearer $HEAVEN_API_KEY"

Open the desktop

GET/v1/computer/?view=desktop

Returns a link to a Computer's desktop in the browser. Only its owner and people with root access can open it.

Query

computer string required: A Computer: its name or ID.

An API key needs desktop in its commands.

Request

curl 'https://heaven.dev/v1/computer/?computer=my-site&view=desktop' \
  -H "Authorization: Bearer $HEAVEN_API_KEY"

Read who has access

GET/v1/computer/?view=access

Returns who can reach a Computer and its website.

The response lists its shares, invitations, links, domains and ports, and says whether its website is public.

Query

computer string required: A Computer: its name or ID.

An API key needs access in its commands.

Request

curl 'https://heaven.dev/v1/computer/?computer=my-site&view=access' \
  -H "Authorization: Bearer $HEAVEN_API_KEY"

Create and delete

Create a Computer

POST/v1/computer/create

Creates a Computer in a pool from an image, or as a copy of a Computer or one of its snapshots.

A Computer uses its pool's CPU, memory and storage, so you don't need to size it. It returns an operation at once, and the Computer is ready when its state is running.

Body

name string

Its name, which becomes NAME.heaven.dev. Without one, Heaven picks a free adjective-noun name, such as swift-otter. The answer's name says which.

pool string

The pool it runs in. Required unless you have exactly one.

image string

Any OCI image, such as debian:12 or ghcr.io/you/app:latest. Defaults to Heaven's Ubuntu.

registry_auth string

USERNAME:PASSWORD for a private image's registry.

integrations string[]

Integrations to attach to it.

github object

{"repo": "OWNER/REPO"} clones that repository into the home directory at first boot, before your setup script. It uses a GitHub integration you can attach that reaches OWNER. If the clone keeps failing for a minute, setup stops there, but the Computer stays.

repo string required: A GitHub repository (OWNER/REPO) to clone into the Computer, through your GitHub integration.

setup_script string

A script run once at first boot, up to 10 KiB. Without one, your default runs. A pool's setup script runs first either way.

env string[]

Environment variables for the setup script, such as ["PORT=8000"].

tags string[]

Tags to group, filter and attach integrations by.

comment string

A note for people.

cpu string

vCPUs of its own, within its pool's, as resize gives. Without it, the Computer can use the whole pool.

memory string

Memory of its own, such as 8GiB, within its pool's. Without it, the Computer can use the whole pool.

disk string

A disk of its own, such as 20GB, up to the pool's storage. By default, it shares the pool's storage, or takes the pool's default disk.

copy object

{"computer": "NAME"} copies a Computer's disk. Add "snapshot" to copy one of its snapshots instead. A copy takes no image, setup_script, env, tags or comment. Copying a disk needs root access or ownership. Copying a snapshot needs ownership, or a pool snapshot shared with you. The copy must be made in a pool on the source's server, or it's refused (conflict). A copy from a shared snapshot names your pool and keeps none of the source's tags.

computer string required: Make a copy of this Computer (or, with snapshot, of one of its snapshots).
snapshot string: Copy this snapshot of it.

copy_tags boolean

Whether a copy keeps the source's tags. Defaults to true.

organization string

Act in this organization (its name or ID) instead of your personal account.

wait boolean or string

Wait until it finishes and return how it ended: true waits up to 10m, a duration such as 2m waits that long.

An API key needs create in its commands.

Request

curl https://heaven.dev/v1/computer/create \
  -H "Authorization: Bearer $HEAVEN_API_KEY" \
  --json '{
    "name": "my-site",
    "pool": "web",
    "setup_script": "apt-get install -y nginx",
    "tags": ["web"]
  }'

200

{
  "version": 1,
  "data": {
    "request_id": "f4515dc8-125c-45d4-9000-fcb344896108",
    "operation": {
      "id": "8540e6f2-9f39-4d39-89b5-eeac80d0ac97",
      "kind": "create",
      "computer_id": "0098166a-9908-43ab-967b-4111c45c3b33",
      "revision": 1,
      "state": "accepted"
    },
    "name": "my-site",
    "ssh_dest": "my-site@heaven.dev",
    "url": "https://my-site.heaven.dev"
  }
}

Copy a snapshot

{"name": "my-site-test", "copy": {"computer": "my-site", "snapshot": "before-upgrade"}}

Delete Computers

POST/v1/computer/delete

Deletes Computers with their disks and snapshots, at once. Heaven's operators can restore one from backups for 7 days.

You can't undo a delete yourself. Heaven checks every name before anything is deleted, so a typo deletes nothing. Each Computer gets its own result, either an operation or an error.

Body

computers string[] required: The Computers to delete, by name or ID, any number. Use computer to name just one.

An API key needs delete in its commands.

Request

curl https://heaven.dev/v1/computer/delete \
  -H "Authorization: Bearer $HEAVEN_API_KEY" \
  --json '{"computers": ["my-site", "my-api"]}'

200

{
  "version": 1,
  "data": {
    "request_id": "05576c57-a681-4949-b029-47b5cf175489",
    "results": [
      {
        "computer": { "id": "7cd4a3ec-…", "name": "my-site" },
        "operation": {
          "id": "95ea2943-c2d2-4468-97c4-80c56fe47337",
          "kind": "delete",
          "state": "accepted"
        }
      }
    ]
  }
}

Power

Paused Computers. start doesn't continue a paused Computer. It returns conflict and suggests resume. While a Computer is paused, move, resize, snapshot restore, exec with its downloads and uploads, and the browser terminal are refused the same way. Its clock stands still until it resumes. stop and restart still work.

pause_reason says why it's paused: requested, storage_limit, host_storage_full, disk_error or host. If its server loses its memory, the operation fails with memory_lost, the Computer reads stopped, and start boots it fresh.

Start a Computer

POST/v1/computer/modify"action": "start"

Starts a stopped Computer. A running one is left as it is.

Body

computer string: A Computer: its name or ID.
computers string[]: Several Computers at once, instead of computer.
wait boolean or string: Wait until it finishes and return how it ended: true waits up to 10m, a duration such as 2m waits that long.

An API key needs start in its commands.
Give computers instead of computer to act on several at once.

Request

curl https://heaven.dev/v1/computer/modify \
  -H "Authorization: Bearer $HEAVEN_API_KEY" \
  --json '{"action": "start", "computer": "my-site"}'

Stop a Computer

POST/v1/computer/modify"action": "stop"

Shuts a Computer down and keeps it off. Its disk, address and settings stay.

Body

computer string: A Computer: its name or ID.
computers string[]: Several Computers at once, instead of computer.
wait boolean or string: Wait until it finishes and return how it ended: true waits up to 10m, a duration such as 2m waits that long.

An API key needs stop in its commands.
Give computers instead of computer to act on several at once.

Request

curl https://heaven.dev/v1/computer/modify \
  -H "Authorization: Bearer $HEAVEN_API_KEY" \
  --json '{"action": "stop", "computer": "my-site"}'

Restart a Computer

POST/v1/computer/modify"action": "restart"

Restarts a Computer, or starts a stopped one. Its disk and settings stay.

Body

computer string: A Computer: its name or ID.
computers string[]: Several Computers at once, instead of computer.
wait boolean or string: Wait until it finishes and return how it ended: true waits up to 10m, a duration such as 2m waits that long.

An API key needs restart in its commands.
Give computers instead of computer to act on several at once.

Request

curl https://heaven.dev/v1/computer/modify \
  -H "Authorization: Bearer $HEAVEN_API_KEY" \
  --json '{"action": "restart", "computer": "my-site"}'

200

{
  "version": 1,
  "data": {
    "request_id": "c44821a3-a72c-44d6-bf5e-c388d18265c3",
    "operation": {
      "id": "7bbd53b7-8a68-4f61-a03f-db54072e591d",
      "kind": "restart",
      "computer_id": "7cd4a3ec-7411-402c-b74b-43f6d7587ae7",
      "revision": 2,
      "state": "accepted"
    }
  }
}

Restart several

curl https://heaven.dev/v1/computer/modify \
  -H "Authorization: Bearer $HEAVEN_API_KEY" \
  --json '{"action": "restart", "computers": ["my-site", "my-shop"]}'

200

{
  "version": 1,
  "data": {
    "results": [
      {
        "computer": {"id": "8f2a8286-7123-4a64-874f-23a1c2bc61a0", "name": "my-site"},
        "operation": {"id": "dd4ccc4f-6ff5-44a8-8812-3142d067ba6f", "kind": "restart", "state": "accepted", …}
      },
      {
        "computer": {"id": "0d4e03b1-862f-4012-b14d-d7ffda5273c4", "name": "my-shop"},
        "operation": {"id": "8fa85d89-f289-404e-91c9-a1a14dab1fcc", "kind": "restart", "state": "accepted", …}
      }
    ],
    "request_id": "f42ab1d8-0af8-4418-abfc-6d85f07b4a62"
  }
}

Pause a Computer

POST/v1/computer/modify"action": "pause"

Freezes a Computer where it is, keeping its memory and processes.

Body

computer string: A Computer: its name or ID.
computers string[]: Several Computers at once, instead of computer.

An API key needs pause in its commands.
Give computers instead of computer to act on several at once.

Request

curl https://heaven.dev/v1/computer/modify \
  -H "Authorization: Bearer $HEAVEN_API_KEY" \
  --json '{"action": "pause", "computer": "my-site"}'

Resume a Computer

POST/v1/computer/modify"action": "resume"

Continues a paused Computer where it was, in the same boot.

Its memory and processes come back as they were, within milliseconds.

Body

computer string: A Computer: its name or ID.
computers string[]: Several Computers at once, instead of computer.

An API key needs resume in its commands.
Give computers instead of computer to act on several at once.

Request

curl https://heaven.dev/v1/computer/modify \
  -H "Authorization: Bearer $HEAVEN_API_KEY" \
  --json '{"action": "resume", "computer": "my-site"}'

Reinstall a Computer

POST/v1/computer/modify"action": "reset"

Replaces a Computer's disk with a fresh one from its image and runs its setup again. Without yes, it only shows what would be erased.

With a new setup_script, the pool's current script runs first. Without one, the setup it was created with runs again.

Body

computer string required: A Computer: its name or ID.
image string: Reinstall from this image instead of its own.
setup_script string: Run this setup script instead of its own; it becomes its own, which later resets run. Or - to read it from standard input. Treated as a secret and never included in errors.
yes boolean: Confirm. Without it nothing changes, and the response says what would happen.
wait boolean or string: Wait until it finishes and return how it ended: true waits up to 10m, a duration such as 2m waits that long.

An API key needs reset in its commands.
A key whose commands allow it must also allow delete.

Request

curl https://heaven.dev/v1/computer/modify \
  -H "Authorization: Bearer $HEAVEN_API_KEY" \
  --json '{"action": "reset", "computer": "my-site"}'

Name, pool and size

Rename a Computer

POST/v1/computer/modify"action": "rename"

Gives a Computer a new name. Its address, SSH login and mail address follow at once; its ID and disk stay.

Body

computer string required: A Computer: its name or ID.
name string required: Its new name.

An API key needs rename in its commands.

Request

curl https://heaven.dev/v1/computer/modify \
  -H "Authorization: Bearer $HEAVEN_API_KEY" \
  --json '{"action": "rename", "computer": "my-site", "name": "my-shop"}'

Move a Computer

POST/v1/computer/modify"action": "move"

Moves a Computer to another of your pools on the same server. A running one restarts there.

Body

computer string: A Computer: its name or ID.
computers string[]: Several Computers at once, instead of computer.
pool string required: The pool to move it to, on the same server.
yes boolean: Confirm. Without it nothing changes, and the response says what would happen.

An API key needs move in its commands.
Give computers instead of computer to act on several at once.

Request

curl https://heaven.dev/v1/computer/modify \
  -H "Authorization: Bearer $HEAVEN_API_KEY" \
  --json '{"action": "move", "computer": "my-site", "pool": "web-2"}'

Resize a Computer

POST/v1/computer/modify"action": "resize"

Gives a Computer its own vCPUs, memory or a larger disk, within its pool's, or returns it to sharing the pool's.

The Computer doesn't restart.

Body

computer string required: A Computer: its name or ID.
cpu string: vCPUs of its own, within its pool's, or pool to use the pool's again.
memory string: Memory of its own, such as 8GiB, within its pool's, or pool to use the pool's again.
disk string: A larger disk of its own, such as 50GB, up to the pool's storage; a disk only grows.
wait boolean or string: Wait until it finishes and return how it ended: true waits up to 10m, a duration such as 2m waits that long.

An API key needs resize in its commands.

Request

curl https://heaven.dev/v1/computer/modify \
  -H "Authorization: Bearer $HEAVEN_API_KEY" \
  --json '{"action": "resize", "computer": "my-site", "memory": "8GB"}'

Tag a Computer

POST/v1/computer/modify"action": "tag"

Adds tags to a Computer, or takes them off.

Body

computer string: A Computer: its name or ID.
computers string[]: Several Computers at once, instead of computer.
tags string[]: Tags to add; commas also separate them.
remove string[]: A tag to take off.

An API key needs tag in its commands.
Give computers instead of computer to act on several at once.

Request

curl https://heaven.dev/v1/computer/modify \
  -H "Authorization: Bearer $HEAVEN_API_KEY" \
  --json '{"action": "tag", "computer": "my-site", "tags": ["web"]}'

Comment on a Computer

POST/v1/computer/modify"action": "comment"

Replaces a Computer's comment. An empty one clears it.

Body

computer string: A Computer: its name or ID.
computers string[]: Several Computers at once, instead of computer.
comment string required: The new comment, one line of at most 200 bytes; an empty one clears it.

An API key needs comment in its commands.
Give computers instead of computer to act on several at once.

Request

curl https://heaven.dev/v1/computer/modify \
  -H "Authorization: Bearer $HEAVEN_API_KEY" \
  --json '{"action": "comment", "computer": "my-site", "comment": "COMMENT"}'

Snapshots

A snapshot saves the disk as it is, while the Computer keeps running. Snapshots live on the same server, so they're an undo button, not a backup. To keep a copy elsewhere, export the disk.

If copies were made from a snapshot you delete, Heaven keeps it until those copies are deleted, and it counts toward its pool's storage. ?view=snapshots lists it with kept_by_computers, and kept_by_other_copies counts copies in other accounts.

List snapshots

GET/v1/computer/?view=snapshots

Lists the snapshots of all your Computers or of one, or returns everything about one snapshot.

Query

computer string: Only this Computer's snapshots.
snapshot string: Read this snapshot in full.
sort string: Sort by size instead of newest first.

An API key needs snapshot view in its commands.

Request

curl 'https://heaven.dev/v1/computer/?view=snapshots' \
  -H "Authorization: Bearer $HEAVEN_API_KEY"

Snapshot a Computer

POST/v1/computer/modify"action": "snapshot create"

Saves a Computer's disk as it is now. A snapshot expires after 7 days unless you set another expiry.

Body

computer string: A Computer: its name or ID.
computers string[]: Several Computers at once, instead of computer.
name string: The snapshot's name: letters, digits and hyphens. Defaults to the time.
note string: A note, one line of at most 200 bytes; an empty one clears it.
expires string: How long it is kept: 1d to 365d, or never (default 7d).

An API key needs snapshot create in its commands.
Give computers instead of computer to act on several at once.

Request

curl https://heaven.dev/v1/computer/modify \
  -H "Authorization: Bearer $HEAVEN_API_KEY" \
  --json '{"action": "snapshot create", "computer": "my-site"}'

Change a snapshot

POST/v1/computer/modify"action": "snapshot edit"

Renames a snapshot or changes its note or expiry.

Body

computer string required: A Computer: its name or ID.
snapshot string required: A snapshot: its name or ID.
name string: A new name for the snapshot.
note string: A note, one line of at most 200 bytes; an empty one clears it.
expires string: How long it is kept: 1d to 365d, or never (default 7d).

An API key needs snapshot edit in its commands.

Request

curl https://heaven.dev/v1/computer/modify \
  -H "Authorization: Bearer $HEAVEN_API_KEY" \
  --json '{"action": "snapshot edit", "computer": "my-site", "snapshot": "before-upgrade"}'

Restore a snapshot

POST/v1/computer/modify"action": "snapshot restore"

Returns a Computer's disk to a snapshot and starts it.

The current disk is saved first, so a restore can be undone.

Body

computer string required: A Computer: its name or ID.
snapshot string required: A snapshot: its name or ID.

An API key needs snapshot restore in its commands.

Request

curl https://heaven.dev/v1/computer/modify \
  -H "Authorization: Bearer $HEAVEN_API_KEY" \
  --json '{"action": "snapshot restore", "computer": "my-site", "snapshot": "before-upgrade"}'

Delete snapshots

POST/v1/computer/modify"action": "snapshot delete"

Deletes one or more snapshots.

You can delete up to 100 at once.

Body

computer string: A Computer: its name or ID.
computers string[]: Several Computers at once, instead of computer.
snapshots string[] required: The snapshots to delete: names or IDs.

An API key needs snapshot delete in its commands.
Give computers instead of computer to act on several at once.

Request

curl https://heaven.dev/v1/computer/modify \
  -H "Authorization: Bearer $HEAVEN_API_KEY" \
  --json '{"action": "snapshot delete", "computer": "my-site", "snapshots": ["before-upgrade"]}'

Share a Computer with people by email or ID, with a team of your organization, or with the whole organization (whole_organization: true). A role decides what they get:

web (the default): the website only.
root: the website, plus SSH, the terminal, exec and files.
admin: everything root gets, plus the owner's changes, including delete and reset. It excludes transferring, sharing, website and support access.

A team's admins own the Computers the team owns. The organization's billing owner and admins own the organization's Computers. Other members reach those only through a share, or as the team's member-access setting allows.

POST/v1/computer/modify"action": "share add"

Gives people, a team or the whole organization access to a Computer, as web, root or admin.

Someone without an account gets an invitation, valid for 30 days, that their first sign-in accepts. The response is the share as it now stands.

Body

computer string: A Computer: its name or ID.
computers string[]: Several Computers at once, instead of computer.
users string[]: A person: email address or user ID.
team string: One of your organization's teams.
whole_organization boolean: Everyone in your organization.
role string: web (the default: the website only), root (SSH and the website) or admin (also manage it).
commands string[]: Management commands on top of the role, such as restart or domain add. It can't include exec, terminal, logs, export, transfer, sharing, website or grant-support-root.
message string: Text sent with the email invitation, at most 500 bytes.

API keys you create can't run it. Use a sign-in key or SSH.
Give computers instead of computer to act on several at once.

Request

curl https://heaven.dev/v1/computer/modify \
  -H "Authorization: Bearer $HEAVEN_API_KEY" \
  --json '{"action": "share add", "computer": "my-site", "users": ["ada@example.com"], "role": "root"}'

POST/v1/computer/modify"action": "share remove"

Removes someone's access, or lowers their role.

With role, they keep that lesser role instead of losing access.

Body

computer string: A Computer: its name or ID.
computers string[]: Several Computers at once, instead of computer.
users string[]: A person: email address or user ID.
team string: A team it is shared with.
whole_organization boolean: Everyone in your organization.
role string: Leave them this lesser role instead of nothing.

An API key needs share remove in its commands.
Give computers instead of computer to act on several at once.

Request

curl https://heaven.dev/v1/computer/modify \
  -H "Authorization: Bearer $HEAVEN_API_KEY" \
  --json '{"action": "share remove", "computer": "my-site"}'

POST/v1/computer/modify"action": "share link add"

Creates a link that gives web access to a Computer.

The link is shown once, as url.

Body

computer string required: A Computer: its name or ID.
label string: A label to recognize it by.
expires string: How long the link works: up to 365d, or never (default 30d).
max_uses string: How many people can claim it.

API keys you create can't run it. Use a sign-in key or SSH.

Request

curl https://heaven.dev/v1/computer/modify \
  -H "Authorization: Bearer $HEAVEN_API_KEY" \
  --json '{"action": "share link add", "computer": "my-site"}'

POST/v1/computer/modify"action": "share link remove"

Removes a link that gives web access to a Computer.

Nobody new can claim the link. People who already claimed it keep access until you remove them with share remove.

Body

computer string required: A Computer: its name or ID.
link string required: The link's ID (see access).

An API key needs share link remove in its commands.

Request

curl https://heaven.dev/v1/computer/modify \
  -H "Authorization: Bearer $HEAVEN_API_KEY" \
  --json '{"action": "share link remove", "computer": "my-site", "link": "LINK"}'

Transfer a Computer

POST/v1/computer/modify"action": "transfer"

Gives a Computer in your organization to a member, a team or the organization itself. Its shares are cleared, unless keep_shares keeps those the new owner could make.

Body

computer string: A Computer: its name or ID.
computers string[]: Several Computers at once, instead of computer.
user string: The member who gets it.
team string: The team that gets it.
whole_organization boolean: The organization itself gets it.
keep_shares boolean: Keep shares with people, teams and the organization that the new owner could make themselves; without it, shares are cleared.
pool string: A pool: its name or ID.

API keys you create can't run it. Use a sign-in key or SSH.
Give computers instead of computer to act on several at once.

Request

curl https://heaven.dev/v1/computer/modify \
  -H "Authorization: Bearer $HEAVEN_API_KEY" \
  --json '{"action": "transfer", "computer": "my-site"}'

Give support root access

POST/v1/computer/modify"action": "grant-support-root"

Gives Heaven's operators root access to a Computer, or takes it back.

Body

computer string required: A Computer: its name or ID.
state string required: on gives Heaven's operators root access, and off takes it away.

An API key needs grant-support-root in its commands.

Request

curl https://heaven.dev/v1/computer/modify \
  -H "Authorization: Bearer $HEAVEN_API_KEY" \
  --json '{"action": "grant-support-root", "computer": "my-site", "state": "STATE"}'

Website, domains and ports

Every Computer serves a website at https://NAME.heaven.dev, from the port its image exposes. The website is private, open only to people with access, until you make it public.

To give a Computer one of your static addresses (not offered yet) for all its traffic in and out, use ip attach with computer. ip detach takes it off.

Set who reaches the website

POST/v1/computer/modify"action": "website"

Makes a Computer's website public or private, and sets the port it is served from. With neither, returns the current settings.

It returns the website's settings: computer, url, public, port, and default_port, which is the port the image exposes.

Body

computer string required: A Computer: its name or ID.
public boolean: With true, anyone can visit. With false, only people with access can.
port string: The port the website is served from. 0 goes back to the image's port.

An API key needs website in its commands.

Request

curl https://heaven.dev/v1/computer/modify \
  -H "Authorization: Bearer $HEAVEN_API_KEY" \
  --json '{"action": "website", "computer": "my-site"}'

200 With "public": true

{
  "version": 1,
  "data": {
    "updated": true,
    "computer": "my-site",
    "url": "https://my-site.heaven.dev/",
    "public": true,
    "port": 0,
    "default_port": 8080
  }
}

List domains

GET/v1/computer/?view=domains

Lists the verified website domains of all your Computers, or of one.

Query

computer string: A Computer: its name or ID.

An API key needs domain view in its commands.

Request

curl 'https://heaven.dev/v1/computer/?view=domains' \
  -H "Authorization: Bearer $HEAVEN_API_KEY"

Add a domain

POST/v1/computer/modify"action": "domain add"

Serves a Computer's website at your own domain. The domain's DNS must point at the Computer and have its verification record.

Before you add the domain, point its DNS at NAME.heaven.dev, and add a _heaven.DOMAIN TXT record holding heaven=COMPUTER_ID. If a record is missing, the error names it.

Body

computer string required: A Computer: its name or ID.
domain string required: A domain name you control, such as www.example.com.
wildcard boolean: Also serve every name under the domain (*.DOMAIN).

An API key needs domain add in its commands.

Request

curl https://heaven.dev/v1/computer/modify \
  -H "Authorization: Bearer $HEAVEN_API_KEY" \
  --json '{"action": "domain add", "computer": "my-site", "domain": "shop.example.com"}'

Remove a domain

POST/v1/computer/modify"action": "domain remove"

Stops serving a Computer's website at one of your domains.

Body

computer string required: A Computer: its name or ID.
domain string required: A domain name you control, such as www.example.com.

An API key needs domain remove in its commands.

Request

curl https://heaven.dev/v1/computer/modify \
  -H "Authorization: Bearer $HEAVEN_API_KEY" \
  --json '{"action": "domain remove", "computer": "my-site", "domain": "shop.example.com"}'

List public ports

GET/v1/computer/?view=ports

Lists the public TCP ports of all your Computers or of one, and each pool's allowance.

Query

computer string: A Computer: its name or ID.

An API key needs port view in its commands.

Request

curl 'https://heaven.dev/v1/computer/?view=ports' \
  -H "Authorization: Bearer $HEAVEN_API_KEY"

Publish a port

POST/v1/computer/modify"action": "port add"

Publishes one of a Computer's TCP ports to the internet, at a public port Heaven picks.

It returns the public port as address: ADDRESS:PORT on a static address, or NAME.heaven.dev:PORT otherwise.

Body

computer string required: A Computer: its name or ID.
guest_port string required: The Computer's TCP port to publish.

API keys you create can't run it. Use a sign-in key or SSH.

Request

curl https://heaven.dev/v1/computer/modify \
  -H "Authorization: Bearer $HEAVEN_API_KEY" \
  --json '{"action": "port add", "computer": "my-site", "guest_port": "GUEST_PORT"}'

Close a port

POST/v1/computer/modify"action": "port remove"

Closes a public TCP port. Name either the public port or the Computer's port.

Body

computer string required: A Computer: its name or ID.
port string required: The public port, or the Computer's port it publishes.

An API key needs port remove in its commands.

Request

curl https://heaven.dev/v1/computer/modify \
  -H "Authorization: Bearer $HEAVEN_API_KEY" \
  --json '{"action": "port remove", "computer": "my-site", "port": "PORT"}'

Email

Read mail settings

GET/v1/computer/?view=mail

Returns whether a Computer receives mail, and whom it can send mail to.

Query

computer string required: A Computer: its name or ID.

An API key needs mail view in its commands.

Request

curl 'https://heaven.dev/v1/computer/?computer=my-site&view=mail' \
  -H "Authorization: Bearer $HEAVEN_API_KEY"

Set mail

POST/v1/computer/modify"action": "mail"

Turns receiving mail at the Computer's address on or off, and sets whom the Computer can send mail to.

A Computer receives mail at NAME.heaven.dev. It sends mail from inside itself through Heaven's mail API, with no credential:

Inside the Computer

curl http://169.254.169.254/gateway/email/send \
  -H 'Content-Type: application/json' -H 'Idempotency-Key: build-123' \
  -d '{"to":"alex@example.com","subject":"Build complete","body":"All green."}'
curl http://169.254.169.254/gateway/email/status/OPERATION_ID

Sending returns an operation ID once the message is accepted. If the response is lost, send it again with the same Idempotency-Key, never a new one. The message's status goes from queued through provider_accepted to delivered, or ends as refused, expired or unknown. reply_policy decides whom the Computer can send to, and mail to anyone else is refused.

Body

computer string required: A Computer: its name or ID.
state string: With on, receive mail at NAME@ the domain. With off, refuse mail, and permanently delete its reply threads and unsubscribe everyone allowed to write to it.
reply_policy string: Whom the Computer can send mail to: all (the default: its owner, team members, those given access, and people who wrote to it while it receives mail), known (its owner, team members and those given access), owner (its owner only) or none (it sends no mail).
yes boolean: Confirm turning mail off when that deletes reply threads or subscriptions. Without it, off changes nothing and says what it would remove.

An API key needs mail in its commands.

Request

curl https://heaven.dev/v1/computer/modify \
  -H "Authorization: Bearer $HEAVEN_API_KEY" \
  --json '{"action": "mail", "computer": "my-site"}'

Read a message's delivery

GET/v1/computer/?operation=…

Returns whether a message a Computer sent was delivered, using the ID returned when it was sent.

Query

computer string required: A Computer: its name or ID.
operation string required: The ID returned when the Computer sent it.

An API key needs mail status in its commands.

Request

curl 'https://heaven.dev/v1/computer/?computer=my-site&operation=OPERATION' \
  -H "Authorization: Bearer $HEAVEN_API_KEY"

Computers

Read

List or get Computers

Query

Each Computer in the list

Read usage

Query

Read the boot console

Query

Open the browser terminal

Query

Open the desktop

Query

Read who has access

Query

Create and delete

Create a Computer

Body

Delete Computers

Body

Power

Start a Computer

Body

Stop a Computer

Body

Restart a Computer

Body

Pause a Computer

Body

Resume a Computer

Body

Reinstall a Computer

Body

Name, pool and size

Rename a Computer

Body

Move a Computer

Body

Resize a Computer

Body

Tag a Computer

Body

Comment on a Computer

Body

Snapshots

List snapshots

Query

Snapshot a Computer

Body

Change a snapshot

Body

Restore a snapshot

Body

Delete snapshots

Body

Sharing

Share a Computer

Body

Stop sharing a Computer

Body

Create a share link

Body

Remove a share link

Body

Transfer a Computer

Body

Give support root access

Body

Website, domains and ports

Set who reaches the website

Body

List domains

Query

Add a domain

Body

Remove a domain

Body

List public ports

Query

Publish a port