Endpoints

Pools

You buy capacity on a server and divide it into pools. A pool's Computers share its CPU, memory and storage.

You pay for capacity; pools themselves cost nothing. Every Computer in a pool can use the whole pool, so a busy Computer borrows what idle ones leave. Idle Computers keep running with their memory moved aside, and come back on their own when used.

The account's owner, or an organization's billing owner and admins, manage its pools.

Read with GET /v1/pool/. Change a pool with POST /v1/pool/modify, naming the pool and one action. The action is the command name without its pool prefix: pool stop is "stop".

Your pools

List pools

GET/v1/pool/

Lists your pools with their sizes and limits, or returns one pool with everything about it you can read.

Each pool comes with its ID, account, size and power. Without a view, the response also includes every part you can read: usage, snapshots, plans and capacity.

A pool shared with you returns only its usage. Its account's snapshots, plans and capacity are withheld, and the pool has no checkout_url.

Query

pool string: Read one pool, by name or ID, including one shared with you. The response adds pool, with its Computers, recent operations and, for its managers, its setup_script. Through a share, you see only the Computers you created.
parts string[]: Only this part of the JSON response: usage, snapshots, plans or capacity, or none for no parts. Repeat for several. Without it, every part (MCP tools: none).
organization string: Act in this organization (its name or ID) instead of your personal account.

Each pool

power string: running, paused or stopped.
allowance object: Its size and limits: vcpus, memory_bytes, swap_bytes, disk_allowance_bytes, storage_limit_bytes (where writes stop, at 120%), max_computers (50 a unit), lend_bytes and margin_bytes, and max_published_ports when it has public ports of its own. lend_bytes and margin_bytes are the memory it can borrow above its own: its share of what your account has on the server.
limits object: Your pool's storage_bytes (its share of your storage on the server), account_ports (the public ports your pools there share, 4 plus one a unit, at most 20) and any overrides Heaven set for it.
billing object: kind is slice, because its capacity is what you pay for. A pool waiting for its monthly capacity's first payment has a checkout_url.
static_address string: The static address attached to it, if any. ip attach and ip detach with pool change it.
stale boolean: Whether its measurements are old. Treat old usage as unknown.

An API key needs pool view in its commands.

Request

curl 'https://heaven.dev/v1/pool/?pool=web' \
  -H "Authorization: Bearer $HEAVEN_API_KEY"

200

{
  "version": 1,
  "data": {
    "pools": [
      {
        "id": "pool-0eba2d9abc704c54",
        "account_id": "5e209a1c-a2bf-4dfd-867d-38eab3ae8cf9",
        "name": "web",
        "power": "running",
        "billing": {"kind": "slice", "plan": 0},
        "allowance": {
          "vcpus": 2,
          "memory_bytes": 8589934592,
          "swap_bytes": 17179869184,
          "max_computers": 50,
          "disk_allowance_bytes": 100000000000,
          "storage_limit_bytes": 120000000000,
          "lend_bytes": 4294967296,
          "margin_bytes": 1073741824
        },
        "limits": {"storage_bytes": 100000000000, "account_ports": 5, "overrides": {}},
        "stale": false
      }
    ],
    "pool": {
      "computers": [
        {"id": "8f2a8286-7123-4a64-874f-23a1c2bc61a0", "name": "my-site", "power": "running"}
      ],
      "operations": []
    },
    "usage": {…},
    "snapshots": {"pool_snapshots": []},
    "plans": {…},
    "capacity": {…}
  }
}

Read pool usage

GET/v1/pool/?view=usage

Returns CPU, memory and traffic history over 24 hours, 7 days or 30 days, for each pool or one.

Query

pool string: Only this pool.
range string: The span of history: 24h, 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.
organization string: Act in this organization (its name or ID) instead of your personal account.

An API key needs pool usage in its commands.

Request

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

Capacity

A purchase is one plan from ?view=plans on one server. A plan marked no_room there has no server with space for it right now, so buying it is refused. Try a smaller plan, or again later. Your pools on that server share everything you bought there. Buy, change and release capacity with capacity buy, capacity resize, capacity switch and capacity release, which act in your personal account. For an organization, buy it with buy when you create a pool.

