Skip to main content

Purchases and lifecycle

Orders and operations​

IdentifierMeaningRead result
api_key_idIntegration and its balanceGET /balance
api_user_idYour customer's string IDFilter VPS, rentals and orders
order_idA paid purchase, renewal or upgradeGET /orders/{order_id}
vm_idVPSGET /vms/{vm_id}
rental_idDedicated server rentalGET /dedicated/rentals/{rental_id}
ip_idIP allocationGET /ips
operation_idAn asynchronous VPS commandGET /vms/{vm_id}/operations/{operation_id}
operation_id for a rentalAn asynchronous dedicated power or reinstall commandGET /dedicated/rentals/{rental_id}/operations/{operation_id}

Purchases debit the integration balance when the order is accepted. Provisioning then proceeds asynchronously. A quote only calculates a price: it does not debit, create an order or reserve a resource. HTTP 202 confirms acceptance; it is not the final result.

Order statusMeaning
pendingSaved, waiting for processing
processingProcessing in progress
completedPaid action completed; for a dedicated purchase, reservation completed
failedAction failed; inspect the error and transaction history
refundedThe order amount was returned to the integration balance
reviewUncertain or partial outcome requiring clarification

For review or requires_review=true, inspect the resource and contact support before placing another paid or destructive command. Do not assume that a failed or uncertain response proves the resource was never created. Transactions show the actual balance movements; order_id can be null for top-ups and other unrelated movements.

After a lost response, reuse the original Idempotency-Key and unchanged parameters. Track existing orders rather than making new purchases to recover a result. Webhook delivery can repeat or fail, so keep a status lookup path in your integration.

VPS creation queue​

When capacity is unavailable, the paid order remains processing. Queue size returns the total waiting count for a location/platform across all buyers. Order queue shows your order's position, reason and can_cancel. Counts may lag by up to five seconds and do not predict delivery time; orders that cannot fit available capacity may be skipped during placement.

Cancel queue before resource reservation or provisioning starts. A successful cancellation returns the original charged amount once: billing status refunded, error code creation_cancelled. Expect order.refunded and vm.creation_cancelled; their delivery order is not guaranteed. The latter has vm_id=null, order_id and operation_id. This is not deletion of an issued VPS.

Use order_id in these routes. Queue status describes the provisioning operation, separately from the billing order. Before dispatch, the queue routes return 409 queue_not_ready; read the order and retry while it is pending or processing. If creation already started, cancellation returns 409 queue_cancel_unavailable. After a lost cancellation response, read the order or repeat the same DELETE; it does not need an Idempotency-Key and cannot refund the order twice.

VPS pricing and renewal​

Choose a CPU family before purchase: epyc — AMD EPYC, ryzen — AMD Ryzen, xeon — Intel Xeon. Different models of the same family may be used within a location. cpu_display_name is the family name; cpu_max_frequency_ghz is null because the exact model and frequency are determined after provisioning.

platform, cpu_display_name and cpu_max_frequency_ghz describe the physical CPU of the VPS current node and can be null when unknown. After migration, subsequent list/detail requests reflect the new node. cpu_display_name is the stored model text and may include physical core/thread counts; allocated VPS resources are defined by cpu_cores. Maximum frequency is CPU metadata, not a live measurement or a guaranteed frequency per vCPU. Read these fields from VPS lists/details, not creation events or operation results.

GET /plans includes datacenter in each location. Dedicated plans and VPS/dedicated rental lists and details also include datacenter: the location's datacenter name, or null if not specified.

Plan price depends on location, platform, plan and CPU share. The published monthly price already includes your integration markup. A multi-month purchase/renewal applies the current term discount; use quote routes for the total rather than multiplying the displayed monthly price yourself.

Terms are calendar months, not fixed 30-day blocks. The initial VPS duration is calculated at purchase; provisioning shifts the paid-until date to account for waiting and installation. After issue, parameters.paid_until in the order contains the actual date from the creation result; before issue it is provisional. Renewal extends the paid term, or starts from the current time if the service is already overdue. You can renew during the grace period, before deletion begins.

