Skip to content

Transfer a pool

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.

Parameters

#
poolstringRequired
Pool name or ID.
tostring
Destination organization name or ID. Requires admin or billing owner access in both organizations.
dry_runboolean
Preview the change without applying it.
organizationstring
Organization name or ID. A credential, named resource or sole membership can select the organization for you.

Returns

#
dataobjectAlways present
An accepted pool split, combination or transfer. A preview of the requested change.
Show 2 attributesHide attributes
alternative-1object
An accepted pool split, combination or transfer.
Show 11 attributesHide attributes
changesstring[]
Other effects on addresses, ports, setup scripts or snapshots. May be omitted.
ended_sharesobject[]
Shares ended by combining away a pool, including Computers their holders had created. May be omitted.
Show 1 attributeHide attributes
itemsobject
A pool share and the Computers its holders created through it.
Show 8 attributesHide attributes
commandsstring[]
Additional commands granted through the share. May be omitted.
computersintegerAlways present
Computers in the pool created by this share's holders.
emailstring
Recipient's email, including an address whose invitation has not yet been claimed. May be omitted.
organizationstring
Recipient organization, when shared with an organization. May be omitted.
poolstringAlways present
Pool name.
rolestringAlways present
Role granted through this share.
teamstring
Recipient team, when shared with a team. May be omitted.
user_idstring
Individual recipient's user ID. May be omitted.
fromstringAlways present
Source pool's name.
idstringAlways present
Resulting pool's ID.
memory_bytesinteger
Resulting pool's RAM allocation, in bytes. May be omitted.
operationobjectAlways present
Operation group tracking the change.
Show 10 attributesHide attributes
completed_atstring (date-time)
When the group finished. Absent while unfinished. May be omitted.
created_atstring (date-time)Always present
When the grouped change was accepted.
idstringAlways present
Group ID for operation view.
kindstringAlways present
Grouped change.
messagestring
An explanation of the group's progress or failure. May be omitted.
operationsobject[] | nullAlways present
Member Computer operations.
Show 1 attributeHide attributes
itemsobject
An accepted change to one Computer. Work continues after the request disconnects.
Show 9 attributesHide attributes
bystring
Requester's email address, or user ID if no email is recorded. Omitted for your own requests. May be omitted.
completed_atstring (date-time)
When the operation reached its final state. Absent while unfinished. May be omitted.
computer_idstringAlways present
Computer's stable ID.
created_atstring (date-time)
When Heaven accepted the change. May be omitted.
error_codestring
Recorded failure code. May be omitted.
idstringAlways present
Operation ID for operation view.
kindstringAlways present
Change being tracked.
messagestring
An explanation of the recorded failure and any next action. May be omitted.
statestringAlways 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_idstring
Pool this change concerns. May be omitted.
statestringAlways 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".
stepsobject[]
Other steps, in execution order. May be omitted.
Show 1 attributeHide attributes
itemsobject
A step in a grouped change outside its Computer operations.
Show 5 attributesHide attributes
kindstringAlways present
Action taken by this step.
messagestring
Progress or failure details for this step. May be omitted.
pool_idstring
Affected pool's ID. May be omitted.
statestringAlways present
Step's recorded progress or outcome.
subjectstring
Affected object, such as an organization being left. May be omitted.
subjectstring
Other object the change concerns, such as a pool snapshot's name. May be omitted.
organizationstring
Destination organization for a transfer. May be omitted.
poolstringAlways present
Resulting pool: newly created by a split, retained by a combination, or moved by a transfer.
resultsobject[] | nullAlways present
Each Computer's move operation or refusal.
Show 1 attributeHide attributes
itemsobject
One Computer's move within a pool change.
Show 3 attributesHide attributes
computerobjectAlways present
Affected Computer.
Show 2 attributesHide attributes
idstringAlways present
Computer ID.
namestringAlways present
Computer's name when this result was prepared.
errorobject
Why this Computer's move was refused. May be omitted.
Show 7 attributesHide attributes
actionobject
A suggested command addressing the problem. May be omitted.
Show 2 attributesHide attributes
commandstringAlways present
Command's catalog name.
linestringAlways present
Complete suggested command line.
kindstringAlways present
Error category. unknown means the effect is uncertain; reconcile before retrying.
messagestringAlways present
What happened and any action needed from you.
operation_idstring
Operation to read before repeating uncertain work. May be omitted.
request_idstring
Request ID identifying the change during reconciliation. May be omitted.
retry_afterinteger
Seconds before retrying a rate-limited request or a refused wait. May be omitted.
urlstring
Payment page for a payment-required response. May be omitted.
operationobject
Move operation, when accepted. May be omitted.
Show 9 attributesHide attributes
bystring
Requester's email address, or user ID if no email is recorded. Omitted for your own requests. May be omitted.
completed_atstring (date-time)
When the operation reached its final state. Absent while unfinished. May be omitted.
computer_idstringAlways present
Computer's stable ID.
created_atstring (date-time)
When Heaven accepted the change. May be omitted.
error_codestring
Recorded failure code. May be omitted.
idstringAlways present
Operation ID for operation view.
kindstringAlways present
Change being tracked.
messagestring
An explanation of the recorded failure and any next action. May be omitted.
statestringAlways 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_bytesinteger
Resulting pool's included storage, in bytes. May be omitted.
vcpusinteger
Resulting pool's vCPU allocation. May be omitted.
alternative-2object
A preview of the requested change.
Show 3 attributesHide attributes
changesstring[]
Proposed effects and losses. May be omitted.
dry_runbooleanAlways present
True for a preview; no changes are made.
messagestringAlways present
What the request would do.

Errors

#
CodeStatusWhat happened
invalid400An input is missing or invalid.
unauthenticated401The credential is missing, invalid, expired or revoked.
denied403The caller lacks permission for this action.
not_found404The resource is absent or inaccessible to this caller.
conflict409The request conflicts with the current resource state or an earlier request.
over_capacity409The request exceeds a resource or credential allowance.
access_list_full409The change would exceed the access-list allowance.
payment_required402Payment or credit is required.
rate_limited429The caller's request rate exceeds its limit.
busy429Too much work is in progress to accept this request.
unknown503The outcome is unconfirmed; a change may have happened.
unavailable503The 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.