You pay for a purchase as bought, whatever its pools do. A monthly purchase is a line on your account's subscription, and an hourly one is paid at its plan's rate from your wallet. Resizing, stopping or deleting a pool doesn't change what you pay. Storage is never charged beyond your plans.

A pool is made of whole units of 2 vCPUs and 8 GB. Its storage is its share of yours on the server: a pool that takes some of your free units gets the same share of your free storage, at least 100 GB a unit, and gives it back when it shrinks.

A pool can store up to 120% of its own storage, counting files and snapshots together. Past that, its Computers' disks read as full until you delete files or snapshots. At 150%, Computers that keep writing are paused.

Your pools on a server share its public ports: 4, plus one for each unit your pools there hold, up to 20. Plans 5 and 6 need approval, so ask support.

When your wallet reaches $0 with no automatic top-up, or an automatic top-up fails, your pools keep running for a 24-hour grace period. Then:

hourly pools stop and can't be started, but you can still sign in, delete Computers and export their disks;
their files are kept for 7 days at no charge, then deleted;
your next top-up pays off the negative balance first, and pools come back once their first hour is covered.

Add money, or turn on automatic top-up, from billing.

If a monthly renewal fails, its pools keep running for 7 days while Stripe retries the payment, then stop. Pools marked stop-last keep running longest. On day 14, the plan is released and its pools are deleted. To pay before then, use billing pay. A plan you release ends when its paid period ends.

List plans

GET/v1/pool/?view=plans

Lists the six plans, with their RAM, vCPUs, storage, monthly prices and hourly rates.

An API key needs plan view in its commands.

Request

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

200

{
  "version": 1,
  "data": {
    "plans": [
      {
        "plan": 1,
        "units": 1,
        "vcpus": 2,
        "memory_bytes": 8589934592,
        "storage_bytes": 100000000000,
        "storage_limit_bytes": 120000000000,
        "egress_bytes": 500000000000,
        "max_computers": 50,
        "public_ports": 5,
        "monthly_micros": 20000000,
        "hourly_micros": 41096,
        "hourly_passes_monthly_hours": 487
      },
      …
    ],
    "egress_micros_per_gb": 50000
  }
}

Read your capacity

GET/v1/pool/?view=capacity

Returns each purchase, and for each server, the memory you bought, how much your pools use and how much is free.

Query

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

Response

purchases array: Each purchase, with its id, server, region (where the server is, such as montreal; left out until Heaven sets it), plan, kind, size and state. The state is active, pending, out_of_funds, unpaid, or ending for a released monthly plan, which also has ends_at.
servers array: For each server, the memory, vCPUs and storage you bought, and how much of each your pools hold.
storage array: For each server, the storage included, the point where your pools' writes stop together (stop_bytes), and what they store.

An API key needs capacity view in its commands.

Request

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

200

{
  "version": 1,
  "data": {
    "purchases": [
      {
        "id": "cap-5e809142ece64cc3",
        "server": "h-ff6cf959-8d63-463c-8bd8-ef48c9dedc0b",
        "region": "montreal",
        "plan": 2,
        "kind": "hourly",
        "memory_bytes": 17179869184,
        "vcpus": 4,
        "storage_bytes": 250000000000,
        "created_at": "2026-11-02T13:13:31Z",
        "state": "active"
      }
    ],
    "servers": [
      {
        "server": "h-ff6cf959-8d63-463c-8bd8-ef48c9dedc0b",
        "region": "montreal",
        "memory_bought_bytes": 17179869184,
        "memory_allocated_bytes": 8589934592,
        "vcpus_bought": 4,
        "vcpus_allocated": 2,
        "storage_bought_bytes": 250000000000,
        "storage_allocated_bytes": 125000000000
      }
    ],
    "storage": [
      {
        "server": "h-ff6cf959-8d63-463c-8bd8-ef48c9dedc0b",
        "region": "montreal",
        "included_bytes": 250000000000,
        "stop_bytes": 168750000000,
        "used_bytes": 0
      }
    ]
  }
}

