# Pools

Source: https://heaven.dev/docs/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](https://heaven.dev/docs/pools#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](https://heaven.dev/docs/account#static-addresses) 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:

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

200:

```json
{
  "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:

```sh
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`](https://heaven.dev/docs/account#capacity-buy), [`capacity resize`](https://heaven.dev/docs/account#capacity-resize), [`capacity switch`](https://heaven.dev/docs/account#capacity-switch) and [`capacity release`](https://heaven.dev/docs/account#capacity-release), which act in your personal account. For an organization, buy it with `buy` when you [create a pool](https://heaven.dev/docs/pools#create).

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](https://heaven.dev/docs/account#billing).

If a monthly renewal fails, its pools keep running for 7 days while Stripe retries the payment, then stop. Pools marked [`stop-last`](https://heaven.dev/docs/pools#stop-last) keep running longest. On day 14, the plan is released and its pools are deleted. To pay before then, use [`billing pay`](https://heaven.dev/docs/account#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:

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

200:

```json
{
  "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:

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

200:

```json
{
  "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`](https://heaven.dev/docs/account#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](https://heaven.dev/docs/pools#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:

```sh
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:

```json
{
  "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:

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

Copy a pool snapshot:

```json
{"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](https://heaven.dev/docs/account#capacity-release). 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:

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

200:

```json
{
  "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](https://heaven.dev/docs/pools#capacity) under it as bought.

### Start a pool

`POST /v1/pool/modify` with `"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:

```sh
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` with `"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:

```sh
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` with `"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:

```sh
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` with `"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:

```sh
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` with `"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:

```sh
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` with `"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](https://heaven.dev/docs/pools#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`](https://heaven.dev/docs/account#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:

```sh
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:

```json
{
  "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` with `"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:

```sh
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` with `"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](https://heaven.dev/docs/operations#groups) 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:

```sh
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:

```json
{
  "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` with `"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](https://heaven.dev/docs/operations#groups) 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:

```sh
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` with `"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:

```sh
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` with `"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:

```sh
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](https://heaven.dev/docs/operations#groups).

### 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:

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

### Snapshot a pool

`POST /v1/pool/modify` with `"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:

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

200:

```json
{
  "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` with `"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:

```sh
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` with `"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:

```sh
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` with `"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:

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

### Share a pool snapshot

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

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

They can [copy](https://heaven.dev/docs/pools#create) 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:

```sh
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"]}'
```

### Stop sharing a pool snapshot

`POST /v1/pool/modify` with `"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:

```sh
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"]}'
```

## Sharing

### Share a pool

`POST /v1/pool/modify` with `"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:

```sh
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"}'
```

### End a pool share

`POST /v1/pool/modify` with `"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:

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