Plan upgrades cannot decrease CPU resources, RAM, disk or included traffic. Omitted cpu_percent preserves its current value. The surcharge is the price difference for the remaining paid calendar periods, using current plan prices and each period's original discount, including advance renewals. The payment deadline is preserved. A resize quote returns the maximum price to confirm in expected_amount_usd and the new monthly price.

Cloud-init​

VPS creation, its quote and OS reinstallation accept optional cloud_init: a JSON cloud-config object, not a YAML string. Omit it or send null for the standard installation.

{
"cloud_init": {
"packages": ["curl"],
"runcmd": [["sh", "-c", "echo ready > /root/cloud-init-ready"]]
}
}

The object is limited to 65536 bytes after server JSON serialization, which escapes non-ASCII characters. If supplied, users, packages, runcmd and write_files must be arrays. Networking, hostname and primary access remain platform-managed. Creation still requires exactly one of password or ssh_public_key. Retain the same cloud-init object when retrying the same purchase or command.

guest_initialization reports the installation result in VPS details, the purchase order, the reinstall operation result, and the corresponding webhooks:

Statuserror_codeMeaning
succeedednullCloud-init finished; this does not confirm application health
failedcloud_init_failedCustom configuration failed; the running VPS is retained
unknownguest_initialization_timeoutInitialization was not confirmed within 15 minutes; a confirmed running VPS with custom configuration is retained

The field may be null when no result is available. VPS details show the result of the latest installation. A purchase can be completed, or a reinstall operation succeeded, with initialization failed or unknown: inspect both results. A custom configuration failure alone does not cancel the purchase or refund it. Infrastructure failures still fail provisioning.

Cloud-init contents and execution output are not included in public order parameters or partner webhooks.

Applications​

Get the active application catalog and choose an application_id. Pass it with os_id to quote and purchase. OS codes in supported_os correspond to the OS catalog. Select resources using min_* and recommended_*; RAM is in MiB, disk in GiB. Null requirements mean unspecified values. Variants are grouped by app_code and selected by their numeric id.

Do not combine an application with a non-null cloud_init, including {}. The server service checks availability and compatibility during provisioning; a quote only calculates the VPS price, without confirming compatibility. A rejected creation follows the existing order refund flow. There is no separate application charge.

The application field in VPS lists/details, purchase orders and reinstall results contains public metadata and an installer_sha256 checksum, never the installer contents. The order retains the purchase snapshot; VPS data reflects the latest successful installation. Ordinary reinstallation retains the saved installer and checks OS compatibility. Explicit cloud_init, including {}, replaces it; application then becomes null. Selecting another application during reinstall is not supported.

For installation_mode=background (game applications), installation continues after VPS issue and the start of the paid period. guest_initialization.status=succeeded only confirms base cloud-init completion. There is no application-ready webhook. Check systemctl status adapt-application-install.service and journalctl -u adapt-application-install.service inside the VPS. Applications may still require initial setup, domains, tokens or licences.

Rescue​

Enable Rescue with PUT /vms/{vm_id}/rescue, an Idempotency-Key and JSON:

{
"api_key_id": 1,
"password": "Temporary-Rescue-2026!"
}

The temporary password is required: 5–128 characters without CR, LF or NUL. The VPS must be paid and have at least 2048 MiB RAM. Rescue restarts the VPS into a recovery environment and preserves disks and networking. After the operation succeeds, connect as root to the VPS IP over SSH on port 22 using that password. Firewall rules still apply.

Both enable and disable return HTTP 202 with an operation ID in data.id. Poll operation status. Successful results include vm_id, status and rescue; VPS details also expose rescue:

{
"active": true,
"access": "ssh",
"requires_review": false,
"operation_id": 501,
"operation_status": "succeeded"
}

active indicates saved Rescue context, not guaranteed current SSH availability. access can be ssh, console or null. The entire state may be null when unavailable. While Rescue is active, plan changes, OS reinstallation and normal OS password resets are unavailable.