Create and delete

Create a pool

POST/v1/pool/create

Makes a pool from capacity you have, from a plan it buys, or as a copy of a pool or pool snapshot.

You can make a pool in three ways, shown below. With dry_run, each one shows the pool it would make and what it would charge, and changes nothing. A request never makes a pool twice for one Idempotency-Key header (--request-id in the CLI). Sent again, it returns the first response, dry run or not.

From	Fields	Does
Capacity you have	`memory`, `server`; `dry_run`	Takes free capacity, at no charge. `memory` is 8GB or more, in steps of 8GB. Each step is a unit of 2 vCPUs and 8 GB, with its share of your free storage on the server.
A new purchase	`buy`: `plan`, `monthly` \| `hourly`; `offer`, `server`; `dry_run`	Buys capacity, as `capacity buy` does, and makes a pool of all of it.
A copy	`copy`: `pool`, `snapshot`; `memory`; `dry_run`	Copies a pool, or one of its pool snapshots (yours or shared with you), into a new pool from free capacity on its server. `memory` defaults to the source's, in whole units. To copy your own pool, you need ownership or root access on each Computer. Any Computer you lack it on is refused in the result, and in the dry run's result too. A copy can't take `buy`, `offer`, `monthly`, `hourly` or `server`.

Body

name string

The pool's name: up to 32 lowercase letters, digits and hyphens, unique in its account.

buy object

plan string required: Buy this plan (1 to 6, see plan view) and make a pool of all of it.
monthly boolean: Pay monthly (the default).
hourly boolean: Pay by the minute from your wallet.

offer string

An offer's code or ID.

dry_run boolean

Change nothing, and show what it would do and charge.

memory string

Memory: 8GiB or more, in steps of 8GiB. Each step is a unit of 2 vCPUs and 8 GiB, and the vCPUs and storage follow.

server string

The server to make it on (see capacity view).

copy object

pool string required: Copy this pool into the new one, from free capacity on its server.
snapshot string: Copy this pool snapshot instead (yours or shared with you).

organization string

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

API keys you create can't run it. Use a sign-in key or SSH.
Retry it safely with an Idempotency-Key header.

Request

curl https://heaven.dev/v1/pool/create \
  -H "Authorization: Bearer $HEAVEN_API_KEY" \
  -H "Idempotency-Key: pool-create-api" \
  --json '{"name": "api", "memory": "8GB"}'

200

{
  "version": 1,
  "data": {
    "pool": "api",
    "id": "pool-7f26a533766b4df2",
    "kind": "slice",
    "host": "h-ff6cf959-8d63-463c-8bd8-ef48c9dedc0b",
    "memory_bytes": 8589934592,
    "vcpus": 2,
    "storage_bytes": 125000000000
  }
}

Buy and create at once

{"name": "api", "buy": {"plan": 1, "hourly": true}}

Copy a pool snapshot

{"name": "web-copy", "copy": {"pool": "web", "snapshot": "nightly"}}

Delete a pool

POST/v1/pool/delete

Deletes a pool with its Computers and their files.

Its units and storage are freed for your other pools on its server. You keep paying for the capacity under it until you release it. The response's billed lists what you still pay for on that server, by the IDs capacity release takes.

Body

pool string required: A pool: its name or ID.
yes boolean: Confirm with true.
organization string: Act in this organization (its name or ID) instead of your personal account.

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

Request

curl https://heaven.dev/v1/pool/delete \
  -H "Authorization: Bearer $HEAVEN_API_KEY" \
  --json '{"pool": "web", "yes": true}'

200

{
  "version": 1,
  "data": {
    "pool": "web",
    "computers": 0,
    "capacity": {"purchase": "cap-…", "kind": "hourly", "hour_before_micros": …, "hour_after_micros": 0, "released": true},
    "billed": []
  }
}

Power

Starting, stopping, pausing and resuming a pool doesn't change what you pay. You pay for the capacity under it as bought.

