# Create a pool

URL: https://heaven.dev/docs/reference/pools/create
Updated: 2026-11-21

Create a pool that shares CPU, RAM and storage across its Computers. Set `memory` to use capacity you already have. Set `units` to use unused capacity first and buy any shortfall, or `buy.plan` to buy a whole plan for the pool. Use `copy.pool` to copy a pool from its current disks or from `copy.snapshot` into unused capacity on the same server.

`POST /v1/pool/create`

## Parameters

- `name` (string): Pool name, unique in your account regardless of case. Generated if omitted; starts with default when using `units`.
- `buy` (object)
  - `plan` (string): Plan number from `plan view`. The new pool gets the entire purchase.
  - `monthly` (boolean): With `buy.plan` or `units`, pay monthly for new capacity (default).
  - `hourly` (boolean): With `buy.plan` or `units`, pay for new capacity from your wallet by the minute, with a minimum charge of one hour.
- `months` (string): Length of the prepaid monthly term, in months. Choose 1 (default) or 12.
- `offer` (string): Offer code for capacity bought for this pool.
- `dry_run` (boolean): Preview the change without applying it.
- `memory` (string): RAM to allocate from existing capacity in multiples of 8 GiB, with 2 vCPUs and corresponding storage per unit. A copy uses the source pool's size by default.
- `units` (string): Pool size in units of 2 vCPUs and 8 GiB of RAM, from 1 to 64. Uses unused capacity first, then buys the remainder.
- `server` (string): Server identifier from `capacity view`.
- `copy` (object)
  - `pool` (string, required): Source pool name or ID. The new pool uses unused capacity on the same server. To use a saved disk set, also give `copy.snapshot`.
  - `snapshot` (string): Snapshot name or ID from the pool named with `copy.pool`. The snapshot must belong to your account or be shared with you.
- `organization` (string): Organization name or ID. A credential, named resource or sole membership can select the organization for you.

## Returns

