Skip to content

Move a Computer

Move a Computer to another pool in the same account and on the same server. Running processes are preserved. Pool-based access, integration attachments and network addresses can change. Use dry_run: true to check the effects first. If the server doesn't support moves between pools, the move returns unavailable.

Parameters

#
computerstring
Computer name or ID.
computersstring[]
Computer names or IDs, supplied instead of computer.
poolstringRequired
Destination pool name or ID, on the same server as the Computer.
dry_runboolean
Preview the change without applying it.

Returns

#
dataobjectAlways present
A move operation or per-Computer results.
Show 3 attributesHide attributes
alternative-1object
An operation and its request ID.
Show 8 attributesHide attributes
namestring
Computer's name after creation, copying or reset. May be omitted.
notesstring[]
Other effects, including settings or integrations excluded from a copy. May be omitted.
operationobjectAlways present
Current operation state.
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_notestring
How stopping this Computer affects its pool. May be omitted.
renamedobject
Addresses affected by a rename. May be omitted.
Show 6 attributesHide attributes
httpsstringAlways present
Website URL using the new name.
mailstringAlways present
Domain under which the Computer receives mail.
namesobject[]
Custom names created with the Computer and whether they followed its rename. May be omitted.
Show 1 attributeHide attributes
itemsobject
A custom name affected by a Computer rename.
Show 3 attributesHide attributes
fromstringAlways present
Previous custom name.
movedbooleanAlways present
Whether the name moved. False means the destination was occupied and the old custom name was retained.
tostringAlways present
Name corresponding to the Computer's new name.
notestringAlways present
What happened to old addresses and when the guest hostname changes.
portsstring[]
Published port addresses that use the new name. May be omitted.
sshstringAlways present
SSH command using the new name.
request_idstringAlways present
Request ID identifying this change across retries.
ssh_deststring
SSH destination in NAME@DOMAIN form. May be omitted.
urlstring
Computer's website address. May be omitted.
alternative-2object
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".
alternative-3object
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

#
  • API key permission: move.
  • Use computers instead of computer for several targets, each with its own result.