Start a pool

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

Starts a stopped pool, taking its size back from free capacity on its server.

You can't start it when its server has no room, and the error names the pools using that room. You also can't start it while its capacity is lapsed or unpaid.

Body

pool string required: A pool: its name or ID.
organization string: Act in this organization (its name or ID) instead of your personal account.

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

Request

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

Stop a pool

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

Shuts down a pool's Computers and keeps their files. Its memory and vCPUs become free for your other pools on that server.

It keeps its storage.

Body

pool string required: A pool: its name or ID.
organization string: Act in this organization (its name or ID) instead of your personal account.

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

Request

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

Pause a pool

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

Freezes a pool's running Computers where they are, keeping their memory and processes.

Body

pool string required: A pool: its name or ID.
organization string: Act in this organization (its name or ID) instead of your personal account.

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

Request

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

Resume a pool

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

Continues a paused pool's Computers where they were.

Body

pool string required: A pool: its name or ID.
organization string: Act in this organization (its name or ID) instead of your personal account.

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

Request

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

Keep a pool running longest

POST/v1/pool/modify"action": "stop-last"

Marks a pool to stop last when unpaid capacity stops your pools.

As many pools keep running as your remaining capacity holds: those marked on first, then the oldest. The notice names the pools that stopped.

Body

pool string required: A pool: its name or ID.
state string required: on or off.
organization string: Act in this organization (its name or ID) instead of your personal account.

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

Request

curl https://heaven.dev/v1/pool/modify \
  -H "Authorization: Bearer $HEAVEN_API_KEY" \
  --json '{"action": "stop-last", "pool": "web", "state": "on"}'

Size and shape

Resize a pool

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

Changes a pool's size in whole units of 8 GB and 2 vCPUs: within capacity you have on its server, or by buying a plan for it.

You can resize a pool in two ways. A request never resizes or buys twice for one Idempotency-Key header (--request-id in the CLI). Sent again, it returns the first response.

From	Fields	Does
Capacity you have	`memory`	Grows or shrinks the pool in whole units, as in create, at no charge. More units come from free capacity on its server, with their share of your free storage. Fewer units give back their share of the pool's storage.
A new purchase	`buy`: `plan`, `monthly` \| `hourly`; `offer`; `dry_run`	Buys capacity on the pool's server, as `capacity buy` does, and grows the pool by all of it.

A pool you buy a plan for grows when the plan is paid. By the hour, or on a saved card, that is at once. When the response has a checkout_url or an invoice_url, the pool grows once that page is paid, and you send nothing more. A page left unpaid changes nothing. With dry_run, the response shows the size the pool would grow to and what it would charge, and nothing changes.

A stopped pool grows and stays stopped. You can't resize a paused pool, and a plan for one isn't bought. You also can't resize a pool if it would then hold more Computers, public ports or files than its new size allows. For files, the limit is 120% of the storage it keeps.

Body

pool string required

A pool: its name or ID.

memory string

New memory: 8GiB or more, in steps of 8GiB. Each step is a unit of 2 vCPUs and 8 GiB, and the vCPUs and storage follow.

buy object

plan string required: Buy this plan (1 to 6, see plan view) on the pool's server and grow the pool by all of it.
monthly boolean: Pay monthly (the default).
hourly boolean: Pay by the minute from your wallet.

offer string

An offer's code or ID.

dry_run boolean

With buy: change nothing, and show the size the pool would grow to and what it would charge.

organization string

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

API keys you create can't run it. Use a sign-in key or SSH.
Retry it safely with an Idempotency-Key header.

Request

curl https://heaven.dev/v1/pool/modify \
  -H "Authorization: Bearer $HEAVEN_API_KEY" \
  -H "Idempotency-Key: resize-web" \
  --json '{"action": "resize", "pool": "web", "memory": "16GB"}'

200

{
  "version": 1,
  "data": {
    "pool": "web",
    "id": "pool-7f26a533766b4df2",
    "host": "h-ff6cf959-8d63-463c-8bd8-ef48c9dedc0b",
    "memory_bytes": 17179869184,
    "vcpus": 4,
    "storage_bytes": 250000000000
  }
}