Disable Rescue with DELETE /vms/{vm_id}/rescue?api_key_id=1 and a separate Idempotency-Key; no body or password is needed. This restores normal OS boot and starts the VPS if it is paid. An expired or suspended VPS remains stopped. Exit is also available from error when Rescue context is saved.

Check error_code and requires_review on failure. rescue_not_ready means Rescue readiness was not confirmed; inspect VPS state and exit Rescue. rescue_memory_required requires a plan with enough RAM; rescue_iso_missing or rescue_not_configured requires support. Retry a lost request with its original key and parameters.

VPS terminal​

Create a terminal link with POST /vms/{vm_id}/terminal/link?api_key_id=1. The VPS must be running. This opens the OS text console in the browser; the guest OS controls its login prompt. No JSON body or Idempotency-Key is needed. Open data.url unchanged; the one-time link is valid for five minutes before first use. The existing graphical console remains available separately.

Traffic and IPv4​

Extra VPS traffic and separately billed IPv4 have fixed prices without integration markup or term discounts.

  • Traffic: an integer number of units, each equal to 1024⁴ bytes, valid only for the current traffic period. Quote returns expected_period_id and period_ends_at; send that period ID when buying to reject an expired quote. Unused extra traffic does not carry over.
  • IPv4 purchase: one additional address attached to a VPS, paid for 1/3/6/12/24/36 calendar months (default 1) independently of the VPS term. At most 10 IPv4 per VPS including its primary address.
  • IPv4 renewal: the selected calendar-month term, from the later of now and paid_until, at the current fixed price. Applies to paid additional or saved IPv4; an included primary IPv4 and IPv6 cannot be renewed separately.
  • Saved addresses: GET /ips?api_key_id=1&attachment=unattached. Keeping an address continues its billing even without a VPS.

To move an additional IPv4, detach it with keep_ip=true, then attach it to a compatible VPS of the same customer (api_user_id). The saved address must remain paid and available. Attachment does not buy an address or extend its term. Check guest_configuration_required and update guest OS networking if needed.

Detaching with keep_ip=false releases the address. DELETE /ips/{ip_id} releases a saved, unattached IPv4. An existing primary IPv4 cannot be detached from its VPS.

Dedicated rentals​

  1. Read dedicated plans, availability, allowed disk layouts and term discounts. Layout options contain code and name: display name (for example, No Raid) and submit code (separate). Shared-layout plans use the top-level options; disk-group plans, including Storage, use options inside each disks[] entry.
  2. Quote, then buy using plan_id, os_id, the disk selection, customer ID and a password or SSH public key. The physical server is selected by the platform.
  3. Save order_id and later rental_id. order.completed confirms reservation, not readiness.
  4. Wait for dedicated.issued or rental status active. Read rental details for addresses and credentials. The rental term starts on issue.

For a shared-layout plan, send disk_layout. For a disk-group plan, send only disk_layouts, mapping every disks[].id to the chosen code:

{
"disk_layouts": {
"94dc1d25-4d4f-4c6b-a8e3-a226f66254a1": "raid1",
"dc8c3bfe-021d-4d40-adbe-55784a0b71e2": "raid6"
}
}

IDs above are examples: use the opaque IDs from your selected plan, not disk types. Each group provides its own default_disk_layout; the client must submit the selection explicitly. Missing/extra groups, unsupported codes, an empty map or both formats return 422 before charging. Grouped catalog plans have top-level disk_layouts=[] and default_disk_layout=null. Rental lists/details preserve the selected map and return disk_layout=null; use plan.disks from the rental snapshot to label the groups. Snapshot options remain string codes. Repeating an order requires the same selections; object key order does not matter.

Rental states: preparing → active → overdue → cleaning → completed. An unissued cancelled rental can end as cancelled. cleaning means release/cleanup is already underway; do not promise renewal at that point.

Extra IPv4 selected in extra_ipv4_count are billed as part of the dedicated rental at a fixed price. Use the dedicated renewal quote for the full amount. The separate VPS /ips purchase and renewal flow is not the dedicated rental billing flow.