- `data` (object, always present): A pool and its purchases, a copy operation group with per-Computer results, or a preview.
  - `alternative-1` (object): A pool's resulting or proposed capacity and purchase. Pending payment must complete before the pool is created or enlarged.
    - `charged_cents` (integer): Immediate charge, or the previewed charge, in cents. May be omitted.
    - `checkout_url` (string): First monthly purchase's payment page. May be omitted.
    - `dry_run` (boolean): True when no pool or purchase was made. May be omitted.
    - `grows` (boolean): True when a purchase adds capacity to an existing pool after it becomes active. May be omitted.
    - `id` (string): Pool ID, when a pool has been created. May be omitted.
    - `invoice_url` (string): Payment page for an additional purchase needing your action. May be omitted.
    - `kind` (string): Billing model. May be omitted.
    - `memory_bytes` (integer): Pool's resulting RAM allocation, in bytes, including the increase once paid. May be omitted.
    - `plan` (integer): Purchased plan number. May be omitted.
    - `pool` (string, always present): Pool name.
    - `price_micros` (integer): Purchase's hourly or monthly price, in millionths of a dollar. May be omitted.
    - `purchase` (string): Capacity purchase made for this pool. May be omitted.
    - `storage_bytes` (integer): Resulting included storage, in bytes. May be omitted.
    - `unknown` (boolean): Whether the payment response was lost. Read `capacity view` before retrying. May be omitted.
    - `vcpus` (integer): Resulting vCPU allocation. May be omitted.
    - `wallet_micros` (integer): Wallet balance after an hourly purchase, in millionths of a dollar. May be omitted.
  - `alternative-2` (object): An accepted pool copy and its per-Computer results.
    - `operation` (object, always present): Operation group tracking the copy.
      - `completed_at` (string (date-time)): When the group finished. Absent while unfinished. May be omitted.
      - `created_at` (string (date-time), always present): When the grouped change was accepted.
      - `id` (string, always present): Group ID for `operation view`.
      - `kind` (string, always present): Grouped change.
      - `message` (string): An explanation of the group's progress or failure. May be omitted.
      - `operations` (object[] | null, always present): Member Computer operations.
        - `items` (object): An accepted change to one Computer. Work continues after the request disconnects.
          - `by` (string): Requester's email address, or user ID if no email is recorded. Omitted for your own requests. May be omitted.
          - `completed_at` (string (date-time)): When the operation reached its final state. Absent while unfinished. May be omitted.
          - `computer_id` (string, always present): Computer's stable ID.
          - `created_at` (string (date-time)): When Heaven accepted the change. May be omitted.
          - `error_code` (string): Recorded failure code. May be omitted.
          - `id` (string, always present): Operation ID for `operation view`.
          - `kind` (string, always present): Change being tracked.
          - `message` (string): An explanation of the recorded failure and any next action. May be omitted.
          - `state` (string, always present): `accepted` means saved and unfinished. `complete` means the change finished. `failed` means it could not finish. `superseded` means a newer change replaced it before completion. Values: `"accepted"`, `"complete"`, `"failed"`, `"superseded"`.
      - `pool_id` (string): Pool this change concerns. May be omitted.
      - `state` (string, always present): `accepted` while work remains, `complete` when all work succeeds, or `failed` when a step fails or a member operation fails or is superseded. Values: `"accepted"`, `"complete"`, `"failed"`, `"superseded"`.
      - `steps` (object[]): Other steps, in execution order. May be omitted.
        - `items` (object): A step in a grouped change outside its Computer operations.
          - `kind` (string, always present): Action taken by this step.
          - `message` (string): Progress or failure details for this step. May be omitted.
          - `pool_id` (string): Affected pool's ID. May be omitted.
          - `state` (string, always present): Step's recorded progress or outcome.
          - `subject` (string): Affected object, such as an organization being left. May be omitted.
      - `subject` (string): Other object the change concerns, such as a pool snapshot's name. May be omitted.
    - `pool` (object, always present): Destination pool and any purchase made for it.
      - `charged_cents` (integer): Immediate charge, or the previewed charge, in cents. May be omitted.
      - `checkout_url` (string): First monthly purchase's payment page. May be omitted.
      - `dry_run` (boolean): True when no pool or purchase was made. May be omitted.
      - `grows` (boolean): True when a purchase adds capacity to an existing pool after it becomes active. May be omitted.
      - `id` (string): Pool ID, when a pool has been created. May be omitted.
      - `invoice_url` (string): Payment page for an additional purchase needing your action. May be omitted.
      - `kind` (string): Billing model. May be omitted.
      - `memory_bytes` (integer): Pool's resulting RAM allocation, in bytes, including the increase once paid. May be omitted.
      - `plan` (integer): Purchased plan number. May be omitted.
      - `pool` (string, always present): Pool name.
      - `price_micros` (integer): Purchase's hourly or monthly price, in millionths of a dollar. May be omitted.
      - `purchase` (string): Capacity purchase made for this pool. May be omitted.
      - `storage_bytes` (integer): Resulting included storage, in bytes. May be omitted.
      - `unknown` (boolean): Whether the payment response was lost. Read `capacity view` before retrying. May be omitted.
      - `vcpus` (integer): Resulting vCPU allocation. May be omitted.
      - `wallet_micros` (integer): Wallet balance after an hourly purchase, in millionths of a dollar. May be omitted.
    - `request_id` (string, always present): Request ID for this copy.
    - `results` (object[] | null, always present): Each source Computer's copy operation or error.
      - `items` (object): The result of copying a Computer into the destination pool.
        - `computer` (object): New Computer, when creation was accepted. May be omitted.
          - `id` (string, always present): Referenced object's stable ID.
          - `name` (string, always present): Referenced object's name.
        - `error` (object): Why this source could not be copied. May be omitted.
          - `action` (object): A suggested command addressing the problem. May be omitted.
            - `command` (string, always present): Command's catalog name.
            - `line` (string, always present): Complete suggested command line.
          - `kind` (string, always present): Error category. `unknown` means the effect is uncertain; reconcile before retrying.
          - `message` (string, always present): What happened and any action needed from you.
          - `operation_id` (string): Operation to read before repeating uncertain work. May be omitted.
          - `request_id` (string): Request ID identifying the change during reconciliation. May be omitted.
          - `retry_after` (integer): Seconds before retrying a rate-limited request or a refused wait. May be omitted.
          - `url` (string): Payment page for a payment-required response. May be omitted.
        - `operation` (object): New Computer's copy operation. May be omitted.
          - `by` (string): Requester's email address, or user ID if no email is recorded. Omitted for your own requests. May be omitted.
          - `completed_at` (string (date-time)): When the operation reached its final state. Absent while unfinished. May be omitted.
          - `computer_id` (string, always present): Computer's stable ID.
          - `created_at` (string (date-time)): When Heaven accepted the change. May be omitted.
          - `error_code` (string): Recorded failure code. May be omitted.
          - `id` (string, always present): Operation ID for `operation view`.
          - `kind` (string, always present): Change being tracked.
          - `message` (string): An explanation of the recorded failure and any next action. May be omitted.
          - `state` (string, always present): `accepted` means saved and unfinished. `complete` means the change finished. `failed` means it could not finish. `superseded` means a newer change replaced it before completion. Values: `"accepted"`, `"complete"`, `"failed"`, `"superseded"`.
        - `source` (object, always present): Source Computer's ID and name.
          - `id` (string, always present): Referenced object's stable ID.
          - `name` (string, always present): Referenced object's name.
  - `alternative-3` (object): A pool copy preview. Reusing a copy's request ID returns its existing pool and operation group.
    - `dry_run` (boolean, always present): True for a preview; no pool or Computer is created.
    - `operation` (object): Existing copy's operation group when this request ID was already used. May be omitted.
      - `completed_at` (string (date-time)): When the group finished. Absent while unfinished. May be omitted.
      - `created_at` (string (date-time), always present): When the grouped change was accepted.
      - `id` (string, always present): Group ID for `operation view`.
      - `kind` (string, always present): Grouped change.
      - `message` (string): An explanation of the group's progress or failure. May be omitted.
      - `operations` (object[] | null, always present): Member Computer operations.
        - `items` (object): An accepted change to one Computer. Work continues after the request disconnects.
          - `by` (string): Requester's email address, or user ID if no email is recorded. Omitted for your own requests. May be omitted.
          - `completed_at` (string (date-time)): When the operation reached its final state. Absent while unfinished. May be omitted.
          - `computer_id` (string, always present): Computer's stable ID.
          - `created_at` (string (date-time)): When Heaven accepted the change. May be omitted.
          - `error_code` (string): Recorded failure code. May be omitted.
          - `id` (string, always present): Operation ID for `operation view`.
          - `kind` (string, always present): Change being tracked.
          - `message` (string): An explanation of the recorded failure and any next action. May be omitted.
          - `state` (string, always present): `accepted` means saved and unfinished. `complete` means the change finished. `failed` means it could not finish. `superseded` means a newer change replaced it before completion. Values: `"accepted"`, `"complete"`, `"failed"`, `"superseded"`.
      - `pool_id` (string): Pool this change concerns. May be omitted.
      - `state` (string, always present): `accepted` while work remains, `complete` when all work succeeds, or `failed` when a step fails or a member operation fails or is superseded. Values: `"accepted"`, `"complete"`, `"failed"`, `"superseded"`.
      - `steps` (object[]): Other steps, in execution order. May be omitted.
        - `items` (object): A step in a grouped change outside its Computer operations.
          - `kind` (string, always present): Action taken by this step.
          - `message` (string): Progress or failure details for this step. May be omitted.
          - `pool_id` (string): Affected pool's ID. May be omitted.
          - `state` (string, always present): Step's recorded progress or outcome.
          - `subject` (string): Affected object, such as an organization being left. May be omitted.
      - `subject` (string): Other object the change concerns, such as a pool snapshot's name. May be omitted.
    - `pool` (object, always present): Pool the copy would make, or the existing pool from the matching earlier request.
      - `charged_cents` (integer): Immediate charge, or the previewed charge, in cents. May be omitted.
      - `checkout_url` (string): First monthly purchase's payment page. May be omitted.
      - `dry_run` (boolean): True when no pool or purchase was made. May be omitted.
      - `grows` (boolean): True when a purchase adds capacity to an existing pool after it becomes active. May be omitted.
      - `id` (string): Pool ID, when a pool has been created. May be omitted.
      - `invoice_url` (string): Payment page for an additional purchase needing your action. May be omitted.
      - `kind` (string): Billing model. May be omitted.
      - `memory_bytes` (integer): Pool's resulting RAM allocation, in bytes, including the increase once paid. May be omitted.
      - `plan` (integer): Purchased plan number. May be omitted.
      - `pool` (string, always present): Pool name.
      - `price_micros` (integer): Purchase's hourly or monthly price, in millionths of a dollar. May be omitted.
      - `purchase` (string): Capacity purchase made for this pool. May be omitted.
      - `storage_bytes` (integer): Resulting included storage, in bytes. May be omitted.
      - `unknown` (boolean): Whether the payment response was lost. Read `capacity view` before retrying. May be omitted.
      - `vcpus` (integer): Resulting vCPU allocation. May be omitted.
      - `wallet_micros` (integer): Wallet balance after an hourly purchase, in millionths of a dollar. May be omitted.
    - `results` (object[] | null, always present): Sources and preview refusals. Empty when returning an existing copy.
      - `items` (object): The result of copying a Computer into the destination pool.
        - `computer` (object): New Computer, when creation was accepted. May be omitted.
          - `id` (string, always present): Referenced object's stable ID.
          - `name` (string, always present): Referenced object's name.
        - `error` (object): Why this source could not be copied. May be omitted.
          - `action` (object): A suggested command addressing the problem. May be omitted.
            - `command` (string, always present): Command's catalog name.
            - `line` (string, always present): Complete suggested command line.
          - `kind` (string, always present): Error category. `unknown` means the effect is uncertain; reconcile before retrying.
          - `message` (string, always present): What happened and any action needed from you.
          - `operation_id` (string): Operation to read before repeating uncertain work. May be omitted.
          - `request_id` (string): Request ID identifying the change during reconciliation. May be omitted.
          - `retry_after` (integer): Seconds before retrying a rate-limited request or a refused wait. May be omitted.
          - `url` (string): Payment page for a payment-required response. May be omitted.
        - `operation` (object): New Computer's copy operation. May be omitted.
          - `by` (string): Requester's email address, or user ID if no email is recorded. Omitted for your own requests. May be omitted.
          - `completed_at` (string (date-time)): When the operation reached its final state. Absent while unfinished. May be omitted.
          - `computer_id` (string, always present): Computer's stable ID.
          - `created_at` (string (date-time)): When Heaven accepted the change. May be omitted.
          - `error_code` (string): Recorded failure code. May be omitted.
          - `id` (string, always present): Operation ID for `operation view`.
          - `kind` (string, always present): Change being tracked.
          - `message` (string): An explanation of the recorded failure and any next action. May be omitted.
          - `state` (string, always present): `accepted` means saved and unfinished. `complete` means the change finished. `failed` means it could not finish. `superseded` means a newer change replaced it before completion. Values: `"accepted"`, `"complete"`, `"failed"`, `"superseded"`.
        - `source` (object, always present): Source Computer's ID and name.
          - `id` (string, always present): Referenced object's stable ID.
          - `name` (string, always present): Referenced object's name.
  - `alternative-4` (object): The result or preview of creating Computers and any new pool.
    - `computers` (object[] | null, always present): Computers in request order, each with its operation or error. Previews and pending payments can have neither.
      - `items` (object): One Computer in a create request.
        - `error` (object): Reason this Computer could not be created. May be omitted.
          - `action` (object): A suggested command addressing the problem. May be omitted.
            - `command` (string, always present): Command's catalog name.
            - `line` (string, always present): Complete suggested command line.
          - `kind` (string, always present): Error category. `unknown` means the effect is uncertain; reconcile before retrying.
          - `message` (string, always present): What happened and any action needed from you.
          - `operation_id` (string): Operation to read before repeating uncertain work. May be omitted.
          - `request_id` (string): Request ID identifying the change during reconciliation. May be omitted.
          - `retry_after` (integer): Seconds before retrying a rate-limited request or a refused wait. May be omitted.
          - `url` (string): Payment page for a payment-required response. May be omitted.
        - `name` (string): Chosen Computer name. A count-only preview has no name yet. May be omitted.
        - `operation` (object): Create operation. May be omitted.
          - `by` (string): Requester's email address, or user ID if no email is recorded. Omitted for your own requests. May be omitted.
          - `completed_at` (string (date-time)): When the operation reached its final state. Absent while unfinished. May be omitted.
          - `computer_id` (string, always present): Computer's stable ID.
          - `created_at` (string (date-time)): When Heaven accepted the change. May be omitted.
          - `error_code` (string): Recorded failure code. May be omitted.
          - `id` (string, always present): Operation ID for `operation view`.
          - `kind` (string, always present): Change being tracked.
          - `message` (string): An explanation of the recorded failure and any next action. May be omitted.
          - `state` (string, always present): `accepted` means saved and unfinished. `complete` means the change finished. `failed` means it could not finish. `superseded` means a newer change replaced it before completion. Values: `"accepted"`, `"complete"`, `"failed"`, `"superseded"`.
        - `ssh_dest` (string): SSH destination in `NAME@DOMAIN` form. May be omitted.
        - `url` (string): Website URL. May be omitted.
    - `dry_run` (boolean): Whether this is a preview and no Computers were created. May be omitted.
    - `error` (object): Creation refusal found by a dry run. May be omitted.
      - `action` (object): A suggested command addressing the problem. May be omitted.
        - `command` (string, always present): Command's catalog name.
        - `line` (string, always present): Complete suggested command line.
      - `kind` (string, always present): Error category. `unknown` means the effect is uncertain; reconcile before retrying.
      - `message` (string, always present): What happened and any action needed from you.
      - `operation_id` (string): Operation to read before repeating uncertain work. May be omitted.
      - `request_id` (string): Request ID identifying the change during reconciliation. May be omitted.
      - `retry_after` (integer): Seconds before retrying a rate-limited request or a refused wait. May be omitted.
      - `url` (string): Payment page for a payment-required response. May be omitted.
    - `pool` (object): New pool, or the pool a dry run would create. May be omitted.
      - `bought` (object, always present): Capacity purchased for the remaining size.
        - `memory_bytes` (integer, always present): RAM allocation in bytes.
        - `storage_bytes` (integer, always present): Included storage in bytes.
        - `units` (integer, always present): Number of units.
        - `vcpus` (integer, always present): vCPU allocation.
      - `charged_cents` (integer): Charge now, or its dry-run estimate, in cents. May be omitted.
      - `from_unused` (object, always present): Existing purchased capacity assigned to the pool.
        - `memory_bytes` (integer, always present): RAM allocation in bytes.
        - `storage_bytes` (integer, always present): Included storage in bytes.
        - `units` (integer, always present): Number of units.
        - `vcpus` (integer, always present): vCPU allocation.
      - `id` (string): Created pool's ID. Absent for a preview or while payment is pending. May be omitted.
      - `kind` (string): Billing model for new purchases. May be omitted.
      - `memory_bytes` (integer, always present): Pool's RAM allocation, in bytes.
      - `name` (string, always present): New pool's name.
      - `plans` (object[]): Plans bought and any payment steps still required. May be omitted.
        - `items` (object): A plan purchased or proposed for a pool.
          - `charged_cents` (integer): Amount charged now, or its preview, in cents. May be omitted.
          - `checkout_url` (string): Checkout page when payment is required. May be omitted.
          - `invoice_url` (string): Invoice page when payment needs your action. May be omitted.
          - `plan` (integer, always present): Plan number.
          - `price_micros` (integer, always present): Price per billing period, in millionths of a dollar. The enclosing result specifies the billing model.
          - `purchase` (string): Capacity purchase ID. May be omitted.
          - `units` (integer, always present): Capacity units supplied by the plan.
          - `unknown` (boolean): Whether the payment outcome is uncertain. Read capacity before buying again. May be omitted.
      - `price_micros` (integer, always present): Combined price of new purchases per billing period, in millionths of a dollar.
      - `region` (string): Pool's region. May be omitted.
      - `storage_bytes` (integer, always present): Pool's included storage, in bytes.
      - `units` (integer, always present): Pool's capacity in units.
      - `vcpus` (integer, always present): Pool's vCPU allocation.
    - `request_id` (string, always present): Request ID for this creation.
    - `room` (object): Request's capacity check, when available. May be omitted.
      - `computers` (integer, always present): Number of Computers requested.
      - `fits` (boolean, always present): Whether the request fits the pool's available storage and creation limits.
      - `needs_bytes` (integer, always present): Estimated additional storage needed by the request, in bytes.
      - `pool` (string, always present): Pool checked.
      - `storage_bytes` (integer, always present): Pool's included storage, in bytes.
      - `stored_bytes` (integer, always present): Storage already occupied in the pool, in bytes.
      - `waiting_for_memory` (integer, always present): Of the Computers the pool is creating, how many are waiting for memory in the pool.
    - `waiting` (boolean): Whether purchases await payment. Heaven creates the pool and Computers once payment is confirmed. May be omitted.

