# Transfer a pool

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

Transfer a pool and its Computers to another organization. The Computers restart under your ownership. The transfer requires management permission in both organizations, a sign-in or its key, and destination capacity on the same server. Heaven can shrink or delete an empty destination pool to make room. If the source server doesn't support moves between pools, the transfer returns `unavailable`. The transfer removes shares, links, support access, public ports, static address assignments, integration attachments, the pool setup script and pool snapshots.

`POST /v1/pool/modify`

## Parameters

- `pool` (string, required): Pool name or ID.
- `to` (string): Destination organization name or ID. Requires admin or billing owner access in both organizations.
- `dry_run` (boolean): Preview the change without applying it.
- `organization` (string): Organization name or ID. A credential, named resource or sole membership can select the organization for you.

## Returns

- `data` (object, always present): An accepted pool split, combination or transfer. A preview of the requested change.
  - `alternative-1` (object): An accepted pool split, combination or transfer.
    - `changes` (string[]): Other effects on addresses, ports, setup scripts or snapshots. May be omitted.
    - `ended_shares` (object[]): Shares ended by combining away a pool, including Computers their holders had created. May be omitted.
      - `items` (object): A pool share and the Computers its holders created through it.
        - `commands` (string[]): Additional commands granted through the share. May be omitted.
        - `computers` (integer, always present): Computers in the pool created by this share's holders.
        - `email` (string): Recipient's email, including an address whose invitation has not yet been claimed. May be omitted.
        - `organization` (string): Recipient organization, when shared with an organization. May be omitted.
        - `pool` (string, always present): Pool name.
        - `role` (string, always present): Role granted through this share.
        - `team` (string): Recipient team, when shared with a team. May be omitted.
        - `user_id` (string): Individual recipient's user ID. May be omitted.
    - `from` (string, always present): Source pool's name.
    - `id` (string, always present): Resulting pool's ID.
    - `memory_bytes` (integer): Resulting pool's RAM allocation, in bytes. May be omitted.
    - `operation` (object, always present): Operation group tracking the change.
      - `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.
    - `organization` (string): Destination organization for a transfer. May be omitted.
    - `pool` (string, always present): Resulting pool: newly created by a split, retained by a combination, or moved by a transfer.
    - `results` (object[] | null, always present): Each Computer's move operation or refusal.
      - `items` (object): One Computer's move within a pool change.
        - `computer` (object, always present): Affected Computer.
          - `id` (string, always present): Computer ID.
          - `name` (string, always present): Computer's name when this result was prepared.
        - `error` (object): Why this Computer's move was refused. 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): Move operation, when accepted. 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"`.
    - `storage_bytes` (integer): Resulting pool's included storage, in bytes. May be omitted.
    - `vcpus` (integer): Resulting pool's vCPU allocation. May be omitted.
  - `alternative-2` (object): A preview of the requested change.
    - `changes` (string[]): Proposed effects and losses. May be omitted.
    - `dry_run` (boolean, always present): True for a preview; no changes are made.
    - `message` (string, always present): What the request would do.

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

- Transfers between organizations require management SSH, the dashboard, or a CLI or MCP sign-in unbound to an organization. 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.
- A key limited to a command list must also allow `pool delete`.

## Examples

```sh tab="heaven CLI"
heaven pool transfer POOL
  [--to TO]
  [--request-id ID]
  [--dry-run]
  [--organization ORGANIZATION]
```

```sh tab="SSH"
ssh cli@heaven.dev pool transfer POOL
  [--to TO]
  [--request-id ID]
  [--dry-run]
  [--organization ORGANIZATION]
```

```sh tab="cURL"
curl https://heaven.dev/v1/pool/modify \
  -H "Authorization: Bearer $HEAVEN_SIGN_IN_KEY" \
  --json '{"action": "transfer", "pool": "web", "to": "acme", "organization": "studio"}'
```

```json tab="MCP"
{ "tool": "pool_transfer",
  "arguments": { "pool": "web", "to": "acme", "organization": "studio" } }
```

Response:

```json title="Response excerpt"
{
  "version": 1,
  "data": {
    "changes": [
      "Its 2 Computers move to acme as yours and restart, each leaving behind its shares, share links, support access, public ports, static address and the integrations attached to it alone.",
      "acme's empty pool acme-pool is deleted. Its 8 GiB goes to this pool.",
      "The pool uses 8 GiB of acme's capacity. studio keeps its capacity."
    ],
    "from": "web",
    "id": "pool-d3f69c9a266495e2",
    "memory_bytes": 8589934592,
    "operation": {
      "created_at": "2026-11-16T12:00:00Z",
      "id": "c219c81c-6aa3-4052-a04b-1210b9181812",
      "kind": "pool transfer",
      "operations": [
        {
          "computer_id": "3f1c9e2a-7b4d-4c8e-9a6f-2d5b8e1c7a90",
          "created_at": "2026-11-16T12:00:00Z",
          "id": "0af3d638-983c-440e-aca2-bee4cf3fe688",
          "kind": "move",
          "state": "accepted"
        },
        {
          "computer_id": "8a2d6f4b-1e3c-4b7a-8d9e-5c0f3a6b2e14",
          "created_at": "2026-11-16T12:00:00Z",
          "id": "22f22dec-3376-4acc-a677-d1d917584ea9",
          "kind": "move",
          "state": "accepted"
        }
      ],
      "pool_id": "pool-4b8216a90f985c7d",
      "state": "accepted",
      "subject": "acme"
    },
    "organization": "acme",
    "pool": "web",
    "results": [
      {
        "computer": {
          "id": "8a2d6f4b-1e3c-4b7a-8d9e-5c0f3a6b2e14",
          "name": "my-api"
        },
        "operation": {
          "computer_id": "8a2d6f4b-1e3c-4b7a-8d9e-5c0f3a6b2e14",
          "created_at": "2026-11-16T12:00:00Z",
          "id": "22f22dec-3376-4acc-a677-d1d917584ea9",
          "kind": "move",
          "state": "accepted"
        }
      },
      {
        "computer": {
          "id": "3f1c9e2a-7b4d-4c8e-9a6f-2d5b8e1c7a90",
          "name": "my-site"
        },
        "operation": {
          "computer_id": "3f1c9e2a-7b4d-4c8e-9a6f-2d5b8e1c7a90",
          "created_at": "2026-11-16T12:00:00Z",
          "id": "0af3d638-983c-440e-aca2-bee4cf3fe688",
          "kind": "move",
          "state": "accepted"
        }
      }
    ],
    "storage_bytes": 100000000000,
    "vcpus": 2
  }
}
```