If an administrator cancels a rental before issue, the original dedicated purchase is refunded once to the integration balance; expect order.refunded and dedicated.released. Ordinary expiry or release of an issued service is not an automatic refund.

HDD groups support RAID 5 (at least 3 disks), RAID 6 (at least 4) and RAID 10 (an even number of at least 4). Submit an option only if listed in disks[].disk_layouts. These three options are unavailable for NVMe/SSD and shared layouts.

Power and reinstallation​

Read rental status for power_state, supported power_actions and the reinstall capability. Management is available for active, paid rentals on configured servers. Initial issue remains manual, within 72 hours. Automatic OS reinstallation is currently unavailable for disk-group rentals, including Storage.

Power control and OS reinstallation return HTTP 202 with an operation ID. They do not create a financial order or charge the balance. Use an Idempotency-Key for each command; retry a lost response with the same key and unchanged body. Follow the operation, history or the corresponding webhook.

Reinstallation erases disk data and requires confirmed: true and os_id. Omitting both password and ssh_public_key retains current credentials. Sending either replaces the whole credential set: provide a password, SSH public key or both. IPs, owner and paid term are retained. Retrieve updated credentials from rental details after success. A pending operation or failed operation with unresolved requires_review blocks further commands; contact support. review_resolved_at records the administrator's review without changing the original result.

Auto-renewal and expiry​

auto_renew defaults to false and can be set on purchase or changed later via PATCH for a VPS, rental or separately paid IPv4. Changing the flag does not charge money immediately. Each service has its own setting.

ServiceRenewal termPrice
VPSSame number of months as its latest paid purchase/renewalCurrent plan price, integration markup and current term discount
Dedicated rentalSame number of months as its latest paid purchase/renewalCurrent rental price, markup, term discount and extra IPv4 charge
Separate IPv4Last paid calendar-month termCurrent fixed monthly IPv4 price × term

When enabled, Cloud API attempts renewal from the integration balance on the warning one hour before expiry. If the service expires, a final warning one hour before its release/deletion triggers another attempt. Insufficient balance does not extend the service. A balance top-up does not itself trigger an immediate retry; use manual renewal when needed.

Overdue VPS and paid IPv4 are suspended; the grace period is 24 hours. Without payment they are deleted/released. Dedicated rentals become overdue and then enter cleanup/release after the grace period. Processing is asynchronous; a deadline is not a guarantee that cleanup finishes at that exact second.

Partner warnings are delivered through Webhooks, including vm.deleting_soon, ip.releasing_soon and dedicated.releasing_soon, even when auto-renewal is disabled or funds are insufficient. A warning is not proof of a successful renewal: check the resulting paid term.

Backups​

Backups belong to a separate storage service and remain available after the source VPS is deleted. Use the backup service list with api_user_id or vm_id to find them.

Create a service for an existing VPS with POST /backup-services and a new Idempotency-Key:

{"api_key_id": 1, "vm_id": 101, "kind": "automatic", "auto_renew": false}

automatic creates the first copy on activation, then daily, retaining the latest 7 successful copies. Use kind: "manual" for one copy with its own storage service. The paid period is one calendar month from activation. Prices in /plans have no integration markup, CPU factor or term discount.

  • Automatic storage is charged upfront at the plan's monthly price. A failed purchase is refunded after cleanup.
  • Manual storage is charged after capture: stored_size_bytes / 1073741824 × manual_backup_gb_month_price_usd, using the rate saved at purchase and rounding to four USD decimals. Its pending order amount is zero until the size is known. If the balance is insufficient, the copy is deleted; integrations with permitted negative balance are charged normally into the negative.
  • GET /vms/{vm_id}/backup-estimate provides an estimate, not the final billable size. Copy access requires confirmed initial payment.

All backup commands with Idempotency-Key return HTTP 202 and an order, including free restoration, export and deletion. Poll /orders/{order_id} for payment and final status. backup_service_id, backup_id and worker_operation_id appear when known; the operation endpoint reports execution, not billing. Reuse the same key and body after a timeout.