Rename a pool

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

Gives a pool a new name. Its Computers, address and capacity stay.

Body

pool string required: A pool: its name or ID.
name string required: The pool's new name: 1 to 32 letters, digits and hyphens, in any case (stored lowercase), unique in your account.
organization string: Act in this organization (its name or ID) instead of your personal account.

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

Request

curl https://heaven.dev/v1/pool/modify \
  -H "Authorization: Bearer $HEAVEN_API_KEY" \
  --json '{"action": "rename", "pool": "web", "name": "NAME"}'

Split a pool

POST/v1/pool/modify"action": "split"

Gives part of a pool to a new pool on the same server and moves the Computers you name into it.

Whole units, with their share of the pool's storage, go to the new pool, and the named Computers restart there. The original pool keeps at least one unit. What you pay doesn't change.

If either pool would end up with more Computers, ports or files than its size allows, the whole split is refused.
The new pool gets the original's shares, but not its address, setup script or snapshots.
Moving Computers off the pool's static address needs yes.

It returns an operation group with each Computer's move.

Body

pool string required: A pool: its name or ID.
name string: The new pool's name; without one it is named after your name or organization's and its size, as pool create names it.
memory string: The memory the new pool takes from this one.
computers string[]: A Computer to move into the new pool.
yes boolean: Confirm. Without it nothing changes, and the response says what would happen.
organization string: Act in this organization (its name or ID) instead of your personal account.

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

Request

curl https://heaven.dev/v1/pool/modify \
  -H "Authorization: Bearer $HEAVEN_API_KEY" \
  --json '{"action": "split", "pool": "web", "name": "web-2", "memory": "8GB", "computers": ["my-site"]}'

200

{
  "version": 1,
  "data": {
    "pool": "web-2",
    "id": "pool-324a6ef5ce57440b",
    "from": "web",
    "memory_bytes": 8589934592,
    "vcpus": 2,
    "storage_bytes": 125000000000,
    "operation": {
      "id": "e352229f-02d1-42e7-9ba4-335ad609ab56",
      "kind": "pool split",
      "state": "accepted",
      "operations": [{"kind": "move", "state": "accepted", …}],
      …
    },
    "results": [
      {
        "computer": {"id": "0f6a3b61-96b9-475d-bd12-372d5e1b5b33", "name": "my-site"},
        "operation": {"id": "86289b67-bbd8-4a7a-86e1-228f084ebfad", "kind": "move", "state": "accepted", …}
      }
    ]
  }
}

Combine pools

POST/v1/pool/modify"action": "combine"

Moves every Computer of another pool into this one, then deletes the other pool.

The moved Computers restart. Then this pool takes the other pool's units, and the other pool is deleted with its address, shares and snapshots. What you pay doesn't change.

If this pool, with both pools' units, would hold more Computers, ports or files than its size allows, the whole combine is refused before anything moves.
Without yes, ended_shares says who would lose access, and changes says what else would change.
A member who has pool delete withheld can't combine pools either.

It returns an operation group with each Computer's move.

Body

pool string required: The pool that receives the Computers.
with string required: The pool whose Computers move in; it is then deleted.
yes boolean: Confirm. Without it nothing changes, and the response says what would happen.
organization string: Act in this organization (its name or ID) instead of your personal account.

API keys you create can't run it. Use a sign-in key or SSH.
A key whose commands allow it must also allow pool delete.

Request

curl https://heaven.dev/v1/pool/modify \
  -H "Authorization: Bearer $HEAVEN_API_KEY" \
  --json '{"action": "combine", "pool": "web", "with": "WITH"}'

Defaults

Set pool defaults

POST/v1/pool/modify"action": "defaults set"

Sets what every Computer created in the pool gets: a setup script that runs first, and vCPUs or a disk of its own.

The pool's setup script runs at first boot, before the Computer's own. If it fails, the Computer's own script doesn't run. Copies and restores run neither script.

