Parameters
#namestring
Pool name, unique in your account regardless of case. Generated if omitted; starts with default when using
units.buyobject
Show 3 attributesHide attributes
planstring
Plan number from
plan view. The new pool gets the entire purchase.monthlyboolean
With
buy.plan or units, pay monthly for new capacity (default).hourlyboolean
With
buy.plan or units, pay for new capacity from your wallet by the minute, with a minimum charge of one hour.monthsstring
Length of the prepaid monthly term, in months. Choose 1 (default) or 12.
offerstring
Offer code for capacity bought for this pool.
dry_runboolean
Preview the change without applying it.
memorystring
RAM to allocate from existing capacity in multiples of 8 GiB, with 2 vCPUs and corresponding storage per unit. A copy uses the source pool's size by default.
unitsstring
Pool size in units of 2 vCPUs and 8 GiB of RAM, from 1 to 64. Uses unused capacity first, then buys the remainder.
serverstring
Server identifier from
capacity view.copyobject
Show 2 attributesHide attributes
poolstringRequired
Source pool name or ID. The new pool uses unused capacity on the same server. To use a saved disk set, also give
copy.snapshot.snapshotstring
Snapshot name or ID from the pool named with
copy.pool. The snapshot must belong to your account or be shared with you.organizationstring
Organization name or ID. A credential, named resource or sole membership can select the organization for you.
Returns
#dataobjectAlways present
A pool and its purchases, a copy operation group with per-Computer results, or a preview.
Show 4 attributesHide attributes
alternative-1object
A pool's resulting or proposed capacity and purchase. Pending payment must complete before the pool is created or enlarged.
Show 16 attributesHide attributes
charged_centsinteger
Immediate charge, or the previewed charge, in cents. May be omitted.
checkout_urlstring
First monthly purchase's payment page. May be omitted.
dry_runboolean
True when no pool or purchase was made. May be omitted.
growsboolean
True when a purchase adds capacity to an existing pool after it becomes active. May be omitted.
idstring
Pool ID, when a pool has been created. May be omitted.
invoice_urlstring
Payment page for an additional purchase needing your action. May be omitted.
kindstring
Billing model. May be omitted.
memory_bytesinteger
Pool's resulting RAM allocation, in bytes, including the increase once paid. May be omitted.
planinteger
Purchased plan number. May be omitted.
poolstringAlways present
Pool name.
price_microsinteger
Purchase's hourly or monthly price, in millionths of a dollar. May be omitted.
purchasestring
Capacity purchase made for this pool. May be omitted.
storage_bytesinteger
Resulting included storage, in bytes. May be omitted.
unknownboolean
Whether the payment response was lost. Read
capacity view before retrying. May be omitted.vcpusinteger
Resulting vCPU allocation. May be omitted.
wallet_microsinteger
Wallet balance after an hourly purchase, in millionths of a dollar. May be omitted.
alternative-2object
An accepted pool copy and its per-Computer results.
Show 4 attributesHide attributes
operationobjectAlways present
Operation group tracking the copy.
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.
poolobjectAlways present
Destination pool and any purchase made for it.
Show 16 attributesHide attributes
charged_centsinteger
Immediate charge, or the previewed charge, in cents. May be omitted.
checkout_urlstring
First monthly purchase's payment page. May be omitted.
dry_runboolean
True when no pool or purchase was made. May be omitted.
growsboolean
True when a purchase adds capacity to an existing pool after it becomes active. May be omitted.
idstring
Pool ID, when a pool has been created. May be omitted.
invoice_urlstring
Payment page for an additional purchase needing your action. May be omitted.
kindstring
Billing model. May be omitted.
memory_bytesinteger
Pool's resulting RAM allocation, in bytes, including the increase once paid. May be omitted.
planinteger
Purchased plan number. May be omitted.
poolstringAlways present
Pool name.
price_microsinteger
Purchase's hourly or monthly price, in millionths of a dollar. May be omitted.
purchasestring
Capacity purchase made for this pool. May be omitted.
storage_bytesinteger
Resulting included storage, in bytes. May be omitted.
unknownboolean
Whether the payment response was lost. Read
capacity view before retrying. May be omitted.vcpusinteger
Resulting vCPU allocation. May be omitted.
wallet_microsinteger
Wallet balance after an hourly purchase, in millionths of a dollar. May be omitted.
request_idstringAlways present
Request ID for this copy.
resultsobject[] | nullAlways present
Each source Computer's copy operation or error.
Show 1 attributeHide attributes
itemsobject
The result of copying a Computer into the destination pool.
Show 4 attributesHide attributes
computerobject
New Computer, when creation was accepted. May be omitted.
Show 2 attributesHide attributes
idstringAlways present
Referenced object's stable ID.
namestringAlways present
Referenced object's name.
errorobject
Why this source could not be copied. 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
New Computer's copy operation. 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".sourceobjectAlways present
Source Computer's ID and name.
Show 2 attributesHide attributes
idstringAlways present
Referenced object's stable ID.
namestringAlways present
Referenced object's name.
alternative-3object
A pool copy preview. Reusing a copy's request ID returns its existing pool and operation group.
Show 4 attributesHide attributes
dry_runbooleanAlways present
True for a preview; no pool or Computer is created.
operationobject
Existing copy's operation group when this request ID was already used. May be omitted.
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.
poolobjectAlways present
Pool the copy would make, or the existing pool from the matching earlier request.
Show 16 attributesHide attributes
charged_centsinteger
Immediate charge, or the previewed charge, in cents. May be omitted.
checkout_urlstring
First monthly purchase's payment page. May be omitted.
dry_runboolean
True when no pool or purchase was made. May be omitted.
growsboolean
True when a purchase adds capacity to an existing pool after it becomes active. May be omitted.
idstring
Pool ID, when a pool has been created. May be omitted.
invoice_urlstring
Payment page for an additional purchase needing your action. May be omitted.
kindstring
Billing model. May be omitted.
memory_bytesinteger
Pool's resulting RAM allocation, in bytes, including the increase once paid. May be omitted.
planinteger
Purchased plan number. May be omitted.
poolstringAlways present
Pool name.
price_microsinteger
Purchase's hourly or monthly price, in millionths of a dollar. May be omitted.
purchasestring
Capacity purchase made for this pool. May be omitted.
storage_bytesinteger
Resulting included storage, in bytes. May be omitted.
unknownboolean
Whether the payment response was lost. Read
capacity view before retrying. May be omitted.vcpusinteger
Resulting vCPU allocation. May be omitted.
wallet_microsinteger
Wallet balance after an hourly purchase, in millionths of a dollar. May be omitted.
resultsobject[] | nullAlways present
Sources and preview refusals. Empty when returning an existing copy.
Show 1 attributeHide attributes
itemsobject
The result of copying a Computer into the destination pool.
Show 4 attributesHide attributes
computerobject
New Computer, when creation was accepted. May be omitted.
Show 2 attributesHide attributes
idstringAlways present
Referenced object's stable ID.
namestringAlways present
Referenced object's name.
errorobject
Why this source could not be copied. 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
New Computer's copy operation. 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".sourceobjectAlways present
Source Computer's ID and name.
Show 2 attributesHide attributes
idstringAlways present
Referenced object's stable ID.
namestringAlways present
Referenced object's name.
alternative-4object
The result or preview of creating Computers and any new pool.
Show 7 attributesHide attributes
computersobject[] | nullAlways present
Computers in request order, each with its operation or error. Previews and pending payments can have neither.
Show 1 attributeHide attributes
itemsobject
One Computer in a create request.
Show 5 attributesHide attributes
errorobject
Reason this Computer could not be created. 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.
namestring
Chosen Computer name. A count-only preview has no name yet. May be omitted.
operationobject
Create operation. 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".ssh_deststring
SSH destination in
NAME@DOMAIN form. May be omitted.urlstring
Website URL. May be omitted.
dry_runboolean
Whether this is a preview and no Computers were created. May be omitted.
errorobject
Creation refusal found by a dry run. 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.
poolobject
New pool, or the pool a dry run would create. May be omitted.
Show 13 attributesHide attributes
boughtobjectAlways present
Capacity purchased for the remaining size.
Show 4 attributesHide attributes
memory_bytesintegerAlways present
RAM allocation in bytes.
storage_bytesintegerAlways present
Included storage in bytes.
unitsintegerAlways present
Number of units.
vcpusintegerAlways present
vCPU allocation.
charged_centsinteger
Charge now, or its dry-run estimate, in cents. May be omitted.
from_unusedobjectAlways present
Existing purchased capacity assigned to the pool.
Show 4 attributesHide attributes
memory_bytesintegerAlways present
RAM allocation in bytes.
storage_bytesintegerAlways present
Included storage in bytes.
unitsintegerAlways present
Number of units.
vcpusintegerAlways present
vCPU allocation.
idstring
Created pool's ID. Absent for a preview or while payment is pending. May be omitted.
kindstring
Billing model for new purchases. May be omitted.
memory_bytesintegerAlways present
Pool's RAM allocation, in bytes.
namestringAlways present
New pool's name.
plansobject[]
Plans bought and any payment steps still required. May be omitted.
Show 1 attributeHide attributes
itemsobject
A plan purchased or proposed for a pool.
Show 8 attributesHide attributes
charged_centsinteger
Amount charged now, or its preview, in cents. May be omitted.
checkout_urlstring
Checkout page when payment is required. May be omitted.
invoice_urlstring
Invoice page when payment needs your action. May be omitted.
planintegerAlways present
Plan number.
price_microsintegerAlways present
Price per billing period, in millionths of a dollar. The enclosing result specifies the billing model.
purchasestring
Capacity purchase ID. May be omitted.
unitsintegerAlways present
Capacity units supplied by the plan.
unknownboolean
Whether the payment outcome is uncertain. Read capacity before buying again. May be omitted.
price_microsintegerAlways present
Combined price of new purchases per billing period, in millionths of a dollar.
regionstring
Pool's region. May be omitted.
storage_bytesintegerAlways present
Pool's included storage, in bytes.
unitsintegerAlways present
Pool's capacity in units.
vcpusintegerAlways present
Pool's vCPU allocation.
request_idstringAlways present
Request ID for this creation.
roomobject
Request's capacity check, when available. May be omitted.
Show 7 attributesHide attributes
computersintegerAlways present
Number of Computers requested.
fitsbooleanAlways present
Whether the request fits the pool's available storage and creation limits.
needs_bytesintegerAlways present
Estimated additional storage needed by the request, in bytes.
poolstringAlways present
Pool checked.
storage_bytesintegerAlways present
Pool's included storage, in bytes.
stored_bytesintegerAlways present
Storage already occupied in the pool, in bytes.
waiting_for_memoryintegerAlways present
Of the Computers the pool is creating, how many are waiting for memory in the pool.
waitingboolean
Whether purchases await payment. Heaven creates the pool and Computers once payment is confirmed. May be omitted.
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
#- CLI:
heaven loginwithHEAVEN_API_KEYunset. MCP: Heaven sign-in. cURL:HEAVEN_SIGN_IN_KEYfrom approved device sign-in (POST /v1/auth/create). - A key limited to a command list cannot run this command.
- For retries, reuse the original
Idempotency-Keyand inputs. - From capacity: Create a pool from purchased capacity. Required:
memory. Optional:server,name,dry_run,organization. - Buy a plan: Buy the selected plan and allocate all of its capacity to a new pool. Required:
buy. Optional:months,offer,server,name,dry_run,organization. - Of units: Create a pool using available capacity and buying any shortfall. Required:
units. Optional:buy.monthly,buy.hourly,name,dry_run,organization. - Copy: Copy a pool or pool snapshot into available capacity on the source's server. Required:
copy. Optional:memory,name,dry_run,organization.