Renew storage with POST /backup-services/{service_id}/renew, body {"api_key_id": 1}. The term is one calendar month from the later of now and the current paid_until, at current backup prices. Automatic storage uses the current VPS plan, or the last saved plan after VPS deletion. Manual storage uses the measured copy size. PATCH the service with {"api_key_id": 1, "auto_renew": true} to enable renewal 24 hours before expiry, with a final attempt one hour before deletion. The unpaid grace period is 24 hours. Disabling auto-renewal does not cancel a renewal already accepted.

Restore and download​

POST /backups/{backup_id}/restore with {"api_key_id": 1, "vm_id": 101} overwrites the original VPS's disks. For a new VPS, use the normal POST /vms with backup_id instead of os_id; keep the same api_user_id as the backup. Omit password, SSH key, application and cloud-init fields: OS, credentials and programs come from the copy. The new VPS is billed at the normal plan price, including markup and term discount. Select enough disk capacity for all disks in the copy.

Restoring has no separate fee. Both modes share a limit of 3 accepted restores per storage service per rolling 24 hours. Pending and failed attempts count; retries with the same key do not. An exceeded limit returns 429 with detail.code=backup_limit_reached.

POST /backups/{backup_id}/exports with {"api_key_id": 1} prepares a ZIP64 archive of raw disks and configuration. There is no separate fee; the limit is 1 accepted preparation per copy per rolling 24 hours, with the same retry rules. Read the order's worker_operation_id, then /backup-exports/{operation_id} and /backup-exports/{operation_id}/download. The file lives for 24 hours after completion; a link lasts at most 1 hour, never beyond file expiry. Reissuing a link neither spends another slot nor extends storage. Download count is not limited.

Delete one automatic copy with DELETE /backups/{backup_id}. For a manual copy, delete the whole service with DELETE /backup-services/{service_id}; this also removes every copy of an automatic service. Pass api_key_id in the query and Idempotency-Key in the header. Deletion is irreversible and does not refund unused storage time.

VPS commands and deletion​

Commands return an operation: queued → running → succeeded / failed. Check the operation and current resource state; HTTP 202 is only acceptance. Graceful shutdown/reboot differ from forced stop/reset. Reinstallation destroys system disk data; wipe_extra_disks=true also opts into removing additional disks.

For firewall changes, first read the rules and revision. Send that revision with every mutation; on conflict reread the settings. Reordering requires the full set of rule IDs, each once. Use the separate PATCH /vms/{vm_id}/firewall/smtp endpoint to open or close SMTP ports.

VPS deletion requires explicit keep_ips:

  • true: retain IPv4, including the former primary IPv4, as separately paid addresses. Inspect held_ips in the operation result and the address list for billing dates and settings.
  • false: release the addresses along with the VPS.

Deletion, address release and unused paid time do not create a prorated refund. Save required data before deleting or reinstalling.

IPv4 without a VPS​

Call the quote, then purchase with api_key_id, api_user_id, location_id, months and optional auto_renew (default false). Terms are 1/3/6/12/24/36 calendar months; price is the monthly rate times the term without markup or discount. Use expected_amount_usd to confirm the quoted total. Do not send a cluster or VPS.

After order.completed, read ip_id and paid_until from the order; the address appears in GET /ips?attachment=unattached and belongs to the specified customer. Expect ip.allocated; attach the address to that customer’s VPS when needed. Repeating the original Idempotency-Key does not allocate or charge again.

Manual renewal accepts optional months; omission and auto-renewal use the last paid term. Legacy 30-day rentals switch to one calendar month on their next renewal if months is omitted. Renewal uses current pricing. Buying an extra address through the VPS route accepts the same calendar-month terms.

IPv4 calendar terms​

Months are added to the current UTC purchase time, or to max(current time, paid_until) on renewal. If that day does not exist in the target month, its last day is used: January 31 → February 28, or February 29 in a leap year. Price is the monthly rate × months, without discounts or markup. Attaching or detaching an IP preserves its paid term and does not charge again.

© 2026 AdaptGroup LLC. All rights reserved.
30 N Gould St Ste R, Sheridan, WY 82801, USA
Back to top