API reference
Use API operations and interpret their results
Read the available endpoints, idempotency rules, queued-action responses and current limits on operation tracking.
On this page
Before you start
- A valid session and, for protected changes, its CSRF token.
- Identifiers taken from the current catalogue or authenticated API responses.
- A unique Idempotency-Key for each order, withdrawal or hardware action.
Read the account before changing it
Use the read endpoints to confirm the account, balance and target resource. GET /api/v1/me returns username, balanceUsd and the session’s csrfToken. Resource identifiers are account-specific; use the server or network identifier returned for the current account rather than copying a value from another environment.
The current API is a compact account interface, not a complete asynchronous job platform. Save references from successful writes in your own records. There is no endpoint to list every order, inspect a specific queued action or retrieve a withdrawal’s latest review status.
| Read endpoint | Returned data |
|---|---|
| GET /api/v1/ledger | The latest 100 ledger entries, newest first; no pagination contract. |
| GET /api/v1/servers | Non-terminated servers, state, region, paidThrough, graceUntil and autoRenew. |
| GET /api/v1/network | Assigned addresses, prefix lengths, PTR values and related server identifiers. |
| GET /api/health | Basic service and catalogue counts; no account or physical-server health guarantee. |
Use the matching change endpoint
Supported server actions are reboot, power_off, reinstall, mount_iso, kvm and rotate_root_password. A custom ISO URL must use public HTTPS without embedded credentials. Order term is weekly or monthly, representing seven or thirty days. Price, discounts, funds and capacity are checked by the service; do not send a client-computed price as authority.
| Endpoint | Request fields and result |
|---|---|
| POST /api/v1/orders | configId, regionId, osId, term, quantity; optional sshPublicKey. Returns order id and ACCEPTED. |
| POST /api/v1/deposit-addresses | asset. Returns address, asset, network, confirmationsRequired and mode, or settlement-unavailable error. |
| POST /api/v1/withdrawals | asset, destination, usd. Returns id and PENDING_REVIEW; balance is held. |
| POST /api/v1/servers/{id}/actions | action; isoUrl for mount_iso. Returns action id and QUEUED. |
| PUT /api/v1/servers/{id}/ddos | mode: BASELINE or ADVANCED. Returns QUEUED or UNCHANGED and quoteRequired. |
| PUT /api/v1/network/{id}/rdns | ptr, or an empty value to clear it. Returns the stored PTR value. |
Make retries deliberate
Orders, withdrawals, server actions and DDoS requests require Idempotency-Key. Use 8–100 letters, numbers, hyphens or underscores, and allocate a new key for each distinct intended operation. Preserve the original key, resource and payload before sending so an uncertain response can be investigated.
Orders can replay the existing result for the same key and normalized request; changed order details produce a conflict. Server-action replays return the existing action when compatible. Keep action keys unique across all servers in the account. Withdrawals report a conflict when already recorded rather than returning the original request as a success.
POST /api/v1/servers/{serverId}/actions HTTP/1.1
Content-Type: application/json
x-csrf-token: <current-session-token>
Idempotency-Key: <unique-operation-key>
Cookie: <current-session-cookies>
{"action":"reboot"}Distinguish acceptance from completion
A 202 QUEUED response confirms that a hardware request was recorded. It does not contain a working KVM URL, a replacement root password or proof that the machine restarted. Likewise, ACCEPTED records an order entering provisioning; PENDING_REVIEW records a withdrawal awaiting operator review. Preserve the returned identifier when asking about execution.
There is no action-status polling route in this version. Re-read the server or network data where relevant, and obtain operator confirmation for physical effects. A stored PTR or DDoS preference alone is not a measurement of public DNS or live network protection.
Respond to failures without duplicating work
- 400 validation error: correct the documented fields before resubmission.
- 401 or 403: repair session authentication or CSRF verification before retrying.
- 404: verify the resource identifier belongs to the signed-in account.
- 409: inspect the error code; insufficient balance, exhausted capacity and idempotency conflicts require different responses.
- 502 or 503 on deposits: no usable new address was returned; do not initiate a transfer.
- Timeout or unreadable response: check available account records and preserve the original request details. Do not blindly create a fresh operation key.