## Errors

Each code is explained in full at https://heaven.dev/docs/reference/errors.

| Code | Status | What happened |
|---|---:|---|
| `invalid` | 400 | An input is missing or invalid. |
| `unauthenticated` | 401 | The credential is missing, invalid, expired or revoked. |
| `denied` | 403 | The caller lacks permission for this action. |
| `not_found` | 404 | The resource is absent or inaccessible to this caller. |
| `conflict` | 409 | The request conflicts with the current resource state or an earlier request. |
| `over_capacity` | 409 | The request exceeds a resource or credential allowance. |
| `access_list_full` | 409 | The change would exceed the access-list allowance. |
| `payment_required` | 402 | Payment or credit is required. |
| `rate_limited` | 429 | The caller's request rate exceeds its limit. |
| `busy` | 429 | Too much work is in progress to accept this request. |
| `unknown` | 503 | The outcome is unconfirmed; a change may have happened. |
| `unavailable` | 503 | The service or requested feature is unavailable. |

## Notes

- CLI: `heaven login` with `HEAVEN_API_KEY` unset. MCP: Heaven sign-in. cURL: `HEAVEN_SIGN_IN_KEY` from approved device sign-in (`POST /v1/auth/create`).
- A key limited to a command list cannot run this command.
- For retries, reuse the original `Idempotency-Key` and inputs.
- **From capacity:** Create a pool from purchased capacity. Required: `memory`. Optional: `server`, `name`, `dry_run`, `organization`.
- **Buy a plan:** Buy the selected plan and allocate all of its capacity to a new pool. Required: `buy`. Optional: `months`, `offer`, `server`, `name`, `dry_run`, `organization`.
- **Of units:** Create a pool using available capacity and buying any shortfall. Required: `units`. Optional: `buy.monthly`, `buy.hourly`, `name`, `dry_run`, `organization`.
- **Copy:** Copy a pool or pool snapshot into available capacity on the source's server. Required: `copy`. Optional: `memory`, `name`, `dry_run`, `organization`.

