Parameters
#computerstringRequired
Computer name or ID.
imagestring
Image to reinstall. Defaults to the Computer's current image.
setup_scriptstring
Replacement script to run when the fresh disk starts. Heaven keeps it for later resets. The saved script is used by default. Treated as a secret and never included in errors.
dry_runboolean
Preview what the reset would erase and what you can recover.
waitboolean or string
Wait for the operation to finish. Use true for up to 10m or give a shorter duration such as 2m. Accepted work continues after the wait ends.
Returns
#dataobjectAlways present
An operation and its request ID. A preview of the requested change.
Show 2 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
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
#| 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
#- API key permission:
reset. - A key limited to a command list must also allow
delete.