Body

pool string required: A pool: its name or ID.
setup_script string: The script. Treated as a secret and never included in errors.
cpu string: vCPUs each new Computer gets when it's created without its own.
disk string: A disk of its own, such as 20GB, for each new Computer created without one.
organization string: Act in this organization (its name or ID) instead of your personal account.

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

Request

curl https://heaven.dev/v1/pool/modify \
  -H "Authorization: Bearer $HEAVEN_API_KEY" \
  --json '{"action": "defaults set", "pool": "web"}'

Clear pool defaults

POST/v1/pool/modify"action": "defaults clear"

Removes the pool's defaults, or only the ones you name.

Body

pool string required: A pool: its name or ID.
default string[]: Clear only these defaults: setup-script, cpu or disk.
organization string: Act in this organization (its name or ID) instead of your personal account.

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

Request

curl https://heaven.dev/v1/pool/modify \
  -H "Authorization: Bearer $HEAVEN_API_KEY" \
  --json '{"action": "defaults clear", "pool": "web"}'

Pool snapshots

A pool snapshot is one name for a snapshot of each of the pool's Computers, taken one after another. Each Computer is accepted or refused on its own, and a change returns an operation group.

List pool snapshots

GET/v1/pool/?view=snapshots

Lists the pool snapshots you can copy from, yours and those shared with you, or returns one with each Computer's snapshot.

Query

pool string: Only this pool's snapshots.
snapshot string: Read this one, with each Computer's snapshot.
shared boolean: With true, only those shared with you. With false, only yours.
organization string: Act in this organization (its name or ID) instead of your personal account.

An API key needs pool snapshot view in its commands.

Request

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

Snapshot a pool

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

Snapshots each of a pool's Computers under one name.

It's refused if a Computer already has a snapshot with that name.

Body

pool string required: A pool: its name or ID.
name string: The snapshot's name. 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).
organization string: Act in this organization (its name or ID) instead of your personal account.

An API key needs pool snapshot create in its commands.

Request

curl https://heaven.dev/v1/pool/modify \
  -H "Authorization: Bearer $HEAVEN_API_KEY" \
  --json '{"action": "snapshot create", "pool": "web", "name": "nightly", "expires": "30d"}'

200

{
  "version": 1,
  "data": {
    "request_id": "9d0969ef-1823-4b84-be89-3ecee74f1ddd",
    "operation": {
      "id": "4baa2b68-1bd1-4cd2-b965-c9eb9513de73",
      "kind": "pool snapshot create",
      "state": "accepted",
      "pool_id": "pool-a84a2847cd584a0c",
      "subject": "nightly",
      "operations": [
        {"id": "66778689-c39f-403e-a841-a8c445fd5bf0", "kind": "snapshot", "state": "accepted", …},
        {"id": "6bb22923-e7db-4bef-b92f-7091ed745ba0", "kind": "snapshot", "state": "accepted", …}
      ],
      "created_at": "2026-11-02T13:15:16Z"
    },
    "pool_snapshot": {
      "id": "030765c7-fe5d-4dcb-b0d2-a3062849361e",
      "name": "nightly",
      "pool": {"id": "pool-a84a2847cd584a0c", "name": "web"}
    },
    "results": [
      {
        "computer": {"id": "317ff25b-84a8-4112-815e-d79f0ff6d5b0", "name": "my-site"},
        "snapshot": {"id": "0f561eb7-e483-42c1-9963-87d9f60d9b32", "name": "nightly"},
        "operation": {"id": "66778689-c39f-403e-a841-a8c445fd5bf0", "kind": "snapshot", "state": "accepted", …}
      },
      …
    ]
  }
}

Change a pool snapshot

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

Renames a pool snapshot or changes its note or expiry.

The change applies to the snapshot on every Computer.

Body

pool string required: A pool: 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).
organization string: Act in this organization (its name or ID) instead of your personal account.

An API key needs pool snapshot edit in its commands.

Request

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

Restore a pool snapshot

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