## Examples

```sh tab="heaven CLI"
heaven pool create [NAME]
  [--buy PLAN]
  [--monthly]
  [--hourly]
  [--months MONTHS]
  [--offer OFFER]
  [--dry-run]
  [--memory SIZE]
  [--units N]
  [--server SERVER]
  [--copy POOL]
  [--snapshot SNAPSHOT]
  [--request-id ID]
  [--organization ORGANIZATION]
```

```sh tab="SSH"
ssh cli@heaven.dev pool create [NAME]
  [--buy PLAN]
  [--monthly]
  [--hourly]
  [--months MONTHS]
  [--offer OFFER]
  [--dry-run]
  [--memory SIZE]
  [--units N]
  [--server SERVER]
  [--copy POOL]
  [--snapshot SNAPSHOT]
  [--request-id ID]
  [--organization ORGANIZATION]
```

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

```json tab="MCP"
{ "tool": "pool_create",
  "arguments": { "name": "api", "memory": "8GB", "request_id": "pool-create-api" } }
```

Response:

```json title="Response excerpt"
{
  "version": 1,
  "data": {
    "id": "pool-8c43fc960dcc56d7",
    "kind": "slice",
    "memory_bytes": 8589934592,
    "pool": "api",
    "storage_bytes": 100000000000,
    "vcpus": 2
  }
}
```
