Skip to content

Transfer a Computer

Transfer ownership of a Computer. Shares, links, support access and Computer-scoped keys are cleared by default. Use keep_shares: true to keep eligible shares within the same organization. Direct integrations can stay only if they belong to the new owner. Cross-organization transfers preserve running processes but remove the old account's shares, direct integrations, public ports and static address. They require a sign-in or its key.

Parameters

#
computerstring
Computer name or ID.
computersstring[]
Computer names or IDs, supplied instead of computer.
userstring
The organization member to become the Computer's owner, by email address or user ID.
teamstring
The team to become the Computer's owner.
whole_organizationboolean
Make the organization itself the Computer's owner.
keep_sharesboolean
Keep shares the new owner is allowed to grant. Without it, existing shares are removed.
poolstring
The destination pool in another of your organizations, by name or ID, on the same server. The Computer moves there with you as its owner.

Returns

#
dataobjectAlways present
An ownership change, an account transfer operation, or per-Computer results.
Show 3 attributesHide attributes
alternative-1object
A Computer ownership change and the access it removes.
Show 2 attributesHide attributes
clearedobjectAlways present
Shares, credentials or integration access removed by the transfer.
Show 12 attributesHide attributes
domainsstring[]
Former organization's domain names removed from the Computer. May be omitted.
integrationsstring[]
Integration attachments removed. May be omitted.
invitationsinteger
Email invitations ended. May be omitted.
kept_sharesinteger
Shares explicitly retained by the request. May be omitted.
keysinteger
SSH keys limited to this Computer that were removed. May be omitted.
peer_keysinteger
Peer integration keys that were removed. May be omitted.
public_portsinteger
Public ports released when the Computer left its account. May be omitted.
sessionsinteger
Private-website browser sessions ended. May be omitted.
sharesinteger
Shares removed. May be omitted.
static_addressstring
Static address detached when it left its account. May be omitted.
support_accessboolean
Whether support Root access was removed. May be omitted.
transferredbooleanAlways present
Whether ownership transferred.
alternative-2object
An accepted transfer to another account's pool.
Show 5 attributesHide attributes
accountstringAlways present
Destination account.
clearedobject
Access and addresses removed when leaving the former account. May be omitted.
Show 12 attributesHide attributes
domainsstring[]
Former organization's domain names removed from the Computer. May be omitted.
integrationsstring[]
Integration attachments removed. May be omitted.
invitationsinteger
Email invitations ended. May be omitted.
kept_sharesinteger
Shares explicitly retained by the request. May be omitted.
keysinteger
SSH keys limited to this Computer that were removed. May be omitted.
peer_keysinteger
Peer integration keys that were removed. May be omitted.
public_portsinteger
Public ports released when the Computer left its account. May be omitted.
sessionsinteger
Private-website browser sessions ended. May be omitted.
sharesinteger
Shares removed. May be omitted.
static_addressstring
Static address detached when it left its account. May be omitted.
support_accessboolean
Whether support Root access was removed. May be omitted.
operationobjectAlways present
Operation tracking the Computer's move.
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".
request_idstringAlways present
Request ID for this transfer.
transferredbooleanAlways present
Whether the ownership change was accepted.
alternative-3object
Results for a multi-Computer request. Each target can succeed or fail independently.
Show 2 attributesHide attributes
request_idstringAlways present
Request ID for this multi-Computer change.
resultsobject[] | nullAlways present
Each target's accepted operation, direct result or error, in request order.
Show 1 attributeHide attributes
itemsobject
One Computer's operation, direct result or error.
Show 4 attributesHide attributes
computerobjectAlways present
Target's ID and name.
Show 2 attributesHide attributes
idstringAlways present
Computer ID.
namestringAlways present
Computer's name when this result was prepared.
dataJSON value
Direct command result, with the same meaning as a single-Computer result. May be omitted.
errorobject
Reason this target could not be changed. 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
Accepted operation for this target, if the command returns one. 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".

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.
  • Use computers instead of computer for several targets, each with its own result.
  • Member: Transfer ownership to another member of the Computer's organization. Required: user. Optional: keep_shares, computer, computers.
  • Team: Transfer ownership to a team in the Computer's organization. Required: team. Optional: keep_shares, computer, computers.
  • Organization: Transfer ownership to the Computer's organization. Required: whole_organization. Optional: keep_shares, computer, computers.
  • Pool: Transfer the Computer to your ownership in another organization's pool on the same server. Required: pool. Optional: computer, computers.