Returns each Computer in a pool snapshot to its snapshot. Computers created since are left alone.

deleted_since names the Computers in the snapshot that have since been deleted.

Body

pool string required: A pool: its name or ID.
snapshot string required: A snapshot: its name or ID.
organization string: Act in this organization (its name or ID) instead of your personal account.

An API key needs pool snapshot restore in its commands.

Request

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

Delete a pool snapshot

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

Deletes a pool snapshot, which is each Computer's snapshot in it.

Body

pool string required: A pool: its name or ID.
snapshot string required: A snapshot: its name or ID.
organization string: Act in this organization (its name or ID) instead of your personal account.

An API key needs pool snapshot delete in its commands.

Request

curl https://heaven.dev/v1/pool/modify \
  -H "Authorization: Bearer $HEAVEN_API_KEY" \
  --json '{"action": "snapshot delete", "pool": "web", "snapshot": "before-upgrade"}'

POST/v1/pool/modify"action": "snapshot share add"

Lets people outside your account copy a pool snapshot into their own account.

They can copy it, and nothing else. Each person gets an email.

Body

pool string required: A pool: its name or ID.
snapshot string required: A snapshot: its name or ID.
users string[] required: A person outside your account: email or user ID.
message string: Text sent with the email invitation, at most 500 bytes.
organization string: Act in this organization (its name or ID) instead of your personal account.

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

Request

curl https://heaven.dev/v1/pool/modify \
  -H "Authorization: Bearer $HEAVEN_API_KEY" \
  --json '{"action": "snapshot share add", "pool": "web", "snapshot": "before-upgrade", "users": ["ada@example.com"]}'

POST/v1/pool/modify"action": "snapshot share remove"

Stops sharing a pool snapshot with people. Copies they made stay theirs.

Body

pool string required: A pool: its name or ID.
snapshot string required: A snapshot: its name or ID.
users string[] required: A person it was shared with.
organization string: Act in this organization (its name or ID) instead of your personal account.

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

Request

curl https://heaven.dev/v1/pool/modify \
  -H "Authorization: Bearer $HEAVEN_API_KEY" \
  --json '{"action": "snapshot share remove", "pool": "web", "snapshot": "before-upgrade", "users": ["ada@example.com"]}'

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

Lets people, another organization or one of its teams create and run their own Computers in a pool.

They manage the Computers they create, with the access role and commands give them. Your account owns those Computers. Name a team as ORGANIZATION@TEAM.

Body

pool string required: A pool: its name or ID.
users string[]: A person outside the pool's account: email or user ID.
with_organization string: Another organization: its name.
team string: One of another organization's teams: ORGANIZATION@TEAM.
role string: What they have on the Computers they create: root (the default), web or admin.
commands string[]: A command they can run on those Computers.
organization string: Act in this organization (its name or ID) instead of your personal account.

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

Request

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

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

Ends a pool share. The people it was shared with lose access to the Computers they made there, which stay in the pool's account.

Body

pool string required: A pool: its name or ID.
users string[]: A person it is shared with.
with_organization string: Another organization: its name.
team string: A team it is shared with: ORGANIZATION@TEAM.
organization string: Act in this organization (its name or ID) instead of your personal account.

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

Request

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

Pools

Your pools

List pools

Query

Each pool

Read pool usage

Query

Capacity

List plans

Read your capacity

Query

Response

Create and delete

Create a pool

Body

Delete a pool

Body

Power

Start a pool

Body

Stop a pool

Body

Pause a pool

Body

Resume a pool

Body

Keep a pool running longest

Body

Size and shape

Resize a pool

Body

Rename a pool

Body

Split a pool

Body

Combine pools

Body

Defaults

Set pool defaults

Body

Clear pool defaults

Body

Pool snapshots

List pool snapshots

Query

Snapshot a pool

Body

Change a pool snapshot

Body

Restore a pool snapshot

Body

Delete a pool snapshot

Body

Share a pool snapshot

Body

Stop sharing a pool snapshot

Body

Sharing

Share a pool

Body

End a pool share

Body