Cloudj · https://cloudj.net/v1 · 2026-10-29
Getting started
API Reference
Automate Cloudj from your own code. The REST API at https://cloudj.net/v1 speaks JSON over HTTPS, uses standard verbs and status codes, and authenticates with an API key.
This reference covers Catalog, Virtual Machines, VM Networking, Snapshots, Console and AI Agent, SSH Keys, Billing, DDoS Shield, Kubernetes, Private Cloud, Bandwidth, Images, VPN and Proxy, Scaling, Block Storage, Backups, Account, Object Storage, GPU Cloud, Support Tickets, Affiliate, Service Transfers, Dedicated Servers, AI Models, Bring Your Own IP, API. Every endpoint lists the scope it needs, its parameters, its response and an example you can copy as curl, CLI, JavaScript, Python or Go.
Make your first request
- Create an API key. Open Dashboard, API keys, pick the narrowest scopes you need and copy the key. It is shown once.
- Store it. Keep it in an environment variable on your server, never in client-side code.
- Call the API. Send the key as a Bearer token, as in the example.
Every response carries an X-Request-Id header. Quote it when you contact support.
Authentication and API keys
Authenticate every request with the header Authorization: Bearer vk_.... Keys start with vk_ and are created in the dashboard under API keys. The full key is shown only once, so store it safely.
- Each key has a list of scopes, and can have an expiry date and a list of allowed IP addresses (single IPs or CIDR ranges, IPv4 and IPv6).
- Revoke a key at any time from the same page. A revoked or expired key stops working immediately.
- A key only sees and changes resources of the account that owns it.
Use keys from your servers. The API does not enable CORS, so a browser on another site cannot call it, and a key placed in a web page or mobile app is public. The Try it panels in this reference send requests from this page to this site only.
What a key can never do
For your safety, API keys cannot top up or withdraw money, change cards or auto top-up, change your password, email or two-factor settings, delete your account, or create or revoke other keys. Those actions always require signing in by hand.
Authentication errors
A missing or bad key returns 401 with one of these codes: key_invalid, key_revoked, key_expired, key_ip_denied, api_keys_disabled or site_mismatch. See Errors.
Scopes
A key can only call endpoints inside the scopes you gave it. Scopes follow the pattern resource:action. Each endpoint below shows the scope it needs. A missing scope returns 403 with the code scope_required; a path that is not part of this reference returns 403 endpoint_not_public.
- account:read — Read your profile, overview, activity, bandwidth and notifications
- account:write — Mark notifications as read (nothing else)
- aff:read — Read the affiliate program: code, referrals, commissions (READ ONLY)
- ai:read — Read AI models and prices, AI keys (no secrets), usage, request logs and budget settings
- ai:write — Edit AI keys (name, status, models, budgets, RPM/TPM) and account budget/limit settings
- apikey:read — List the account's API keys and key usage log (cannot create, edit or revoke keys)
- apikey:self — Inspect the calling key itself (every key has it implicitly)
- backup:read — Read backups, backup schedules and pricing
- backup:restore — RESTORE a VM from a backup (overwrites the disk)
- backup:write — Enable/disable backup, create/delete backups, set schedules (storage billed per GB-hour)
- bandwidth:buy — BUY Bandwidth Add-ons (costs money)
- billing:read — Read wallet, invoices, payments (READ ONLY)
- byoip:create — Register a new own IP prefix (may charge the wallet once verification passes)
- byoip:destroy — Cancel an own IP prefix (removes the setup and stops the BGP announcement)
- byoip:read — Read your own IP prefixes (BYOIP), verification results, ROA/IRR instructions, quotes and activity
- byoip:write — Re-verify, request review, attach/detach own IP prefixes to VMs
- catalog:read — Read plans and catalog
- dedicated:console — Open Dedicated Server consoles
- dedicated:create — Order Dedicated Servers (charges the wallet)
- dedicated:destroy — ERASE the disks: reinstall the OS of Dedicated Servers (DELETE, data is lost)
- dedicated:read — Read Dedicated Servers: hardware, status, sensors, hardware log, bandwidth
- dedicated:write — Power on/off/reboot, rename and renew Dedicated Servers
- gpu:console — Open SSH WebSocket tickets for GPU instances
- gpu:create — RENT GPU instances (costs money)
- gpu:destroy — DELETE or recycle GPU instances (data is lost)
- gpu:read — Read GPU instances, quotes, diagnostics and logs
- gpu:write — Start/stop/reboot GPU instances and request logs (a restart can charge the wallet)
- image:read — Read your OS Images / ISO Images
- image:write — Import images from URL, create from instances, delete, attach/detach ISO (storage is billed hourly)
- k8s:create — CREATE Kubernetes clusters (costs money)
- k8s:destroy — DELETE Kubernetes clusters
- k8s:kubeconfig — Download kubeconfig (cluster-admin access)
- k8s:read — Read Kubernetes clusters, nodes, logs, billing
- k8s:scale — SCALE Kubernetes workers (costs money)
- k8s:write — Start/stop, rename Kubernetes clusters
- s3:create — CREATE S3 accounts (usage is billed)
- s3:destroy — DELETE S3 accounts, buckets and objects (data is lost)
- s3:keys — List, create, rotate and delete S3 access keys (the secret is shown once)
- s3:read — Read S3 accounts, buckets, object listings, usage and cost
- s3:write — Create buckets, edit S3 accounts, manage share links and object operations (uploads, downloads, public access; deleting objects also needs s3:destroy)
- shield:agent — Control the agent on your own machine (block/unblock IP commands, auto-block, thresholds) — high risk
- shield:read — Read your own DDoS Shield
- shield:write — Write your own DDoS Shield rules
- sshkey:read — Read stored SSH keys
- sshkey:write — Add/remove SSH keys
- ticket:read — Read your support tickets
- ticket:write — Create, reply to and close support tickets
- transfer:read — Read service transfer requests (READ ONLY)
- vm:console — Open VNC console tickets
- vm:create — CREATE new VMs (costs money)
- vm:destroy — DELETE VMs
- vm:plan — CHANGE PLAN / custom resize (costs money)
- vm:read — Read VMs, metrics and VM invoices
- vm:restore — RESTORE a VM from a snapshot (overwrites the current disk)
- vm:write — Power actions, minor changes, firewall, snapshots
- volume:create — CREATE / ENLARGE data volumes (costs money, billed per GB-hour)
- volume:destroy — DELETE data volumes (data is lost)
- volume:read — Read data volumes and volume quotes
- volume:write — Attach/detach data volumes
- vpc:create — CREATE Private Cloud / CHANGE bandwidth plan (costs money)
- vpc:destroy — DELETE Private Cloud
- vpc:read — Read Private Cloud, tiers, Network ACL, bandwidth, billing
- vpc:write — Edit Network ACL, tiers, name, auto-renew (enabling auto-renew may renew from the wallet)
- vpn:create — BUY / RENEW / upgrade bandwidth / add features to VPN & Proxy IPv6 plans (costs money)
- vpn:destroy — CANCEL or remove VPN & Proxy IPv6 plans from the list (immediate, no refund; IPs return to the pool)
- vpn:detail — Read VPN / Proxy IPv6 plan management details: config export (incl. passwords), traffic, logs, authorized IPs, IP reports, upgrade/cancel quotes
- vpn:read — Read VPN / Proxy IPv6 plans and connection details (incl. proxy passwords)
- vpn:write — Edit VPN / Proxy IPv6 plans: auto-renew (enabling may renew from the wallet), authorized IPs, IP rotation, proxy password, device release, IP reports, feed link — returns fresh connection secrets
Give each key the minimum it needs. A monitoring script only needs read scopes, and scopes that spend money or delete resources should be separate keys.
Rate limits
Each API key may send 120 requests per minute, and all keys of one account together may send 300 requests per minute. Limits use a fixed 60-second window.
Every response from an authenticated request includes these headers, taken from whichever limit is tighter:
| Header | Meaning |
|---|---|
X-RateLimit-Limit | Requests allowed in the current window. |
X-RateLimit-Remaining | Requests left in the current window. |
X-RateLimit-Reset | When the window ends, as a Unix timestamp in seconds. |
Retry-After | Only on 429: seconds to wait before retrying. |
Over the limit you get 429 with the code rate_limited. Back off for Retry-After seconds, then retry. Prefer fewer, paginated list calls over many single reads.
Idempotency
Endpoints that spend money or cannot be repeated safely require an Idempotency-Key header: any unique string up to 200 characters, such as a UUID. Without it the request fails with 400 idempotency_key_required.
- Repeat a request with the same key and you get the original result back, with the header
Idempotency-Replayed: 1. The action is not performed twice, so a flaky network never charges you twice. - Only successful (2xx) results are stored. A request that failed can be retried with the same key.
- Results are kept for about 24 hours. Keys are scoped to the API key that sent them.
- While a request with that key is still running, a second one returns
409 idempotency_in_progresswithRetry-After: 1. Retry the same key. - Use a new key for each new operation, and reuse a key only to retry the same operation.
Endpoints that require it
- POST /v1/bandwidth/objects/{kind}/{ref}/addons — Buy a Bandwidth Add-on (charges the wallet)
- POST /v1/byoip — Register an own IP prefix (waits for verification, not charged yet)
- POST /v1/byoip/subnets — Order an IPv4 subnet (charges the first month and the setup fee)
- POST /v1/byoip/subnets/{id}/cancel — Cancel a subnet (before leasing: full refund; in use: stop renewal)
- POST /v1/byoip/{id}/cancel — Cancel a prefix (remove the setup, withdraw BGP)
- POST /v1/byoip/{id}/move — Move prefix from one VM to another in one step
- POST /v1/byoip/{id}/vms — Attach prefix to an additional VM
- DELETE /v1/byoip/{id}/vms/{vm} — Detach prefix from VM (last VM ⇒ prefix pending attachment, BGP retained)
- POST /v1/byoip/{id}/vpc-requests — Request prefix attachment to Private Cloud (manually set up by network team)
- DELETE /v1/byoip/{id}/vpc-requests/{rid} — Cancel pending Private Cloud attachment request
- POST /v1/dedicated/order — Order a Dedicated Server: charges the wallet, assigns a machine and IP, installs the chosen operating system (automatic refund if the install fails)
- POST /v1/dedicated/{id}/iso — Download an ISO from an http(s) URL into the server's temporary storage (asynchronous)
- POST /v1/dedicated/{id}/iso/attach — Attach the ISO to the server as virtual media and set a one-time CD boot (asynchronous, returns an op)
- POST /v1/dedicated/{id}/power — Power on/off/reboot a Dedicated Server (asynchronous, returns an op)
- POST /v1/dedicated/{id}/reinstall — Reinstall the OS of a Dedicated Server (erases the disks, asynchronous, returns an op)
- POST /v1/dedicated/{id}/renew — Pay the open renewal invoice or renew one cycle early (charged from the wallet at the subscription's locked price)
- POST /v1/gpu — Rent a GPU instance from a quote (charges the wallet)
- DELETE /v1/gpu/{id} — Delete the GPU instance (data is lost)
- POST /v1/gpu/{id}/recycle — Recycle the GPU instance from its template (data is lost)
- POST /v1/gpu/{id}/start — Start the GPU instance (can charge a new billing period)
- POST /v1/images — Import an image/ISO from URL (storage billed hourly)
- POST /v1/images/from-vm — Create an image from a stopped instance
- POST /v1/k8s/clusters — Create a cluster (prepaid cycles charge the wallet)
- DELETE /v1/k8s/clusters/{id} — Delete the cluster (data is lost)
- POST /v1/k8s/clusters/{id}/scale — Change worker count (costs money)
- POST /v1/portal/tickets — Open a support ticket
- POST /v1/proxy6/subscriptions — Buy a Proxy IPv6 plan (charges the wallet)
- DELETE /v1/proxy6/subscriptions/{id} — Remove a canceled or expired Proxy IPv6 plan from your list
- POST /v1/proxy6/subscriptions/{id}/cancel — Cancel a Proxy IPv6 plan now (no refund; addresses are released)
- POST /v1/proxy6/subscriptions/{id}/renew — Renew a Proxy IPv6 plan (charges the wallet)
- POST /v1/proxy6/subscriptions/{id}/rotate — Rotate the IPv6 address now (uses one rotation of the plan)
- POST /v1/s3 — Create an S3 account (usage-billed)
- DELETE /v1/s3/{id} — Delete the S3 account (all buckets must be removed first)
- DELETE /v1/s3/{id}/buckets/{bucket} — Delete a bucket (must be empty)
- POST /v1/tenants/{tid}/targets/{id}/ai/analyze — Ask the AI to analyze one protected IP (uses a daily quota)
- POST /v1/tenants/{tid}/targets/{id}/rtbh — Blackhole one of your IPs upstream (RTBH) — the IP goes offline for the chosen scope
- POST /v1/vm — Create a VM (charges the wallet)
- DELETE /v1/vm/{id} — Delete the VM (data is lost)
- PUT /v1/vm/{id}/autoscale — Enable/disable and set the Auto Scaling rule (grows the VM with load)
- POST /v1/vm/{id}/backup/disable — Disable backup (only when no backups remain)
- POST /v1/vm/{id}/backup/enable — Enable backup for the VM (storage is billed)
- POST /v1/vm/{id}/backups — Create a backup now (storage is billed)
- POST /v1/vm/{id}/backups/{bid}/restore — Restore the VM from a backup (stops, overwrites the disk, restarts)
- POST /v1/vm/{id}/byoip/attach — Attach your own-IP network to a VM (adds a NIC)
- POST /v1/vm/{id}/byoip/detach — Detach your own-IP network from a VM
- POST /v1/vm/{id}/change-custom — Custom resize
- POST /v1/vm/{id}/change-cycle — Change the billing cycle (prorated)
- POST /v1/vm/{id}/change-ip — Change the public IP (cooldown between changes)
- POST /v1/vm/{id}/change-plan — Change plan (prorated)
- POST /v1/vm/{id}/reinstall — Reinstall the OS (WIPES the disk)
- POST /v1/vm/{id}/renew — Renew a prepaid VM (charges the wallet)
- POST /v1/vm/{id}/scale — Resize CPU/RAM/disk now or scheduled (charges or refunds)
- POST /v1/vm/{id}/scale/revert — Return the VM to its base size after Auto Scaling (reboots)
- POST /v1/vm/{id}/snapshots/{sid}/restore — Restore the VM to a snapshot (stops, overwrites the disk, restarts)
- POST /v1/volumes — Create a data volume (billed per GB-hour)
- DELETE /v1/volumes/{vid} — Delete a data volume (data is lost permanently)
- POST /v1/volumes/{vid}/resize — Enlarge a data volume (grow only, costs money)
- POST /v1/vpc — Create a Private Cloud (prepaid cycles charge the wallet)
- DELETE /v1/vpc/{id} — Delete the Private Cloud (no VMs left)
- POST /v1/vpc/{id}/plan — Change bandwidth plan (costs money)
- POST /v1/vpn/subscriptions — Buy a VPN IPv4 plan (charges the wallet)
- DELETE /v1/vpn/subscriptions/{id} — Remove a canceled or expired VPN IPv4 plan from your list
- POST /v1/vpn/subscriptions/{id}/addons — Add features to a plan mid-term (charges the wallet)
- POST /v1/vpn/subscriptions/{id}/bandwidth — Upgrade the bandwidth tier mid-term (charges the wallet)
- POST /v1/vpn/subscriptions/{id}/cancel — Cancel a VPN IPv4 plan now (no refund; IPs are released)
- POST /v1/vpn/subscriptions/{id}/renew — Renew a VPN IPv4 plan (charges the wallet)
Pagination and sorting
List endpoints that can return many rows are paginated. They accept these query parameters, and each endpoint documents the ones it supports:
| Parameter | Meaning |
|---|---|
page | Page number, starting at 1. |
per_page | Rows per page. Default 25, maximum 100 on most endpoints. |
sort | Column to sort by. Allowed columns are listed per endpoint; an unknown column falls back to the default. |
dir | asc or desc (default desc). |
q | Free-text filter where supported. |
Paginated responses wrap the rows in items and report total, page and per_page. Request the next page until page * per_page reaches total.
Errors
Errors use standard HTTP status codes and always the same JSON shape. code is stable and safe to branch on; message is for people and may change. Some errors add fields next to them, such as need_cents.
| Status | Meaning |
|---|---|
| 200 / 201 | Success. Creation endpoints return 201 with the new resource. |
| 400 | The request is malformed or a required header is missing. |
| 401 | Authentication failed. See the key error codes below. |
| 402 | Insufficient wallet balance (code insufficient_funds). The error object adds need_cents and balance_cents. |
| 403 | The key is valid but not allowed to do this. |
| 404 | Not found, or the resource belongs to another account. The two cases are deliberately identical. |
| 409 | Conflict with the current state, for example an action is already running. |
| 422 | The request is well-formed but a value is not acceptable. The code says which, for example invalid_hostname. |
| 429 | Rate limit exceeded. |
| 5xx | Server-side problem. Safe to retry GET requests; for write requests retry with the same Idempotency-Key. |
Codes returned for every endpoint
| Status | Code | When |
|---|---|---|
| 400 | idempotency_key_required | The endpoint spends money or cannot be repeated, and the Idempotency-Key header is missing. |
| 401 | key_invalid | The key is unknown or malformed. |
| 401 | key_revoked | The key was revoked. |
| 401 | key_expired | The key passed its expiry date. |
| 401 | key_ip_denied | The request IP is not in the key's allowed list. |
| 401 | api_keys_disabled | API keys are temporarily disabled on this site. |
| 401 | site_mismatch | The key belongs to another site. Use it on the site where it was created. |
| 403 | scope_required | The key lacks the scope this endpoint needs. The message names it. |
| 403 | endpoint_not_public | The path is not part of the public API, so no key can call it. |
| 409 | idempotency_in_progress | A request with the same Idempotency-Key is still running. Retry the same key after a moment. |
| 429 | rate_limited | Too many requests. Wait for Retry-After seconds. |
| 500 | internal | Unexpected error. Quote the X-Request-Id when contacting support. |
During a maintenance window, write requests return 503 with the code maintenance. That one response uses a flat body: {"error":"maintenance","message":"..."}.
Versioning and changelog
The version is part of the URL: every endpoint here lives under /v1. Within v1, new endpoints, optional parameters and response fields can be added at any time, so ignore fields you do not recognise. Breaking changes are not made to v1 without notice.
2026-10-19 · Reference rebuilt
- Request and response schemas, examples and error lists for every endpoint.
- A command-line name for every endpoint, the command-line client and an MCP server.
- Downloads: OpenAPI JSON and YAML, Postman, Insomnia, Markdown and PDF.
2026-09-24 · Public API v1
- API keys with scopes, per-key and per-account rate limits and Idempotency-Key.
OpenAPI document version: 1.0.0.
Tools
Command-line interface
The cloudj command-line client turns every endpoint in this reference into a command, generated from the same OpenAPI document, so it always matches the API. It is one static binary for Linux, macOS and Windows (amd64 and arm64) with no runtime to install, and it has tab completion, table, JSON and YAML output, and confirmation prompts before it deletes data or spends money.
Install
curl -fsSL https://cloudj.net/cli/install.sh | shThe script picks the package for your system, checks the signature of SHA256SUMS with the release key built into the script (needs ssh-keygen from OpenSSH 8.0 or newer), checks the package SHA-256, then installs cloudj into /usr/local/bin as root or ~/.local/bin otherwise. If a check fails, nothing is installed. macOS uses one universal binary for Intel and Apple silicon.
| Variable | Meaning |
|---|---|
CLOUDJ_VERSION | Version to install, for example 1.0.0. Default: the latest release. |
CLOUDJ_INSTALL_DIR | Install folder. |
CLOUDJ_REQUIRE_SIGNATURE | 1 aborts when the signature cannot be verified, for example without ssh-keygen, instead of warning. |
CLOUDJ_BASE_URL | Download base, for mirrors. Default https://cloudj.net/cli. |
Download manually
Current version 1.0.0. latest.json lists every file with its size and SHA-256.
| Platform | Package | Size |
|---|---|---|
| macOS Intel and Apple silicon | cloudj_1.0.0_darwin_universal.tar.gzSHA-256 in SHA256SUMS | - |
| macOS Apple silicon | cloudj_1.0.0_darwin_arm64.tar.gzSHA-256 in SHA256SUMS | - |
| macOS Intel | cloudj_1.0.0_darwin_amd64.tar.gzSHA-256 in SHA256SUMS | - |
| Linux x86-64 | cloudj_1.0.0_linux_amd64.tar.gzSHA-256 in SHA256SUMS | - |
| Linux ARM64 | cloudj_1.0.0_linux_arm64.tar.gzSHA-256 in SHA256SUMS | - |
| Windows x86-64 | cloudj_1.0.0_windows_amd64.zipSHA-256 in SHA256SUMS | - |
| Windows ARM64 | cloudj_1.0.0_windows_arm64.zipSHA-256 in SHA256SUMS | - |
Verify a download
Every release ships a SHA256SUMS list signed with the release key (ed25519, SSH signature, namespace cloudj-cli), published at cloudj-cli.pub with fingerprint SHA256:vCVyAjURUjskvxnf1vE2EJ5JvMFImd61RfFz6byZ0ZE. Check the signature first, then the sum, before you run anything.
# 1. download the checksums, the signature and the release key
curl -fsSLO https://cloudj.net/cli/v1.0.0/SHA256SUMS
curl -fsSLO https://cloudj.net/cli/v1.0.0/SHA256SUMS.sig
curl -fsSLO https://cloudj.net/cli/cloudj-cli.pub
# 2. check the signature (namespace cloudj-cli)
echo "cloudj-cli namespaces=\"cloudj-cli\" $(cat cloudj-cli.pub)" > allowed_signers
ssh-keygen -Y verify -f allowed_signers -I cloudj-cli -n cloudj-cli -s SHA256SUMS.sig < SHA256SUMS
# 3. check your download against the signed list
sha256sum --check --ignore-missing SHA256SUMS # macOS: shasum -a 256 -c SHA256SUMSSign in
Run cloudj login. The CLI shows a one-time code and opens /link in your browser; sign in, check the client name, device and requested scopes, untick anything you do not need and approve. The CLI then receives its own API key, stored in a file only you can read. Use --scopes to ask for specific scopes, --no-browser on a server without a browser, or paste an existing key with --with-token (stdin) or --token. Keys created this way are listed under API keys › Connected apps & devices, where you can revoke them. cloudj whoami shows the profile, the API URL and the key's scopes.
The key is stored in ~/.config/cloudj/config.json (Windows: %APPDATA%\cloudj\config.json) with owner-only permissions, and is never printed in full. cloudj logout deletes the local copy; the key stays valid until you revoke it in the dashboard. A key only works on the site it was created on.
Using commands
- Path parameters are positional arguments in the order they appear in the URL:
cloudj vm firewall delete VM_ID RULE_ID. - Query parameters and body fields are flags named after the field with dashes:
per_pagebecomes--per-page 50. Integers and numbers are validated, booleans are bare flags, enums are checked, arrays are repeated or comma-separated, and objects take JSON. --datasends a whole JSON body from text,@file.jsonor-(stdin). Flags override fields of--data.--query key=valueadds any other query parameter.- Required flags are checked before anything is sent.
cloudj <command> --helplists everything a command accepts, including its scope. Every endpoint of this reference shows its command.
| Flag | Environment | Meaning |
|---|---|---|
-o, --output | CLOUDJ_OUTPUT | json, table or yaml. Table on a terminal, JSON when piped. |
--profile | CLOUDJ_PROFILE | Which stored key to use. |
--api-url | CLOUDJ_API_URL | API base URL (default https://cloudj.net). Reseller sites have their own URL and keys. |
-y, --yes | Skip the confirmation on destructive or paid commands. Use it in scripts. | |
--idempotency-key | Use your own Idempotency-Key. Paid commands generate one when you omit it. | |
--retry n | On 429, wait for Retry-After and retry up to n times. | |
--timeout s | Seconds to wait for response headers (default 60). | |
--debug | Print the HTTP exchange to stderr, with keys masked. | |
CLOUDJ_TOKEN | The API key itself, for CI and containers. Overrides the stored key; nothing is written. |
Paid and destructive commands
Commands that delete data or charge your wallet ask for confirmation ([y/N]) before anything is sent. Without a terminal they refuse and exit with code 6 unless you pass --yes. Paid commands send an Idempotency-Key: the CLI generates one and prints it to stderr. If the connection drops, run the same command again with that key to get the original result instead of paying twice.
cloudj vm create --data @vm.json # asks [y/N], sends an Idempotency-Key
cloudj vm create --yes --idempotency-key "$KEY" --data @vm.json # scripts: choose the key yourselfOutput and exit codes
-o json prints the server response unchanged, so it is safe for jq. Errors go to stderr and results to stdout. The exit code tells scripts what happened:
| Code | Meaning |
|---|---|
0 | Success. |
1 | Any other error: HTTP 4xx or 5xx not listed below, network failure. |
2 | Usage error: unknown command or flag, missing argument, invalid value. |
3 | Not authorized: HTTP 401 or 403 (bad key, missing scope, wrong site, IP not allowed). |
4 | Not found: HTTP 404, also for resources that belong to someone else. |
5 | Rate limited: HTTP 429. |
6 | Confirmation required or declined for a destructive or paid command. |
130 | Interrupted (Ctrl-C). |
Raw API calls
cloudj api calls any endpoint with your key, for operations the CLI does not know yet or for debugging. If the path matches an operation in this reference it behaves like the dedicated command: destructive operations still ask for confirmation and paid ones get an Idempotency-Key. Only paths on your configured API URL are accepted, so a key can never be sent to another host.
cloudj api GET /v1/vm --query page=2
cloudj api POST /v1/vm/VM_ID/start
cloudj api POST /v1/vm --data @vm.jsonProfiles and CI
Keep several keys as profiles. Precedence is flag, then environment variable, then config file.
cloudj login --profile staging --api-url https://staging.example.com
cloudj config use staging # make it the default
cloudj --profile prod vm list # one-off
cloudj config set output json # default output format- name: Install cloudj
run: |
curl -fsSL https://cloudj.net/cli/install.sh | CLOUDJ_INSTALL_DIR="$RUNNER_TEMP/bin" sh
echo "$RUNNER_TEMP/bin" >> "$GITHUB_PATH"
- name: List running VMs
env:
CLOUDJ_TOKEN: ${{ secrets.CLOUDJ_TOKEN }} # a read-only key
run: cloudj vm list -o json | jq -r '.items[].name'The binary is static, so any container image works. Use one key per pipeline with the minimum scopes, a short expiry and an IP allow-list.
Shell completion
Completion is dynamic: it completes command names, flags, enum values, output formats and your profile names from the installed binary, so it never goes stale.
cloudj completion bash > ~/.local/share/bash-completion/completions/cloudj
cloudj completion zsh > "${fpath[1]}/_cloudj"
cloudj completion fish > ~/.config/fish/completions/cloudj.fish
cloudj completion powershell | Out-String | Invoke-Expression # add to $PROFILEUpdate and uninstall
cloudj version prints the version. cloudj update --check tells you whether a newer release exists, and cloudj update downloads it, verifies the signature against the key built into the running binary and the package SHA-256, and only then replaces the executable. To uninstall, delete the cloudj binary and the config folder (cloudj config path shows it).
MCP server
Let an AI assistant manage your infrastructure through the Model Context Protocol. Each endpoint of this reference is a tool. Every tool call runs with the permissions of the API key you connect with and goes through exactly the same checks as a REST call: scopes, site, IP allow-list, rate limits and ownership. The assistant can never do more than the key allows.
| Server URL | https://cloudj.net/mcp |
|---|---|
| Transport | Streamable HTTP, JSON responses |
| Protocol versions | 2025-11-25, 2025-06-18, 2025-03-26 |
| Authentication | OAuth 2.1 sign-in (most clients do it for you), or Authorization: Bearer vk_... with an API key |
| Tool names | The CLI command with underscores: vm firewall add becomes vm_firewall_add. |
1. Sign in from the assistant
Add only the server URL. On first use the assistant opens the Connect page of this site in your browser. Sign in, check the app name and the permissions it asks for, untick anything it does not need, choose how long access lasts (7 to 365 days, 90 by default) and approve. The assistant receives its own API key with exactly the permissions you ticked.
- Safe defaults. Permissions that cost money, delete resources or reveal secrets are unticked unless you tick them. The assistant sees one tool per permitted endpoint: with
vm:readit listsvm_list,vm_getand so on, and nevervm_createorvm_delete. - Revoke at any time. Every approved assistant is listed under API keys, in Connected apps & devices, with its permissions, last use and expiry. Revoking cuts access at once; connecting the same app again replaces its previous key.
- No key, no access. Signing in never lets an assistant top up, withdraw, change your password or create other keys.
Only approve sign-ins you started. The Connect page shows the app name (as the app reports it, not verified), where access is sent and your IP. If you did not just add the server yourself, press Deny. Anything the assistant can read it can also send.
How the sign-in works (for client developers)
Standard MCP authorization: OAuth 2.1 with PKCE (S256 only) and dynamic client registration. Unauthenticated requests to https://cloudj.net/mcp return 401 with WWW-Authenticate: Bearer resource_metadata="/.well-known/oauth-protected-resource/mcp".
| Protected resource metadata | https://cloudj.net/.well-known/oauth-protected-resource/mcp |
|---|---|
| Authorization server metadata | https://cloudj.net/.well-known/oauth-authorization-server (issuer https://cloudj.net) |
| Registration | POST https://cloudj.net/oauth/register — public clients (token_endpoint_auth_method: none); redirect URIs must be http://127.0.0.1:<port>/…, http://localhost:<port>/… or https://… |
| Authorization | GET https://cloudj.net/oauth/authorize — response_type=code, code_challenge_method=S256, state, resource=https://cloudj.net/mcp, scope = space-separated API scopes |
| Token | POST https://cloudj.net/oauth/token — grant_type=authorization_code with code_verifier. The code is valid for 60 seconds and once. The access token is an API key (vk_...) carrying the approved scopes; there is no refresh token, run the sign-in again when it expires. |
2. Add the server to your client
Add the server, then run /mcp inside Claude Code and choose Authenticate. Your browser opens the Connect page of this site: sign in, untick anything the assistant does not need, choose how long access lasts and approve. Add --scope user to make it available in every project, or --scope project to write it to .mcp.json.
claude mcp add --transport http cloudj https://cloudj.net/mcpAny client that supports Streamable HTTP works: point it at https://cloudj.net/mcp and either let it sign in, or send Authorization: Bearer vk_... with an API key. Smoke test with curl and a key:
curl -s https://cloudj.net/mcp \
-H "Authorization: Bearer vk_YOUR_KEY" \
-H "Content-Type: application/json" \
-H "Accept: application/json, text/event-stream" \
-d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'3. How tools behave
- Read-only tools (
..._list,..._get) carryreadOnlyHintand are safe to call freely. List tools are paginated: passquery: {"page": 1, "per_page": 50}. Tools also carry destructive and idempotent hints, so clients can ask before they act. - Confirmation. Tools that spend money, delete a resource or return credentials (create or resize a server, change plan, delete, kubeconfig, console tickets, password reset) refuse to run unless the call includes
confirm: true. A well-behaved assistant asks you first. Nothing is executed whenconfirmis missing. - Retries are safe. Billable tools always send an
Idempotency-Key. If you do not supplyidempotency_key, one is derived from the tool name and arguments, so repeating an identical call returns the original result instead of charging twice. To deliberately repeat an identical action, pass a differentidempotency_key. - Limits. 60 tool calls per minute per key, on top of the normal per-key and per-account API limits. Request bodies are limited to 1 MB and long results are truncated at about 100 KB, so narrow the query.
- Audit. Every tool call is recorded in the key's activity log: tool name, HTTP result and duration.
Troubleshooting
| Symptom | Cause |
|---|---|
401 with WWW-Authenticate: Bearer | Not signed in yet (the client should start the sign-in by itself), or a wrong, revoked or expired key, a key used on another site, or a request IP outside the key's allow-list. Sign in again or check the key. |
| Sign-in page says the app is not registered | The client's registration expired or was made on another site. Remove the server from the client, add it again and sign in. |
| Sign-in page says "wrong browser" | Open the sign-in link in the browser the client opened, not in another browser or device. |
403 origin_not_allowed | The client sent a browser Origin header that is not this site. Use a desktop or CLI client, or a bridge such as mcp-remote. |
429 | Too many tool calls. Wait for Retry-After seconds. |
| A tool is missing | The key lacks the scope, or the service is not enabled on this site. |
Result has isError: true and starts with HTTP 404 | The resource does not exist or is not yours. |
Result starts with Refused: | The tool needs confirm: true. Ask the user, then repeat the call. |
Downloads
Use the machine-readable specification to generate clients, import the API into Postman or Insomnia, or feed it to your own tooling. Files always match what this page shows.
Client libraries
Single-file clients generated in your browser from the specification you are looking at. They have no dependencies, retry on 429, generate an Idempotency-Key where one is required, and raise a typed error with the status, code and request ID.
Prefer to generate your own SDK? Point any OpenAPI generator at https://cloudj.net/v1/public/openapi.json.
API Reference
Endpoints
393 endpoints in 26 groups. Each shows the scope it needs, its parameters and response, and code you can copy in curl, CLI, JavaScript, Python and Go.
API Reference
Reference
Catalog
Plans, regions, operating systems and prices you can order from. These calls are read-only and cost nothing. Prices are the retail prices of the site you call, in USD.
GET /v1/gpu/catalog — GPU catalog: configurations, templates and sale prices
Returns the live GPU catalog: the configurations that can be ordered with their prices and stock, the software templates, and which configurations each template can run on. The list follows the live market, so prices...
GET /v1/proxy6/catalog — Proxy IPv6 catalog: plans, cycles and zones
Returns the IPv6 proxy catalog for your site: the fixed plans with the price of each billing period, the bandwidth and device add-ons, the regions with their availability, and the connection details (gateway host...
POST /v1/proxy6/quote — Quote a Proxy IPv6 order at your site's price (nothing is purchased)
Prices an IPv6 proxy order at your site's price without creating anything and without charging. The response lists the price lines (plan and add-ons) in millionths of a US dollar and amountcents, the amount an order...
GET /v1/public/dedicated — Public Dedicated Server (Bare Metal) plans: specifications; prices only while on sale
Returns the public list of Dedicated Server (Bare Metal) plans: a physical Dell PowerEdge server for your exclusive use, with the hardware of each plan. Prices are in whole Vietnamese dong (VND) per month; fx gives the...
GET /v1/public/gpu — Public GPU price list
Returns the public price list of GPU servers: the available configurations with their hourly and monthly prices and current stock, and the software templates that can be started on them. Prices are the retail prices for...
GET /v1/public/k8s — Public Kubernetes price list
Returns the public price list of managed clusters: the worker plans with their hourly, monthly and per-cycle prices, the billing cycles, the versions on sale, the regions, the free control plane and the account limits....
GET /v1/public/plans — Public price list of the site
Returns the public price list of the site: fixed plans and the unit prices of custom configurations. It is the same information as the pricing page, with no account data, and is cached for up to a minute.
GET /v1/public/pricing — Consolidated site pricing (VMs, storage, enabled features)
Returns the complete retail price list of the site in one call: every fixed plan with the price of each billing cycle, the unit prices of custom configurations, the unit prices of the optional storage services, and the...
GET /v1/public/proxy6 — Public Proxy IPv6 price list
Returns the public price list of IPv6 proxies: the fixed plans with the price of each billing period, the bandwidth and device add-ons, and the regions with their availability. All prices are in millionths of a US...
GET /v1/public/s3 — Public S3 price list
Returns the public price list of pay-as-you-go object storage: the price per GB of storage and per GB downloaded, the free allowance, and the regions where it can be ordered. Uploads are free.
GET /v1/public/storage — Block Storage, Backup, Snapshot and Images pricing
Returns the retail prices and limits of the storage services: block storage volumes, backups, snapshots and uploaded images. Each service appears as an object with enabled; when a service is not on sale at your site...
GET /v1/public/vm-quote — Quote a custom size in a region (public)
Prices a custom size in a region without an account: the same answer as Quote a custom size in a region but for visitors. Only values listed in the region's custom block are accepted. Limited to 30 calls per minute per...
GET /v1/public/vm-regions — Regions open for sale and starting prices
Lists the regions where servers are on sale to everyone, with the monthly price of the cheapest fixed plan and the CPU types on offer. It needs no account, is the same for every visitor and is cached for up to five...
GET /v1/public/vm-regions/{slug} — One region in detail: CPU types, plans, custom sizes, traffic, cycles
Describes one region that is on sale to everyone: its CPU types (with a one-line description), every fixed plan with its hourly and monthly price, the custom sizes you can build (same custom block as the catalog), the...
GET /v1/public/vpc — Public Private Cloud price list
Returns the public price list of private cloud networks: the plans (dedicated unmetered bandwidth in Mbps) with their hourly, monthly and per-cycle prices, the billing cycles, the region, the account limits and the...
GET /v1/public/vpn — Public VPN IPv4 price list
Returns the public price list of VPN IPs: the price per IP at each order size, the bandwidth tiers, the add-ons, the billing cycles and the regions. Only the dedicated tier is on sale; shared and private stay in the...
POST /v1/public/vpn/quote — Quote a VPN IPv4 order (nothing is purchased)
Prices a VPN order without creating anything and without charging. The body describes the order (tier, number of IPs, bandwidth tier, billing cycle, add-ons) and the response is the price breakdown in millionths of a US...
GET /v1/s3/catalog — S3 catalog: price policy and zones
Returns the object storage catalog for your account: the price policy, the regions where an account can be created, whether your account currently qualifies for the free storage allowance, and the account limits. Create...
GET /v1/vm/catalog — Plans, regions and OS images
Returns everything needed to order a server: the plans on sale with their prices for each billing cycle, the operating system images, the regions, and the account-independent rules (minimum balance, snapshot limits)....
GET /v1/vm/custom-quote — Quote a custom configuration
Prices a custom configuration (any vCPU / RAM / disk combination within the site limits) without creating anything and without charging. The response includes the cost per billing cycle, the cost of the first charge, a...
GET /v1/vm/prices — Unit prices per component (vCPU, RAM, disk)
Returns the price of every plan on sale for each billing cycle, plus the unit prices used for custom configurations. A compact alternative to the catalog when you only need prices (for example to display a cost...
GET /v1/vm/px-quote — Quote a custom configuration in a region (CPU type, cores, RAM, disk)
Prices a custom size (CPU type, cores, memory, disk) in a region that offers several CPU types, without creating anything and without charging. Only values listed in that region's custom block of the catalog are...
GET /v1/vpn/catalog — VPN IPv4 catalog: plans, cycles, zones and free IPs
Returns the VPN price book for your site: the price per IP at each order size, the bandwidth tiers, the add-ons and billing cycles, plus the regions with the number of free IPs. Only the dedicated tier can be ordered...
POST /v1/vpn/quote — Quote a VPN IPv4 order at your site's price (nothing is purchased)
Prices a VPN order at your site's price without creating anything and without charging. The response is the price breakdown in millionths of a US dollar plus amountcents, the amount an order would take from your wallet....
GET /v1/zones — Sale zones and per-service availability
Lists the regions your site sells from, with the availability of each service in each region: virtual machines (vm), VPN IPs (vpn, with the number of free IPs) and object storage (s3). Use a region id as zoneid when...
API Reference
Compute
Virtual Machines
Create, inspect and operate virtual servers: power actions, plan changes, metrics, billing of a single server, and deletion. Creating a server, changing its plan and deleting it are destructive or charge the wallet and require an Idempotency-Key.
Lifecycle. A new server starts in provisioning, becomes active when it is ready, and moves to deleting and deleted when you delete it. A server that cannot be paid for (or that an administrator suspended) becomes locked: it keeps its data for a grace period (destroy_after) but refuses every action except top-ups and deletion-related reads. If deployment fails the server becomes failed and the order is refunded. Power state (Running, Stopped...) is reported separately in cs_state and is only meaningful while the server is active.
Asynchronous actions. Start, stop, reboot, password reset, SSH-key change, plan change and deletion return a job_id immediately. Follow it with List a VM's jobs, or poll Get a VM until job_running is false. Only one job can run on a server at a time; a second action meanwhile fails with 409 job_running.
GET /v1/vm — List VMs
Returns the servers of your account, newest first by default, 25 per page (maximum 100). Servers in the deleted state are hidden unless you ask for them with state=deleted.
POST /v1/vm — Create a VM (charges the wallet)
Orders a new server and returns it at once in the provisioning state; it becomes active (usually within a couple of minutes) when the operating system is installed. The first charge is taken from your wallet in the same...
GET /v1/vm/ops-key — The pre-attached ops SSH key (name + fingerprint, not a secret)
Returns the name and fingerprint of the platform's maintenance SSH key. When attach is true, this key is installed on new servers next to your own key so that support can help you; use the fingerprint to recognise it in...
GET /v1/vm/{id} — Get one VM
Returns one server with its plan, image, network placement, billing cycle and lock details.
PATCH /v1/vm/{id} — Rename / notes
Changes the display name of the server. The host name cannot be changed. Works in any state except locked; it does not need the server to be idle. The updated server is returned (without the network and lock details...
DELETE /v1/vm/{id} — Delete the VM (data is lost)
Permanently deletes the server. This cannot be undone: the system disk, data disks, backups and VM snapshots of the server are destroyed and its public addresses are released. Call Get delete preview first and show the...
GET /v1/vm/{id}/bandwidth — Bandwidth usage
Returns the traffic of the server as a time series (bytes) together with the monthly bandwidth quota. in is traffic into the server, out is traffic leaving it.
GET /v1/vm/{id}/billing — Billing of this VM
Returns the billing state of one server: price, billing cycle, how far it is paid, your wallet balance, and the wallet charges and invoices that belong to this server. charges holds up to the 200 latest wallet entries...
POST /v1/vm/{id}/change-custom — Custom resize
Resizes a server that runs a custom configuration: change its vCPU count, memory and disk. CPU and memory can go up or down; the disk can only grow, in steps of the site's disk step. Only the values you change are...
POST /v1/vm/{id}/change-cycle — Change the billing cycle (prorated)
Moves the server to another billing cycle, for example from hourly to monthly or from monthly to yearly. The unused part of a current prepaid period is refunded to the wallet and the first period of the new cycle is...
POST /v1/vm/{id}/change-ip — Change the public IP (cooldown between changes)
Gives the server a new public IPv4 address and releases the old one. Firewall rules of the old address are copied to the new one. The old address is not reused for a few days, so you cannot cycle through addresses....
POST /v1/vm/{id}/change-plan — Change plan (prorated)
Moves the server to another fixed plan of the same region. The server is stopped, resized and started again, so expect a short downtime (requiresstop in Get plan options says whether the change needs it). The disk can...
GET /v1/vm/{id}/change-quote — Quote a plan change or custom resize
Previews what changing the server's plan or custom size would cost, without changing anything. Pass either planid (a fixed plan from the catalog) or all three of cpu, rammb and diskgb (a custom size). The arithmetic is...
GET /v1/vm/{id}/cycle-quote — Quote a billing-cycle change
Previews switching the server to another billing cycle, without changing anything. The unused part of the current prepaid period is refunded and the first period of the new cycle is charged, so the result is either...
GET /v1/vm/{id}/delete-preview — Preview before delete
Shows what deleting the server would do, without deleting anything: the estimated refund, how the refund is computed, and the resources that will be destroyed with it (data disks, backups, IP addresses, VM snapshots)....
GET /v1/vm/{id}/events — VM event log
Returns the activity log of the server, newest first: power actions, plan changes, renewals, locks, failures. msg is display text in English (older entries can be in Vietnamese); to show the message in your own language...
POST /v1/vm/{id}/force-stop — Force stop the VM
Powers the server off immediately, like pulling the power cable. Unsaved data in memory is lost and file systems may need a repair on the next boot, so use Stop first and keep this for servers that do not respond. The...
GET /v1/vm/{id}/fsinfo — Disk used/total measured inside the VM
Returns how full the server's main disk is, measured from inside the server (root filesystem, or the C: drive on Windows). The three disk values are null when the server is not running, is locked, has no guest agent...
GET /v1/vm/{id}/jobs — Running jobs of the VM
Returns the 50 most recent background jobs of the server, newest first: creation, power actions, plan changes, SSH-key changes and deletion. Every action endpoint returns a jobid; poll this list until that job's state...
GET /v1/vm/{id}/metrics — CPU/RAM/disk/network over time
Returns CPU, memory, disk and network time series for the last 30 minutes up to 12 hours, one sample per minute, plus the current reading in now. Rates are in KB/s; CPU and memory are percentages. Results are cached for...
GET /v1/vm/{id}/nics — Network interfaces and IPs
Lists the network interfaces of the server with their IPv4 and IPv6 addressing. publicip is the address the server is reached on from the internet; it is mapped 1:1 to the private address of the default interface....
GET /v1/vm/{id}/plan-options — Plans this VM can switch to (same zone)
Lists the fixed plans this server can switch to: plans in the same region that are on sale to you, have a disk at least as large as the current one and differ from the current plan, cheapest first. Each option carries a...
GET /v1/vm/{id}/plan-quote — Quote before changing plan
Dry run of Change plan: tells you what moving the server to another fixed plan would cost or refund, without changing or charging anything. For prepaid servers the amount is the prorated price difference for the time...
GET /v1/vm/{id}/price — Current price of the VM (hourly, cycle, renewal)
Returns the price this server is billed at right now and the price its next renewal will cost. Prices are exact integers: hourlyuusd is in millionths of a US dollar and the cents fields are in US cents. A prepaid server...
POST /v1/vm/{id}/reboot — Reboot the VM
Restarts the server (a soft reboot signalled to the operating system). A stopped server is started instead. The call returns immediately with a jobid.
POST /v1/vm/{id}/reinstall — Reinstall the OS (WIPES the disk)
Erases the server's system disk and installs the operating system again, either the one it already runs or, when templateid is given, a different image from the catalog. Everything on the system disk is lost and cannot...
POST /v1/vm/{id}/renew — Renew a prepaid VM (charges the wallet)
Renews a prepaid server for one or more periods of its billing cycle. The price of all periods (the price of one period, times periods; a site price cut since the last renewal is applied) is taken from the wallet...
POST /v1/vm/{id}/reset-password — Reset the admin password
Generates a new administrator password for the server. A running server is stopped, the password is reset, and the server is started again, so expect a short downtime. The new password is never returned by the API: it...
GET /v1/vm/{id}/screenshot — Screenshot of the running VM
Takes a picture of the server's screen (what its console shows) as a PNG data URL. It always answers 200: when no picture can be taken the body is {available: false, reason} instead of an error, so you can poll it...
POST /v1/vm/{id}/ssh-key — Attach an SSH key to the VM
Replaces the SSH key installed on the server with one of your saved keys (see List SSH keys). A running server is stopped, the key is installed, and the server is started again, so expect a short downtime; the previous...
POST /v1/vm/{id}/start — Start the VM
Powers the server on. The call returns immediately with a jobid; the server is running once the job is done and csstate is Running. Starting a server that is already running succeeds without effect. Powering on is...
POST /v1/vm/{id}/stop — Stop the VM (graceful)
Shuts the server down gracefully (an ACPI power-button signal, so the operating system can close files and services). If the guest does not shut down in time, it is powered off forcibly. The call returns immediately...
POST /v1/vm/{id}/toggle-ipv6 — Enable/disable IPv6 (dual-stack or IPv4 only)
Switches the server between dual-stack (IPv4 and IPv6) and IPv4 only. The server is moved to the other network, which interrupts its public connectivity for a few minutes; it may be restarted at the end, and its public...
GET /v1/vm/{id}/volumes — Volumes of the VM
Lists the disks attached to the server: the system disk and any data disks, with size and state. Results are cached for 20 seconds. Fails with 409 vmnotready while the server has not been created on the infrastructure...
Snapshots
Point-in-time snapshots of a whole virtual server. Each server can hold a limited number of snapshots (meta.limit, 3 by default). Taking or deleting a snapshot runs in the background: the write operations answer immediately with a job_id, which you follow with List VM jobs. While a server has snapshots, changing its plan, reinstalling it or resizing its disk is refused with 409 has_snapshots, so delete them first. Snapshots can be switched off for a site; every operation then answers 501 feature_disabled.
GET /v1/snapshot-policies — Automatic snapshot schedules of all VMs (paged)
Lists the automatic snapshot schedules of all your servers in one paged list. To see the schedules of one server, or to add or remove one, use the per-server operations.
GET /v1/snapshots — Snapshots of all VMs in the account (paged, sortable)
Lists the snapshots of all your servers in one paged list, newest first by default. Snapshots of deleted servers are not shown. To list or manage the snapshots of one server use the per-server operations. The list is...
GET /v1/vm/{id}/snapshot-policies — Automatic snapshot schedules of one VM
Lists the automatic snapshot schedules of one server, oldest first, with the limits that apply. At each due time the server takes a snapshot; before that the oldest automatic snapshots beyond keep are deleted. A run is...
POST /v1/vm/{id}/snapshot-policies — Add an automatic snapshot schedule (daily/weekly)
Adds an automatic snapshot schedule to a server and answers 201 with the new schedule. Describe the time either with kind, hour, minute (and dow for weekly), or with a single cron string such as daily 03:00 or weekly 1...
DELETE /v1/vm/{id}/snapshot-policies/{pid} — Delete an automatic snapshot schedule
Deletes an automatic snapshot schedule. Snapshots it already took are kept; delete them separately if you no longer need them. A schedule that does not exist, or belongs to another server or account, answers 404.
GET /v1/vm/{id}/snapshots — List snapshots
Lists the snapshots of the server, with how many more you may take. meta.cancreate is true only when the limit is not reached, no snapshot job is queued or running, and the server is active and not locked. The result is...
POST /v1/vm/{id}/snapshots — Create a snapshot
Takes a snapshot of the whole server. The call returns as soon as the job is queued (jobid); the snapshot shows up in List snapshots with state Creating and becomes Ready when the job is done. Taking a snapshot can take...
DELETE /v1/vm/{id}/snapshots/{sid} — Delete a snapshot
Deletes one snapshot of the server. The call returns as soon as the deletion is queued (jobid). A snapshot that does not belong to this server answers 404.
POST /v1/vm/{id}/snapshots/{sid}/restore — Restore the VM to a snapshot (stops, overwrites the disk, restarts)
Overwrites the server's disk with a snapshot. The server is stopped, its disk goes back to the state it had when the snapshot was taken, and the server is started again. Everything written since the snapshot was taken...
Console and AI Agent
One-time tickets for the graphical (VNC) console and the SSH web terminal, shareable terminal links, and the AI SSH agent that runs commands on a server for you. Tickets and share tokens are secrets: anyone who holds one can open the console until it expires, so never log them or put them in a URL you share publicly.
GET /v1/chat/agent/sessions — List AI SSH Agent conversations
Lists your AI agent conversations that have at least one message, most recently active first. Filter by server with vmid, and search titles and server names with q.
POST /v1/chat/agent/sessions — Start an AI SSH Agent conversation for a VM
Starts a new, empty conversation with the AI agent about one of your servers. The conversation stays bound to that server. It is listed once it has a message; send one with Send to the AI agent. Limited to 30 per minute...
GET /v1/chat/agent/sessions/{sid} — Get an AI SSH Agent conversation with messages
Returns one conversation with its latest 100 messages, oldest first. Command output is stored cut to 16000 characters (stderr 8000). Limited to 120 requests per minute per account. Each answer lists the commands the...
PATCH /v1/chat/agent/sessions/{sid} — Rename an AI SSH Agent conversation
Renames a conversation. Control characters are removed and the title is cut to 80 characters; an empty title fails with 422 invalidargument.
DELETE /v1/chat/agent/sessions/{sid} — Delete an AI SSH Agent conversation (with its command history)
Deletes a conversation and all its messages, including the record of the commands it ran — so it needs the same vm:console scope that runs commands. This cannot be undone. A conversation that is answering right now...
POST /v1/chat/agent/sessions/{sid}/messages — Send to the AI SSH Agent / confirm a command (SSE stream)
Sends a request to the AI agent in a conversation, or answers a command that waits for your confirmation. The agent works on the conversation's server over SSH and the conversation history is taken from the server side...
GET /v1/chat/agent/vms — VMs usable by the AI SSH Agent + daily quota
Lists your servers (at most 500, by name) with whether the AI SSH agent can work on each one right now. A server is ready when it is active, running, not locked, runs Linux and has an address. Otherwise reason says why...
POST /v1/chat/agent/vms/{id}/connect — Check the agent SSH login (fixed command)
Checks that the agent can log in to the server over SSH, using the saved credentials or the platform's operations key — you never send or receive a password. The platform runs a fixed, read-only command (login name...
POST /v1/vm/{id}/ai-agent — Run AI SSH Agent (SSE stream)
Sends a message to the AI agent, which can run shell commands on the server over SSH to answer. The response is a stream of server-sent events (text/event-stream): each data: line is one JSON object (see the schema)...
POST /v1/vm/{id}/ai-agent/clear — Start a new AI SSH Agent session
Starts a new, empty AI agent conversation for this server. The earlier conversation is kept but is no longer the one Get AI agent status returns, so the agent forgets the previous context. Pass the returned sessionid to...
GET /v1/vm/{id}/ai-agent/status — AI SSH Agent status and history
Returns whether the AI agent is enabled, the model it uses, and the most recent conversation you had with it about this server (up to the last 40 messages, oldest first). sessionid is null and messages is empty when...
GET /v1/vm/{id}/console — Get a one-time VNC console ticket
Issues a one-time link to the graphical (VNC) console of a running server. Open url in a browser, or embed it in a page, within expiresin seconds (60). The link works for one console session; asking again issues a new...
GET /v1/vm/{id}/console-shares — List active SSH session share links
Lists the share links of the server that are still active (not revoked and not expired), newest first, at most 20. A share link lets someone else open the server's SSH terminal without an account. Each link carries its...
POST /v1/vm/{id}/console-shares — Create an SSH session share link
Creates a share link for the server's SSH terminal. The viewer connects to the returned websocketurl with ?mode=share&token=<token> appended, with no account or password. Anyone holding the token can use the link until...
DELETE /v1/vm/{id}/console-shares/{sid} — Revoke an SSH session share link
Revokes a share link immediately: its token stops working for new connections. A link that is unknown, already revoked or belongs to another server answers 404. Links also stop working on their own when they expire.
POST /v1/vm/{id}/ssh-token — Get a one-time SSH WebSocket token
Issues a one-time ticket for the SSH web terminal of a running Linux server. Open a WebSocket to websocketurl with the ticket as the token query parameter (<websocketurl>?token=<token>) within expiresin seconds (300)....
SSH Keys
SSH public keys stored in your account. Only the public half is stored here, so nothing secret is ever returned. Attach a stored key to a server with Attach an SSH key to the VM, or choose one when you create a server. An account can store at most 20 keys.
GET /v1/vm/sshkeys — List SSH keys
Lists the SSH public keys stored in your account, oldest first. The list is not paginated because an account holds at most 20 keys.
POST /v1/vm/sshkeys — Add an SSH key
Stores an SSH public key in your account so you can attach it to servers. Paste the contents of the .pub file as publickey. Only ssh-ed25519 and ssh-rsa keys are accepted; other types (for example ecdsa-sha2-nistp256)...
DELETE /v1/vm/sshkeys/{id} — Delete an SSH key
Deletes a stored SSH key. Servers that already use the key keep working and keep the key installed; only the stored copy is removed, so you can no longer attach it to other servers. Deleting a key that does not exist...
Images
Operating system images and ISO images of your account. Import an image from a URL, create one from a stopped server, rename it, delete it, or attach and detach an ISO. A template image that is Ready can be used as the operating system when you create a server. Stored images are billed per GB-hour from the moment they are ready. Image management can be switched off on a site; every call in this section then fails with 501 feature_disabled.
GET /v1/images — List your images and ISOs (paged, sortable)
Lists the OS images and ISO images stored in your account, newest first by default. A new image moves from Queued through Downloading (or Creating when made from a server) to Ready; Error means it failed and errorcode...
POST /v1/images — Import an image/ISO from URL (storage billed hourly)
Imports an operating system image (a QCOW2 disk) or an ISO from a public URL into your account. The call returns 202 at once with the image in state Queued and a jobid; the file is then downloaded and checked in the...
POST /v1/images/from-vm — Create an image from a stopped instance
Creates a template image from the system disk of one of your servers. The server must be stopped (power state Stopped) and not locked or busy with another operation; it is not modified. The call returns 202 with the new...
GET /v1/images/os-types — OS types
Lists the operating system types you can choose when importing an image. Pass the id of one entry as ostypeid to Import an image; it selects the virtual hardware profile used for the image, so pick the closest match to...
GET /v1/images/public — Public OS images on sale
Lists the operating system images that the site provides to everybody, with the regions where each one is available. They are the same images as templates in the VM catalog, in a lighter form meant for pickers shown...
GET /v1/images/quote — Image storage price per GB
Prices the storage of an image of a given size without creating anything. Images are billed hourly from the moment they are Ready: the size is rounded up to whole GB (1 GB = 2^30 bytes) and multiplied by the hourly...
GET /v1/images/{iid} — Get one image
Returns one image with its state, progress, size, cost, region, the number of servers using it and, for images made from a server, the name of the source server. Use it to follow an image after Import an image or Create...
PATCH /v1/images/{iid} — Rename / describe an image
Renames an image and/or changes its description. Only these display fields change; the image itself, its billing and the servers using it are not affected, and the call works in any state. Omit a field to keep it; send...
DELETE /v1/images/{iid} — Delete an image (not in use)
Deletes an image. The request is accepted with 202 and the image moves to Deleting; it disappears from List images when the removal finishes, and billing stops. An image cannot be deleted while it is being processed...
POST /v1/images/{iid}/attach — Attach an ISO to an instance
Attaches one of your ISO images to a server so that it can boot from it. The server can be running or stopped; reboot it to boot from the ISO. The ISO must be Ready, not locked, and in the same region as the server, and...
POST /v1/images/{iid}/detach — Detach an ISO from an instance
Detaches the ISO that is currently attached to a server. iid must be one of your ISO images, but it is not compared with the ISO that is actually attached: whatever ISO is attached is removed, and the call succeeds...
GET /v1/vm/{id}/iso — ISO attached to the VM + attachable ISOs
Shows which ISO is attached to a server and which of your ISO images can be attached to it. attached is the ISO currently inserted, or null when there is none; its imageid is null when that ISO is not one of yours (for...
Scaling
Change the size of a server (vCPU, RAM, disk) now or on a schedule, and let Auto Scaling grow it when the load is high. Resizing is charged or refunded for the price difference, and every operation that costs money requires an Idempotency-Key. Available only on sites that sell resizing; when it is switched off the write operations fail with 403 feature_disabled.
GET /v1/autoscale — Auto Scaling of all VMs in the account (paged)
Lists the Auto Scaling configuration of all servers of your account in one call. A server is listed when its rule is enabled, when a target size was saved for it, or when it currently is not in the base state. Deleted...
GET /v1/vm/scale-events — Scaling history of the account (paged, filterable)
Lists the size changes of the servers of your account, newest first: resizes you requested, scheduled ones, automatic growth by Auto Scaling, returns to base size, and automatic growth that was held back (kind: blocked...
GET /v1/vm/{id}/autoscale — Auto Scaling rule and state of the VM
Returns the Auto Scaling rule of one server and its live state. Auto Scaling watches the CPU and RAM load of an hourly-billed server: when the load stays above rule.uppct for rule.upsecs seconds, the server grows to the...
PUT /v1/vm/{id}/autoscale — Enable/disable and set the Auto Scaling rule (grows the VM with load)
Switches Auto Scaling on or off for a server and saves its rule. The call replaces the whole rule: tuning fields you leave out go back to their defaults (not to the previous values), and an omitted enabled means false....
GET /v1/vm/{id}/scale — Scaling status: limits, capabilities, blockers
Returns everything needed to build a resize form for one server in a single call: its current size and price, the limits and unit prices of your site, what it can do without a restart, the reasons a resize is not...
POST /v1/vm/{id}/scale — Resize CPU/RAM/disk now or scheduled (charges or refunds)
Resizes a server to the vCPU, RAM and disk you give, now or at a scheduled time. This operation costs money. The price of the new size is always computed by the server. For a server billed by the hour, one hour at the...
POST /v1/vm/{id}/scale/reboot — Reboot (now or scheduled) to unlock CPU/RAM hot-plug
Restarts the server immediately, or at a time you choose. A server that was last started before live resizing became available needs one restart before CPU and RAM can be changed without interrupting it, and a restart...
POST /v1/vm/{id}/scale/revert — Return the VM to its base size after Auto Scaling (reboots)
Returns a server that Auto Scaling has grown to its base size. The server is stopped, resized back to the base configuration and started again automatically in the background, which is a short interruption; the price...
GPU Cloud
Rent NVIDIA GPU servers by the hour or for a fixed billing cycle, and manage them afterwards. The section is available on sites that sell GPUs; elsewhere ordering fails with sales_disabled.
How an order works. Choose a GPU model, a template (the operating system image) and a disk size from the GPU catalog. Quote the rental to fix the price for 180 seconds without paying anything, then create the instance with the quote_id: the first period is charged to your wallet and the instance starts in state queued. Poll Get a GPU instance until state is active, then connect over SSH to public_ip on the host port listed under ports["22/tcp"], or open the web terminal with Get an SSH ticket.
Billing. An hourly instance is paid one hour ahead, every hour, from the wallet. While it is stopped only the disk is billed (storage_hourly_uusd). The other cycles (monthly, quarterly, semiannual, yearly) are paid up front with a discount and renew automatically until you delete the instance, running or not. When the wallet cannot pay, a running instance is stopped and becomes locked; a locked instance is deleted after 7 days unless you add funds and start it.
Commands are asynchronous. Start, stop, reboot, recycle and delete answer at once with {"ok": true, "pending": true}. The work continues in the background: follow state and intent on the instance. While a command is running, other commands answer 409 invalid_state.
GET /v1/gpu — List GPU instances
Lists the GPU instances of your account, newest first. Deleted instances are not listed; an instance whose order failed stays in the list with state failed and an errormsg. The list is not paginated.
POST /v1/gpu — Rent a GPU instance from a quote (charges the wallet)
Rents the machine from a quote. The first period is charged to your wallet immediately (one hour of compute for hourly, the whole cycle price for the other cycles) and the instance is created in state queued. The...
POST /v1/gpu/quote — Quote a GPU rental (no charge; use the quote_id to rent)
Finds the cheapest available machine that matches a GPU model, GPU count, template and disk size, and prices it. Nothing is charged and nothing is reserved on the machine: the returned quoteid only fixes the price for...
GET /v1/gpu/{id} — Get one GPU instance
Returns one GPU instance. This is the call to poll after Create and after every command: state is the lifecycle state, intent names the command still being carried out (null when the instance is idle), and publicip with...
DELETE /v1/gpu/{id} — Delete the GPU instance (data is lost)
Deletes the instance for good: the machine is released and everything on its disk is lost. The call answers at once and the deletion continues in the background; state becomes destroying and then the instance disappears...
GET /v1/gpu/{id}/diagnostics — Metrics and events of the GPU instance
Returns the latest usage readings reported by the machine and the recent activity of the instance. metrics only contains the readings the machine reported, so it can be empty or partial for a while after a start...
GET /v1/gpu/{id}/logs — Read the requested startup log
Reads the start-up log you asked for with Request GPU instance logs. Nothing is fetched until you ask: without a request in the last 5 minutes the answer is requested: false with empty logs. While the machine is still...
POST /v1/gpu/{id}/logs — Request a fresh startup log
Asks the machine to publish the last 500 lines of its start-up log. The answer has the same shape as Read GPU instance logs and is usually pending: true at first; poll that call every few seconds until pending is false....
POST /v1/gpu/{id}/reboot — Reboot the GPU instance
Restarts an active instance without losing its disk. The call answers at once; state is rebooting until the instance is back, which normally takes a minute or two. There is no extra charge. Repeating reboot while a...
POST /v1/gpu/{id}/recycle — Recycle the GPU instance from its template (data is lost)
Rebuilds an active instance from its template in place: the container or virtual machine is recreated from the original image on the same host and everything on the disk is erased, including every file you added. The...
POST /v1/gpu/{id}/ssh-token — Get a one-time SSH WebSocket ticket for the GPU instance
Issues a one-time ticket for the web SSH terminal of a running instance. Open a WebSocket to websocketurl with the ticket as the token query parameter (<websocketurl>?token=<token>) within expiresin seconds. The ticket...
POST /v1/gpu/{id}/start — Start the GPU instance (can charge a new billing period)
Powers a stopped or locked instance back on. The call answers at once; follow state (starting, then active).
POST /v1/gpu/{id}/stop — Stop the GPU instance
Powers an active instance off and keeps its disk. The call answers at once; state becomes stopping and then stopped. GPU charges stop. An hourly instance keeps paying the disk rate (storagehourlyuusd) every hour, and a...
Dedicated Servers
Dedicated Servers are physical machines assigned to your account. You can read their hardware, network settings, health, sensors, hardware log and bandwidth, rename them, change their power state and open a remote console. You never see the management controller of a machine, only the machine.
The list calls only return servers assigned to you; any other identifier answers 404 not_found. Changing power state and opening a console are asynchronous and protected by two switches: a system-wide switch (dedicated_ops_disabled while it is off) and a lock on each server (dedicated_server_locked). The actions object of Get a Dedicated Server tells you which buttons are available and why not. Power commands answer 202 with an op; poll Get an operation. Only one operation runs at a time on a server (409 dedicated_busy). A suspended subscription is read-only (423 dedicated_suspended).
Timestamps are Unix seconds. Byte counters are bytes. Hardware log times are corrected for the controller's clock (clock_adjusted). Hidden on sites that do not sell Dedicated Servers.
GET /v1/dedicated — List my Dedicated Servers
Lists the Dedicated Servers assigned to your account. enabled tells whether Dedicated Servers are shown to you at all. Each item carries the last known power state and health; stale is true when that status may be...
GET /v1/dedicated/catalog — Dedicated Server order catalog: locations, plans, cycles with VND prices, stock and auto-install operating systems
Returns everything needed to order a Dedicated Server: locations, plans with their billing cycles (prices in VND, already discounted and rounded down to 1,000), how many servers are left per location, the operating...
POST /v1/dedicated/order — Order a Dedicated Server: charges the wallet, assigns a machine and IP, installs the chosen operating system (automatic refund if the install fails)
Orders a Dedicated Server and pays it from the wallet in one step: a server is taken from stock, an IPv4 address is assigned if the server has none, the first cycle plus the setup fee is charged, a paid invoice is...
GET /v1/dedicated/orders — List my Dedicated Server orders
Lists your Dedicated Server orders, newest first by default.
GET /v1/dedicated/orders/{oid} — Get one Dedicated Server order
Returns one of your orders. Poll it while status is installing; the installation progress itself is the operation in opid.
POST /v1/dedicated/orders/{oid}/cancel — Cancel your own Dedicated Server order while it waits for a server (full refund to the wallet)
Cancels your order while it is awaitingstock (no server assigned yet) and refunds the full amount to your wallet, once. Orders that already have a server cannot be cancelled here.
GET /v1/dedicated/os-templates — List the operating systems that can be installed on a Dedicated Server (enabled templates)
Lists the operating systems that can be installed on a Dedicated Server: only templates that are switched on and whose installation image is available. The list is the same for every server. It is empty for accounts...
POST /v1/dedicated/quote — Quote a Dedicated Server order (server-side price, wallet check, stock)
Prices an order without placing it. The price is always computed by the server from the plan and cycle: the total in VND, the US cents that would be charged at today's exchange rate, whether your wallet is enough...
GET /v1/dedicated/{id} — Get one Dedicated Server: hardware, network, status and which actions are available
Returns one Dedicated Server with its hardware, network settings, subscription and which actions you can start now. The actions object is the only thing a client needs to decide whether a button is enabled: reason says...
PATCH /v1/dedicated/{id} — Rename a Dedicated Server
Renames a Dedicated Server. Only the name changes; nothing is sent to the machine. A suspended subscription cannot rename.
GET /v1/dedicated/{id}/activity — Activity log of a Dedicated Server
Lists what happened on the server since it was assigned to you: power commands, console requests, renames and status changes, newest first by default.
PATCH /v1/dedicated/{id}/auto-renew — Turn auto-renew of a Dedicated Server subscription on or off
Turns automatic renewal of the subscription on or off. With auto-renew on, the wallet is charged the locked price of one cycle when the renewal date arrives and the balance is enough; otherwise an invoice is issued and...
GET /v1/dedicated/{id}/bandwidth — Inbound/outbound bandwidth of a Dedicated Server (series + monthly total)
Returns the traffic of the server's public IP address: a chart for range and the total of a month. inbytes is traffic received by your server, outbytes traffic it sent. stale is true when the counters have not been...
POST /v1/dedicated/{id}/console — Open a console session (a one-time URL is returned when ready)
Opens a remote console session for the machine. When the session is ready the answer carries a one-time url; open it in a browser within 60 seconds. If it is still preparing (202), poll Get a console session. Calling...
GET /v1/dedicated/{id}/console/{sid} — Console session status; when ready, issues a fresh URL (valid 60 seconds)
Returns a console session. While it is ready or active every call issues a fresh one-time url (valid 60 seconds, replacing the previous one), which is also how you reopen the console after closing the browser tab. At...
DELETE /v1/dedicated/{id}/console/{sid} — Close a console session
Closes a console session. The one-time address stops working and an open console connection is cut shortly after.
GET /v1/dedicated/{id}/events — Hardware log (SEL) of a Dedicated Server
Returns the hardware log of the machine (the most recent 50 entries) from the moment it was assigned to you. Times are corrected for the clock of the machine's controller; atraw keeps the original text.
GET /v1/dedicated/{id}/iso — The server's custom ISO: state, progress, expiry and which actions are available
Returns your custom ISO for this server (null when there is none), the limits and which actions are available now. Poll this call while state is queued, downloading, verifying, attaching or detaching. The internal...
POST /v1/dedicated/{id}/iso — Download an ISO from an http(s) URL into the server's temporary storage (asynchronous)
Downloads an ISO from a public http or https address into temporary storage for this server. The call answers 202 and the download runs in the background: poll Get the ISO. Only ports 80, 443, 8080 and 8443 are...
DELETE /v1/dedicated/{id}/iso — Delete the ISO early (detached first when attached)
Deletes the ISO and frees its storage. An ISO that is still attached is detached first: the call then answers 202 with state detaching and the file is removed when the detach finishes; otherwise it answers 200 with...
POST /v1/dedicated/{id}/iso/attach — Attach the ISO to the server as virtual media and set a one-time CD boot (asynchronous, returns an op)
Attaches the ready ISO to the server as virtual media and sets the server to boot once from it. The call answers 202 with an op; poll Get an operation or Get the ISO until state is attached. The server is not restarted...
POST /v1/dedicated/{id}/iso/detach — Detach the ISO from the server (asynchronous, returns an op)
Detaches the ISO from the server and clears the one-time CD boot. The ISO stays available (ready) until it expires, so it can be attached again. The call answers 202 with an op.
GET /v1/dedicated/{id}/ops — Operation history of a Dedicated Server
Lists the operations (power commands and console requests) on a server since it was assigned to you, newest first by default.
GET /v1/dedicated/{id}/ops/{op} — Get one operation (poll its progress)
Returns one operation of the server. Poll it after a power command until state is done, failed or cancelled.
POST /v1/dedicated/{id}/power — Power on/off/reboot a Dedicated Server (asynchronous, returns an op)
Changes the power state of the machine: on, off (immediate power cut), shutdown (ask the operating system to shut down), reboot (ask the operating system to restart) or reset (immediate hard restart). The call answers...
POST /v1/dedicated/{id}/reinstall — Reinstall the OS of a Dedicated Server (erases the disks, asynchronous, returns an op)
Reinstalls the operating system from an automatic template (List OS templates). Every disk partition is erased. The call answers 202 with an op (Linux 15–25 minutes, Windows about 60 minutes); poll Get an operation. Set...
POST /v1/dedicated/{id}/renew — Pay the open renewal invoice or renew one cycle early (charged from the wallet at the subscription's locked price)
Pays the renewal of the subscription from your wallet. If an invoice is open it is paid; otherwise one cycle is renewed early, which is allowed in the last 14 days before renewat. The price is always the locked price of...
GET /v1/dedicated/{id}/sensors — Power, temperatures, fans, PSUs (+ 24h/7d series)
Returns the last sensor reading: power draw, temperatures, fan speeds and power supplies. With range it also returns a time series (24h every 2 minutes, 7d every 30 minutes). stale is true when the reading may be...
API Reference
Networking
VM Networking
Firewall rules and port forwarding rules of a virtual server. Changes are applied in the background: the write operations answer immediately with a job_id, which you follow with List VM jobs. Rules are read live from the network and cached for about 20 seconds, so a list can lag slightly behind a change you have just made.
GET /v1/vm/{id}/firewall — Firewall rules
Lists the inbound firewall rules of the server: IPv4 rules on its public address and, when IPv6 is enabled for the server, its IPv6 rules. Each rule lets one protocol and port range in from one source range. The result...
POST /v1/vm/{id}/firewall — Add a firewall rule
Adds an inbound rule that lets one protocol and port range reach the server from one source range. The call returns as soon as the change is queued (jobid); the rule appears in List firewall rules with state Active once...
DELETE /v1/vm/{id}/firewall/{rule_id} — Delete a firewall rule
Removes one firewall rule of the server, IPv4 or IPv6. The call returns as soon as the removal is queued (jobid). Only rules that belong to this server can be removed; any other ruleid answers 404.
GET /v1/vm/{id}/port-forwarding — Port forwarding rules
Lists the port forwarding rules of the server's public address. Servers normally use a dedicated public address that is mapped 1:1 to the server (static NAT): every port already reaches the server, staticnat is true and...
POST /v1/vm/{id}/port-forwarding — Add a port-forwarding rule
Forwards a public port (or port range) to a port of the server. The public and private ranges must have the same length. The call returns as soon as the change is queued (jobid).
DELETE /v1/vm/{id}/port-forwarding/{rule_id} — Delete a port-forwarding rule
Removes one port forwarding rule of the server. The call returns as soon as the removal is queued (jobid). Get the ruleid from List port forwarding rules.
DDoS Shield
Inspect and manage the DDoS Shield of your account: protected IPs, blocking rules, attack events, edge traffic, blackholes, web protection and AI analysis, and the agent installed on your own server. Reading needs the shield:read scope, changing rules and settings needs shield:write, and controlling the agent needs shield:agent. Every path contains your tenant identifier, which is shown on the Account page of the dashboard; a key can only reach the tenant of the account that owns it. Protected IPs are managed for you and cannot be added or removed through the API. Rules created by automatic attack mitigation are visible but read-only.
GET /v1/tenants/{tid} — Tenant overview: quota, usage and protected IPs
Returns your DDoS Shield account: status, limits, current usage and every protected IP with its blocking rules. Rules created by the protection system or by staff appear with an actor label instead of a name.
GET /v1/tenants/{tid}/blocks — All blocking rules of the tenant, flat and paged
Lists every blocking rule of the tenant across all protected IPs in one flat list, newest first, with cursor paging. To list the rules of one IP with their hit counters use the target rule list instead.
GET /v1/tenants/{tid}/blocks/export — Download the tenant's blocking rules as CSV
Downloads every blocking rule of the tenant as a CSV file with the columns id,targetip,kind,value,prefixes,note,by,at.
GET /v1/tenants/{tid}/countries — Country code table used by country rules
Returns the countries seen in recent traffic, for building country rules. Each entry has the ISO country code and its name. The call needs the traffic analyzer to be running and returns 503 unavailable otherwise.
GET /v1/tenants/{tid}/events — Attack events against the tenant's IPs
Lists attack events against the tenant's IPs, newest first (at most 300). Events from before an IP was assigned to you are never shown. Use brief=1 to drop the bulky sample arrays.
GET /v1/tenants/{tid}/events/{eid} — One attack event with packet sample
Returns one attack event with the captured packet sample (top sources, protocols and ports) and a link to the text report.
GET /v1/tenants/{tid}/events/{eid}/report — Plain-text incident report of an attack event
Downloads the incident report of an attack event as a plain-text file: target, type, times, peak rates, top sources and protocol mix. The text is written in Vietnamese.
GET /v1/tenants/{tid}/rtbh — Upstream blackhole (RTBH) entries of the tenant's IPs
Lists the upstream blackhole (RTBH) entries that currently cover the tenant's IPs, including entries created by the protection system. Use the target blackhole calls for the full detail of one IP.
DELETE /v1/tenants/{tid}/rtbh/{bid} — Withdraw a blackhole entry you created
Withdraws a blackhole entry that you created, so traffic to the IP flows again. Entries created by the protection system or by staff cannot be withdrawn this way.
POST /v1/tenants/{tid}/rtbh/{bid}/extend — Reset the lifetime of a blackhole entry you created
Restarts the lifetime of a blackhole entry that you created: it now expires ttls seconds from now (it does not add to the old remaining time).
GET /v1/tenants/{tid}/shape — Traffic shaping state of all the tenant's IPs (read-only)
Returns the traffic shaping (rate limiting) state of every protected IP of the tenant: whether a shaper applies, its limits and the live rates. Read-only.
GET /v1/tenants/{tid}/summary — DDoS Shield overview
Returns the overview shown on the DDoS Shield page of the dashboard: every protected IP with its current inbound and outbound rate, status, number of blocking rules and the attack in progress (if any), plus totals....
GET /v1/tenants/{tid}/targets — Protected IPs
Returns the IP addresses protected by DDoS Shield on your account, each with its blocking rules, web protection settings and cumulative edge counters. The list is not paginated.
GET /v1/tenants/{tid}/targets/{id}/agent — Monitoring agent installed on the VM that holds this IP
Returns the monitoring agent installed on the server that holds this IP: its settings, the last 60 samples, the addresses it currently blocks and its baseline. agent is null when none is installed. This call only reads...
PATCH /v1/tenants/{tid}/targets/{id}/agent — Change agent note, auto-block switch and thresholds
Changes the settings of the monitoring agent on the server that holds this IP. Turning enforce on lets the agent block, by itself, any source that exceeds the thresholds, which can cut off real users if the thresholds...
POST /v1/tenants/{tid}/targets/{id}/agent/cmd — Send a block, unblock or acct command to the agent
Sends a command to the agent on your server. block and unblock add or remove one source address in the agent's block list; acct asks the agent to refresh its accounting. The agent picks the command up at its next...
POST /v1/tenants/{tid}/targets/{id}/ai/analyze — Ask the AI to analyze one protected IP (uses a daily quota)
Asks the AI to analyze one protected IP, either one of its attack events or its last 30 minutes of traffic. The request is queued and the result appears in the AI task list within a minute or two. Each IP allows 3...
GET /v1/tenants/{tid}/targets/{id}/ai/tasks — AI analysis tasks of one protected IP and today's quota
Lists the AI analysis tasks of one protected IP, newest first, with the analyses still waiting and your quota for today. The analyzer states whether the traffic looks like an attack, why, and which blocking actions it...
GET /v1/tenants/{tid}/targets/{id}/ai/tasks/{task} — One AI analysis task
Returns one AI analysis task of a protected IP.
GET /v1/tenants/{tid}/targets/{id}/detail — Everything about one protected IP: status, history, rules, events, RTBH
Returns everything about one protected IP in a single call: protection status, current and baseline rates, the last 5 and 30 minutes of history, counters, up to 10 recent events, all blocking rules with their hit...
GET /v1/tenants/{tid}/targets/{id}/events — Attack events of one IP
Lists the attacks detected on one protected IP in the chosen period, newest first, and the attack in progress (open) if there is one. :id is the target id; the IP address itself is accepted too. Events from before the...
GET /v1/tenants/{tid}/targets/{id}/flows — Live connections of one protected IP
Lists the live connections of one protected IP, the busiest first: peer address, ports, protocol, bytes, packets and duration, refreshed every few seconds. Returns 503 unavailable when the traffic analyzer is not...
GET /v1/tenants/{tid}/targets/{id}/ips — Intrusion-prevention (IPS) alerts aimed at one protected IP
Returns the most recent intrusion-prevention (IPS) alerts aimed at one protected IP: source, ports, protocol, signature, category and severity (1 = highest). Alerts of other IPs are never shown.
GET /v1/tenants/{tid}/targets/{id}/logs — Action log of one protected IP (last 24 hours)
Returns the action log of one protected IP for the last 24 hours at most: rules added and removed, blackholes, web protection changes, AI requests and agent commands, each with the actor that did it.
GET /v1/tenants/{tid}/targets/{id}/rtbh — Blackhole (RTBH) entries of one protected IP
Returns the blackhole (RTBH) entries of one protected IP, the active one if any, and the allowed scopes and lifetimes for Blackhole an IP.
POST /v1/tenants/{tid}/targets/{id}/rtbh — Blackhole one of your IPs upstream (RTBH) — the IP goes offline for the chosen scope
Blackholes one of your IPs at the upstream network (RTBH): traffic to the IP is dropped before it reaches you, which stops a volumetric attack but takes the IP offline for the chosen scope. international drops traffic...
GET /v1/tenants/{tid}/targets/{id}/rules — Rules of one IP
Lists the blocking rules of one protected IP, newest first, with the number of packets and bytes each rule matched and the limits that apply when you add more. :id is the target id from List protected IPs; the IP...
POST /v1/tenants/{tid}/targets/{id}/rules — Add a blocking rule
Adds one or more blocking rules to a protected IP. A rule drops (block) or only counts (count) traffic from a source: an IPv4 address or network (/8 to /32), an IPv6 address or network (/32 to /128), an AS number such...
POST /v1/tenants/{tid}/targets/{id}/rules/bulk-delete — Delete up to 100 of your own blocking rules at once
Deletes up to 100 blocking rules of one protected IP in a single call. Only rules you created are deleted; rules made by the protection system or by staff are skipped and listed in skipped with the reason. Unknown...
GET /v1/tenants/{tid}/targets/{id}/rules/export — Download one IP's blocking rules as CSV
Downloads the blocking rules of one protected IP as a CSV file with the columns id,kind,value,mode,source,note,createdat,expiresat,hitspackets,hitsbytes,prefixes.
DELETE /v1/tenants/{tid}/targets/{id}/rules/{rid} — Delete a blocking rule
Deletes a blocking rule that was created by your account (actor is you in List blocking rules); the rule stops applying shortly after the call returns. Rules created by an integration, intrusion prevention, AI analysis...
GET /v1/tenants/{tid}/targets/{id}/shape — Traffic shaping state and history of one protected IP (read-only)
Returns the traffic shaping state of one protected IP: the shaper in effect with its limits, live rates in both directions and a history series. Read-only.
GET /v1/tenants/{tid}/targets/{id}/top — Top traffic sources of one protected IP over a range
Returns the traffic of one protected IP broken down by source country, source network, protocol and port over a time range, with a rate series for charting. The series columns are named in seriescols. Returns 503...
GET /v1/tenants/{tid}/targets/{id}/web — Web protection policy of one protected IP
Returns the web protection policy of one protected IP: per-source SYN and packet rate limits applied to the web ports, plus the allowed ranges and how often the policy may change.
PUT /v1/tenants/{tid}/targets/{id}/web — Change web protection (per-source SYN / packet rate limits) of one IPv4
Changes the web protection of one protected IPv4: per-source SYN and packet rate limits on the web ports. Values above the allowed maximum are clamped. Sending the policy that is already in effect succeeds with...
GET /v1/tenants/{tid}/traffic — Edge traffic
Returns, for each protected IP, the cumulative edge counters and the learned traffic baseline. counters holds packets and bytes per direction since the edge started (in is traffic toward your IP, out is traffic from...
GET /v1/tenants/{tid}/traffic/live — Live packet and bit rate of each protected IP
Returns the current packet and bit rate of every protected IP, computed from the last two counter readings. stale is true when no earlier reading was available to compare with.
GET /v1/tenants/{tid}/traffic/top-sources — Top attacking source IPs seen in the tenant's events
Returns the 50 source addresses that sent the most packets to your IPs across the recorded attack events. Useful for building block rules; the numbers come from packet samples, not from full counting.
Private Cloud
Private Cloud networks with their own dedicated, unmetered bandwidth plan. A Private Cloud is a private network (a /16 range) split into tiers (/24 subnets, each with its own IPv6 /64), protected by Network ACL rules, with one virtual router and one public IP address for outbound traffic. Servers are placed in a tier when you create them.
Creating, changing the plan, adding or removing tiers, editing ACL rules and deleting are asynchronous: the call answers 202 with an op and the Private Cloud settles in the background, so poll Get a Private Cloud or List operations. Only one operation runs at a time; a second change meanwhile fails with 409 vpc_busy.
Ordering calls (catalog, quote, create, change plan, add tier) answer 403 vpc_disabled while Private Cloud is not enabled for your account. Existing Private Clouds stay readable, their ACL can be edited and they can be deleted. Amounts ending in _cents are US cents; amounts ending in _uusd are millionths of a US dollar per hour; timestamps are Unix seconds. Hidden on sites that do not sell Private Cloud.
GET /v1/vpc — List Private Clouds
Lists your Private Clouds, oldest first by default. Deleted Private Clouds are hidden unless you filter with state=deleted, which shows those deleted in the last 30 days. Besides the page, the response tells you whether...
POST /v1/vpc — Create a Private Cloud (prepaid cycles charge the wallet)
Orders a new Private Cloud: a private /16 network with a default tier, a virtual router with one public IP address for outbound traffic, default Network ACL rules (SSH, RDP and ICMP in, everything out) and a dedicated...
GET /v1/vpc/catalog — Private Cloud catalog: bandwidth plans, cycles, limits
Returns what you can order: the bandwidth plans (dedicated, unmetered Mbps) with their price for every billing cycle, the billing cycles, the region where Private Clouds are built, and the limits that apply to your...
GET /v1/vpc/quote — Quote a Private Cloud + required balance (no charge)
Prices one plan for one billing cycle and tells you whether you can order it right now, without creating or charging anything. quote holds the prices; funds compares your wallet with the balance an order needs...
GET /v1/vpc/{id} — Get one Private Cloud
Returns one Private Cloud with its tiers, billing, current operation and what you can do with it now (can). A Private Cloud you deleted stays readable, with state deleted, for 30 days. Use the list calls for the parts...
PATCH /v1/vpc/{id} — Rename / notes / auto-renew
Changes the name, the note or the automatic renewal of a Private Cloud. Nothing is charged and the network is not touched. Send only the fields you want to change. It works in every state except deleting, deleted and...
DELETE /v1/vpc/{id} — Delete the Private Cloud (no VMs left)
Deletes a Private Cloud with its tiers and ACL rules, and releases its public IP address. Every server in it must be deleted first (409 vpchasvms), and you confirm by sending the exact name of the Private Cloud. The...
GET /v1/vpc/{id}/acl — Network ACL rules
Lists the Network ACL rules of a Private Cloud in ascending order of number. The ACL applies to all tiers. A new Private Cloud starts with rules that allow SSH (22), RDP (3389) and ICMP in and everything out for IPv4...
POST /v1/vpc/{id}/acl — Add a Network ACL rule
Adds a Network ACL rule. The rule is applied in the background: the call returns 202 with the rule in state pending, and it filters traffic once its state is active. Rules are evaluated in ascending order of number and...
DELETE /v1/vpc/{id}/acl/{rule} — Delete a Network ACL rule
Deletes a Network ACL rule, including the default rules created with the Private Cloud. The rule stops filtering traffic within a few seconds; the call returns 202 while it is removed in the background. Platform rules...
GET /v1/vpc/{id}/bandwidth — Bandwidth chart (Mbps, plan limit)
Returns inbound and outbound traffic of all public addresses of the Private Cloud (router address, server addresses and the IPv6 prefixes of the tiers) as a time series in Mbit/s, with the bandwidth cap of the plan and...
GET /v1/vpc/{id}/billing — Private Cloud billing
Returns what this Private Cloud costs and the wallet entries it caused: the creation charge, hourly charges or renewals, plan-change charges and refunds. spentmonthcents and spenttotalcents are net amounts (charges...
GET /v1/vpc/{id}/delete-preview — Preview before deleting
Shows what Delete a Private Cloud would do, without changing anything: how many servers and tiers are inside, the public IP that would be released, the wallet refund for unused prepaid time, and whether the deletion is...
GET /v1/vpc/{id}/events — Private Cloud event log
Returns the activity log of a Private Cloud, newest first by default: who did what and when (orders, renames, plan changes, tier and ACL changes, locks and unlocks, deletion). actor is you for changes made with your...
GET /v1/vpc/{id}/ips — Public IPs of the Private Cloud
Lists the public IPv4 addresses that belong to the Private Cloud: the address of the virtual router, used for outbound traffic of servers without their own address (kind snat), and the public address of each server that...
GET /v1/vpc/{id}/ops — Private Cloud operations
Lists the operations of a Private Cloud (creation, plan changes, tier and ACL changes, deletion), newest first. Use it to follow an op returned by a write call: it is finished when state is done, failed or cancelled. At...
POST /v1/vpc/{id}/plan — Change bandwidth plan (costs money)
Changes the dedicated bandwidth plan of the Private Cloud. The new bandwidth is applied to every tier in the background (the Private Cloud shows an open changeplan operation until it is done). On a prepaid cycle the...
GET /v1/vpc/{id}/plan-quote — Quote a bandwidth plan change
Shows what changing the bandwidth plan of this Private Cloud to plan would cost, without changing anything. For a prepaid cycle the difference for the rest of the paid period is charged (chargecents) or refunded...
GET /v1/vpc/{id}/tiers — List tiers (subnets)
Lists the tiers (subnets) of a Private Cloud, the default tier first, with the number of servers in each. max is the most tiers a Private Cloud may have, the default tier included. Deleted and failed tiers are not...
POST /v1/vpc/{id}/tiers — Add a tier
Adds a tier (a /24 IPv4 subnet with its own IPv6 /64) to the Private Cloud. The tier is created in the background: the call returns 202 with the new tier in state provisioning; it can host servers once it is active....
DELETE /v1/vpc/{id}/tiers/{tier} — Delete a tier (no VMs left)
Deletes a tier that has no servers left. The tier moves to deleting and is removed in the background (202 with an op). A tier that never became ready (state failed, not listed) is discarded at once and answered with 200...
GET /v1/vpc/{id}/vms — VMs in the Private Cloud
Lists the servers that are in the Private Cloud, newest first, with the tier each one is in. Servers you deleted are not listed. To put a server in a Private Cloud, choose the network and tier when you create it.
Bandwidth
Monthly traffic quota of your services and the Add-ons that raise it. Every server, container cluster, object-storage account and VPN plan has a quota per billing period; unmetered services (for example servers inside a Private Cloud network) have none. Reading is free. Buying an Add-on adds terabytes to the current billing period of one service, charges your wallet and requires an Idempotency-Key. In this section 1 TB means 2^40 bytes and 1 GB means 2^30 bytes.
GET /v1/bandwidth/addons — Bandwidth Add-on purchase history
Lists the Add-ons you bought or were granted, for all services and all periods, newest first. Each entry shows the service it belongs to, the period it was valid for, the terabytes added and the amount charged. It is a...
GET /v1/bandwidth/objects — Bandwidth per service (paged, sortable)
Lists every service of your account that has a bandwidth quota (servers, container clusters, your object storage and VPN plans) with its usage in the current billing period. The list is filtered, sorted and paged on the...
GET /v1/bandwidth/objects/{kind}/{ref} — Bandwidth of one service
Returns the bandwidth of one service: quota, Add-ons of the current period, usage, the Add-on price and the policy that applies when the quota is used up. Pass series to get the traffic chart data in the same call...
POST /v1/bandwidth/objects/{kind}/{ref}/addons — Buy a Bandwidth Add-on (charges the wallet)
Buys an Add-on of tb terabytes for one service and charges your wallet immediately. The Add-on raises the limit of the current billing period only and expires at periodend; it is not refunded and does not carry over....
GET /v1/bandwidth/objects/{kind}/{ref}/quote — Quote a Bandwidth Add-on
Prices an Add-on of tb terabytes for one service without buying anything. The Add-on is valid for the current billing period only (periodend) and the price is flat per terabyte. Take amountcents from the response and...
GET /v1/bandwidth/objects/{kind}/{ref}/series — Hourly/daily traffic of one service
Returns the traffic of one service over time, ready for a chart. 24h gives hourly points for the last 24 hours; 7d and 30d give daily points (days start at midnight UTC+7); period (the default) gives daily points from...
GET /v1/bandwidth/summary — Bandwidth totals across services
Returns the traffic totals of all your services for their current billing periods, together with the Add-on price and the policy applied when a service runs out of quota. Use it for a dashboard header; call List...
VPN and Proxy
VPN IPv4 and Proxy IPv6 plans. The vpn:read scope gives an app or script what it needs to connect: the plans, IP addresses, ports, user names and passwords. Separate scopes cover plan details such as traffic and configuration files (vpn:detail), changing settings (vpn:write), buying, renewing and upgrading (vpn:create, costs money) and cancelling (vpn:destroy). The responses contain live proxy credentials, so treat them as secrets and give each key only the scopes it needs. Hidden on sites that do not sell VPN or proxies.
DELETE /v1/ext/session — The key revokes itself (app log out)
Revokes the API key that makes the call, immediately and permanently. Apps use it as a "log out" button: the next request with the same key fails with 401. Only the calling key is affected; other keys and dashboard...
GET /v1/proxy6/subscriptions — List Proxy IPv6 plans
Lists your Proxy IPv6 plans, newest first. Each plan shows its type and size, the host and ports to connect to, the user name and the rotation state. The password is not included in the list (proxy6.password is null)...
POST /v1/proxy6/subscriptions — Buy a Proxy IPv6 plan (charges the wallet)
Buys a Proxy IPv6 plan. The price is charged to the wallet and the proxy is set up at once; if setup fails after payment the amount is refunded automatically. Get plans, speeds and cycles from the Proxy IPv6 catalog...
GET /v1/proxy6/subscriptions/{id} — Get one Proxy IPv6 plan (with password)
Returns one Proxy IPv6 plan including the connection password (proxy6.password), so this response is sensitive. With proxy6.host, proxy6.ports, proxy6.username and the password you can configure any HTTP or SOCKS5...
DELETE /v1/proxy6/subscriptions/{id} — Remove a canceled or expired Proxy IPv6 plan from your list
Removes a finished plan from your list. Only plans that are canceled, expired or failed and whose addresses have been released can be removed. The plan and its invoices are kept for the records. Repeating the call...
PUT /v1/proxy6/subscriptions/{id}/auto-renew — Turn auto-renew on or off (turning it on can renew from the wallet at once)
Turns auto-renew on or off. When on, the plan renews itself from the wallet shortly before it expires. Turning it on for a plan that is already due renews it immediately; renew then reports what happened. Turning it off...
GET /v1/proxy6/subscriptions/{id}/billing — Invoices that belong to a Proxy IPv6 plan
Lists every invoice that belongs to the plan (purchase and renewals), newest first. Invoices issued to a previous owner (after a transfer) are marked previousowner and their buyer details are redacted.
POST /v1/proxy6/subscriptions/{id}/cancel — Cancel a Proxy IPv6 plan now (no refund; addresses are released)
Cancels the plan immediately. The proxy stops working and the addresses are released. Nothing is refunded, even if time remains. To prevent accidents you must repeat the plan id in confirm. Canceling an already canceled...
GET /v1/proxy6/subscriptions/{id}/cancel-preview — Preview of canceling a Proxy IPv6 plan
Shows what canceling the plan would do, without changing anything: whether it can be canceled, how many addresses would be released, and that no refund is given.
GET /v1/proxy6/subscriptions/{id}/export — Download the proxy list of a Proxy IPv6 plan (with password)
Downloads the proxies of the plan as a text file in the chosen format. Every line carries the proxy password, so treat the file as a secret. For static plans there is one line per address (the user name carries the...
GET /v1/proxy6/subscriptions/{id}/ips — IPv6 addresses of the plan (paged)
Returns the IPv6 addresses currently assigned to a Proxy IPv6 plan, ordered by slot, together with the user name (and, on static plans, the dedicated port) that selects each address. A static plan has one address per...
GET /v1/proxy6/subscriptions/{id}/logs — Connection log of a Proxy IPv6 plan (paged, searchable)
Returns the connection log of the plan, newest first: which client address connected to which destination through which outgoing IPv6 address, with the transferred bytes and whether the connection was denied. Without q...
POST /v1/proxy6/subscriptions/{id}/release-device — Release the devices locked to the plan
Releases the devices (client source IPs) locked to the plan. The plan allows a limited number of devices; the first devices that connect are locked in. After a release, the next devices that connect are locked instead.
POST /v1/proxy6/subscriptions/{id}/renew — Renew a Proxy IPv6 plan (charges the wallet)
Renews the plan for one or more periods at the price fixed when it was bought. The amount is charged to the wallet and the expiry moves forward; for rotating plans more rotations are added to the plan. Send an...
POST /v1/proxy6/subscriptions/{id}/reset-password — Generate a new proxy password (returned once)
Generates a new proxy password and returns it. The old password stops working at once, so update your clients. At most 5 resets per plan every 5 minutes.
POST /v1/proxy6/subscriptions/{id}/rotate — Rotate the IPv6 address now (uses one rotation of the plan)
Rotates the IPv6 address of a rotating plan now and returns the new one. Each call uses one of the plan's rotations; when none are left the call fails with turnsexhausted until you renew. Send an Idempotency-Key so that...
PUT /v1/proxy6/subscriptions/{id}/rotation — Set the automatic IP rotation interval (0 = off)
Sets the automatic rotation interval of a rotating plan. Every automatic rotation uses one of the plan's rotations. Static plans cannot rotate.
POST /v1/proxy6/subscriptions/{id}/rotation/token — Issue a new public rotation link (anyone holding it can burn rotations)
Issues a new public rotation link and invalidates the previous one. Calling the link (GET or POST, no API key needed) rotates the address once, which is handy for scripts and phones. Anyone who holds the link can use up...
GET /v1/proxy6/subscriptions/{id}/traffic — Real traffic chart and usage of a Proxy IPv6 plan
Returns real traffic of the plan: a time series for charting, the latest rate, the usage of the current billing period and the busiest endpoints. Minute buckets are available for 1h and 6h, hourly buckets for longer...
GET /v1/vpn/endpoints — All endpoints of active plans (IP, ports, user/pass)
Returns the endpoints of all your active VPN IPv4 plans in one flat list, ready to feed an app that lets the user pick an IP. The response contains the proxy passwords.
GET /v1/vpn/subscriptions — List VPN IPv4 plans
Lists your VPN IPv4 plans, newest first, with status, expiry and the number of endpoints of each plan. The list is not paginated. Plans you removed from your list and orders that were rejected before any payment are...
POST /v1/vpn/subscriptions — Buy a VPN IPv4 plan (charges the wallet)
Buys a VPN IPv4 plan. The price is charged to the wallet and the IP addresses are allocated and activated at once. If activation fails after payment the amount is refunded automatically. Only dedicated IPs are on sale....
GET /v1/vpn/subscriptions/{id} — Get one VPN IPv4 plan + endpoints (with passwords)
Returns one VPN IPv4 plan with its endpoints. Each endpoint carries the IP address, the SOCKS5, HTTP and UDP ports, and the user name and password to connect with, so this response is sensitive. The renewal history and...
DELETE /v1/vpn/subscriptions/{id} — Remove a canceled or expired VPN IPv4 plan from your list
Removes a finished plan from your list. Only plans that are canceled, expired or failed and whose IP addresses have been released can be removed. The plan and its invoices are kept for the records; it just stops...
GET /v1/vpn/subscriptions/{id}/addons — Active add-ons and add-ons you can still buy, with mid-term prices
Lists the add-ons currently active on the plan and the add-ons you can still buy, with the prorated price of adding each one now. canadd is false, with a reason, when add-ons cannot be bought right now.
POST /v1/vpn/subscriptions/{id}/addons — Add features to a plan mid-term (charges the wallet)
Adds add-ons to the plan in the middle of a period. The price is prorated for the days left and charged now; the add-ons are included in later renewals. Retired add-ons are rejected. See List add-ons for the keys and...
POST /v1/vpn/subscriptions/{id}/addons/remove — Schedule removal of add-ons at the next renewal (no refund)
Schedules add-ons for removal at the next renewal. Nothing is refunded and the add-ons keep working until the plan renews. Send an empty list to cancel a scheduled removal.
GET /v1/vpn/subscriptions/{id}/auth-ips — IPs authorized to use the plan without user and password
Returns the IP addresses and networks that may use the plan without a user name and password. The limit is 3 entries, or 1000 with the ipauth add-on.
PUT /v1/vpn/subscriptions/{id}/auth-ips — Replace the list of authorized IPs of a plan
Replaces the whole list of authorized IPs. Addresses and networks must be valid CIDR; networks wider than /16 (IPv4) or /32 (IPv6) are rejected, and so is a list longer than the limit (3, or 1000 with the ipauth...
PUT /v1/vpn/subscriptions/{id}/auto-renew — Turn auto-renew on or off (turning it on can renew from the wallet at once)
Turns auto-renew on or off. When on, the plan renews itself from the wallet shortly before it expires (and during the grace period after expiry). Turning it on for a plan that is already due renews it immediately; renew...
GET /v1/vpn/subscriptions/{id}/bandwidth — Bandwidth tiers you can upgrade to, with prices
Lists the bandwidth tiers you can upgrade this plan to, with the amount that would be charged now (prorated for the days left) and the renewal price afterwards. canupgrade is false, with a reason, when the plan cannot...
POST /v1/vpn/subscriptions/{id}/bandwidth — Upgrade the bandwidth tier mid-term (charges the wallet)
Upgrades the monthly bandwidth quota to a higher tier in the middle of a period. The difference is charged now, prorated for the days left, and the renewal price rises accordingly. Only higher tiers are accepted. See...
GET /v1/vpn/subscriptions/{id}/billing — Invoices that belong to a VPN IPv4 plan
Lists every invoice that belongs to the plan: purchase, renewals, bandwidth upgrades and add-ons, newest first. Invoices issued to a previous owner (after a transfer) are marked previousowner and their buyer details are...
POST /v1/vpn/subscriptions/{id}/cancel — Cancel a VPN IPv4 plan now (no refund; IPs are released)
Cancels the plan immediately. The proxies stop working and the IP addresses go back to the pool. Nothing is refunded, even if time remains. To prevent accidents you must repeat the plan id in confirm. Canceling an...
GET /v1/vpn/subscriptions/{id}/cancel-preview — Preview of canceling a VPN IPv4 plan
Shows what canceling the plan would do, without changing anything: whether it can be canceled, how many IPs would be released, and that no refund is given.
GET /v1/vpn/subscriptions/{id}/config — Download the connection list (SOCKS5/HTTP, plain, Clash, sing-box, v2rayN)
Downloads the connection list of the plan as a plain-text file in the chosen format. The file contains the user name and password of every active endpoint, so treat it like a secret. Formats: socks / http (URL lines)...
POST /v1/vpn/subscriptions/{id}/feed/rotate — Issue a new subscription-feed link (the old link dies)
Issues a new subscription-feed link and invalidates the previous one. The feed is a public URL (no API key needed) that VPN apps download to get the plan's proxies, so anyone holding it can use the plan: treat the token...
GET /v1/vpn/subscriptions/{id}/ip-reports — Blacklist reports you filed for the plan's IPs
Lists the blacklist reports you filed for the IP addresses of the plan, newest first (up to 100). Use Report IPs to file one.
POST /v1/vpn/subscriptions/{id}/ip-reports — Report blacklisted IPs of a plan for replacement
Reports IP addresses of the plan that are blacklisted or blocked by a site, asking for replacements. Each IP is checked against public blacklists immediately and the result is attached to the report. A reviewer then...
POST /v1/vpn/subscriptions/{id}/renew — Renew a VPN IPv4 plan (charges the wallet)
Renews the plan for one or more periods at the price fixed when it was bought (not the current catalog price). The amount is charged to the wallet and the expiry moves forward. Active plans, and expired plans that still...
GET /v1/vpn/subscriptions/{id}/traffic — Real traffic chart and usage of a VPN IPv4 plan
Returns real traffic of the plan: a time series for charting, the latest rate, the usage of the current billing period against the quota, and the busiest endpoints. Minute buckets are available for 1h and 6h, hourly...
Bring Your Own IP
Announce your own IPv4 or IPv6 prefix over BGP and use it on your VMs. Two types: leased (a prefix you lease from an IP provider) and own (a prefix your organisation holds at a RIR/LIR). Flow: register the prefix and origin ASN → publish an RPKI ROA, an IRR route/route6 object and the verification token (byoip-verify=<token>) in the prefix whois (or in the aut-num of your ASN) at the RIR — RIPE, APNIC, ARIN, AFRINIC or LACNIC database; objects in RADB/ALTDB and other open IRRs do not count as proof → the platform verifies automatically every 10 minutes for up to 7 days (you are not charged before verification passes; a prefix that is already announced on the Internet goes to a manual review) → the prefix is announced and a private L2 network with gateway .1/::1 is created → attach it to a VM (a second NIC) and configure the addresses shown in setup. Accepted sizes: IPv4 /24–/22, IPv6 /48–/32 (configurable per site, see GET /v1/byoip/catalog).
GET /v1/byoip — List your own IP prefixes
Lists your prefixes (ended ones stay visible for 30 days).
POST /v1/byoip — Register an own IP prefix (waits for verification, not charged yet)
Registers a prefix for verification. Requires Idempotency-Key and agreeterms: true. Nothing is charged now: once RPKI (ROA for the origin ASN), the IRR route object and the token pass, the monthly BGP fee of the origin...
GET /v1/byoip/catalog — BYOIP catalog: types, prefix sizes, prices and limits
Types, accepted prefix sizes, prices (VND list price and wallet cents), verification rules and limits of the site.
POST /v1/byoip/check — Quick check of a prefix before registering (no external lookups)
Checks a prefix and ASN before registering: syntax, accepted size, special-use ranges, overlap with the provider's or other customers' prefixes. No external lookup; RPKI/IRR are checked after you register. Limited to 30...
GET /v1/byoip/quote — BYOIP quote by type and ASN
Price of registering a prefix of the given type and origin ASN. The monthly BGP fee is charged once per origin ASN and type: a second prefix with the same ASN costs nothing extra.
GET /v1/byoip/subnets — Your IPv4 subnet orders
Your subnet orders, newest first.
POST /v1/byoip/subnets — Order an IPv4 subnet (charges the first month and the setup fee)
Orders a subnet from the market. Requires Idempotency-Key and agreeterms: true. The first month and the setup fee are taken from the wallet now; the subnet is leased in the background and becomes active once its LOA is...
GET /v1/byoip/subnets/market — IPv4 subnets for sale priced for your account
Same list as the public market, priced for your account, plus your wallet balance and the platform ASN you may use for routing at this platform.
GET /v1/byoip/subnets/{id} — Subnet order details
One subnet order: state, price, billing period and, for platform, the Bring Your Own IP prefix created for it (byoipid).
POST /v1/byoip/subnets/{id}/cancel — Cancel a subnet (before leasing: full refund; in use: stop renewal)
Before the subnet is leased (paid): cancels and refunds everything. In use (active, grace): stops renewal at the end of the paid month (no refund). Requires Idempotency-Key.
GET /v1/byoip/vms/eligible — VMs eligible for own IP prefix (Ho Chi Minh City zone)
Your VMs eligible for own IP prefix (Ho Chi Minh City zone). eligible=false = VM is not running.
GET /v1/byoip/{id} — Prefix details: verification results, instructions, VM setup
Prefix details: verification checks, the token to publish, ROA/IRR/LOA instructions, attachments and, once active, the VM configuration (policy routing, MTU).
POST /v1/byoip/{id}/cancel — Cancel a prefix (remove the setup, withdraw BGP)
Cancels a prefix. Before it is charged the request simply ends; after that the setup is removed, the BGP announcement is withdrawn and VMs lose the addresses. The current month is not refunded; a setup that never became...
GET /v1/byoip/{id}/events — Prefix activity log
Activity log of a prefix (verification, charge, setup, BGP, attachments).
POST /v1/byoip/{id}/move — Move prefix from one VM to another in one step
Transfer the prefix from this VM to another of your VMs (Ho Chi Minh City zone) in one step: detaches old VM and attaches new VM simultaneously. Requires Idempotency-Key.
POST /v1/byoip/{id}/review-request — Request a manual review (when the token cannot be published)
Asks for a manual review when RPKI and IRR already pass but you cannot publish the token (for example a leased prefix whose whois you cannot edit). Attach the LOA reference in note.
POST /v1/byoip/{id}/verify — Verify again now (RPKI, IRR, token)
Runs the verification now instead of waiting for the next automatic check (every 10 minutes). Limited to once per minute per prefix and 20 per hour per account. When it passes the prefix moves on (charge + setup)...
GET /v1/byoip/{id}/vms — Attached VM + IP configuration commands
Attached VMs, NIC statuses, and IP configuration commands inside each VM.
POST /v1/byoip/{id}/vms — Attach prefix to an additional VM
Attach the prefix to another VM in your Ho Chi Minh City zone (a prefix can attach to multiple VMs). A second NIC is added while the prefix is active. Requires Idempotency-Key; 10 attach/detach/transfer operations per...
DELETE /v1/byoip/{id}/vms/{vm} — Detach prefix from VM (last VM ⇒ prefix pending attachment, BGP retained)
Detach prefix from a VM. Detaching the last VM ⇒ prefix waits for another VM (needsvm), BGP remains active. Requires Idempotency-Key.
POST /v1/byoip/{id}/vpc-requests — Request prefix attachment to Private Cloud (manually set up by network team)
Request to attach prefix to your Private Cloud (VPC). The network team sets it up manually within 1–2 business days and reports results in the prefix logs. Requires Idempotency-Key.
DELETE /v1/byoip/{id}/vpc-requests/{rid} — Cancel pending Private Cloud attachment request
Cancel a pending Private Cloud attachment request. Requires Idempotency-Key.
GET /v1/public/ip-subnets — IPv4 subnets for sale (public, monthly price plus a one-time setup fee)
IPv4 subnets for sale (/24–/22, RPKI managed automatically), public — no login. Prices are the final monthly price in US cents; setupcents is charged once per subnet. Filter, sort and page on the server.
GET /v1/vm/{id}/byoip — Own-IP attachment of a VM and sample configuration
Own-IP state of a VM: whether it can be attached, the attachment, and the commands/netplan to configure each active prefix inside the VM (policy routing keeps the main default route of the VM).
POST /v1/vm/{id}/byoip/attach — Attach your own-IP network to a VM (adds a NIC)
Adds a second NIC on your private own-IP network to the running VM (hot-plug). Then configure the addresses shown in prefixes[].setup. Requires Idempotency-Key; 10 attach/detach per minute.
POST /v1/vm/{id}/byoip/detach — Detach your own-IP network from a VM
Removes the own-IP NIC from the VM. Requires Idempotency-Key.
API Reference
Account
Billing
Read-only access to your wallet, invoices, payments, orders and current usage. Money can only be added, and payment methods only be changed, from the dashboard; no API key can do it. Unless a field says otherwise, amounts are integers in US cents (*_cents). Prices per hour are given in millionths of a dollar (*_uusd*) or thousandths of a dollar (*_mills*).
GET /v1/billing/invoices — List invoices
Lists your invoices: receipts for purchases, renewals, top-ups, refunds and manual invoices. The list also includes invoices issued to the previous owner of a server that was transferred to you; those are marked...
GET /v1/billing/invoices/{id} — Get one invoice
Returns one invoice with its line items and the seller and buyer details parsed into objects. An invoice that belongs to another account answers 404, except invoices issued to the previous owner of a server that was...
GET /v1/billing/orders — Order history
Lists your orders: every invoice that is about a server (purchases, plan and cycle changes, renewals, refunds), newest first by default. Each order carries the first line of its invoice as description and a short...
GET /v1/billing/payments — Payment history
Lists the payments made into your wallet: top-ups (started by you or automatic) and refunds, newest first by default. A payment adds to the wallet only once its status is completed; pending ones are still waiting for...
GET /v1/billing/summary — Billing overview
Returns an overview of your spending: balance, what has been charged this month, what is overdue, and how fast running hourly servers burn through the wallet. It also carries the site's top-up limits, fee schedule and...
GET /v1/billing/wallet — Wallet balance
Returns your wallet balance and its transaction history, newest first by default. The wallet is a prepaid balance in US cents: top-ups and refunds add to it, server charges take from it. The balance can be negative...
GET /v1/client/usage — Current usage
Returns the resources your account uses right now: the total vCPU, memory and disk of all servers that are active, locked or being provisioned, the number of public addresses and servers, and how many attacks were...
GET /v1/orders — Orders across all services
Lists your orders across every service in one place: purchases, renewals, upgrades, add-ons, top-ups, refunds and usage. Orders come from your invoices, from wallet charges that have no invoice, and from metered hourly...
Account
Your account at a glance and read-only access to your API keys: profile, dashboard overview, activity timeline, bandwidth, notifications, resource quota, printable invoices and DDoS analyses. The only call here that changes anything is marking notifications as read. Editing the profile, password, e-mail or two-factor settings, and creating, editing or revoking API keys, are not available through the API and can only be done from the dashboard.
GET /v1/apikeys — List the account's API keys (never the raw key)
Lists all API keys of your account, newest first, including expired and revoked ones. The list is not paged. The secret key and its hash are never returned, and hint shows only the first characters (7 when listed...
GET /v1/apikeys/log — API key usage log of the account (paged)
Returns the usage log of all API keys of your account, newest first by default. Only calls that change something (any method except GET) and every failed call (HTTP status 400 and above) are logged; successful reads are...
GET /v1/apikeys/self — The calling key itself: scopes, expiry, allowed IPs, rate limits
Returns information about the API key making the call: its permissions, expiry, allowed IP addresses, usage, and how many requests it may still make in the current minute. Every key can call this operation whatever its...
GET /v1/billing/invoices/{id}/print — Printable HTML invoice (?cur=usd|vnd)
Returns one of your invoices as a self-contained HTML page ready to print or save as PDF from a browser. The page contains the seller, buyer, line items and totals, in your account language. Amounts are shown in US...
GET /v1/billing/notifications — Latest 50 notifications and the unread count
Returns your 50 newest notifications, newest first, with a count of unread ones. unread counts only the notifications in items, so it is at most 50. One-time credential messages are never included. Mark notifications as...
POST /v1/billing/notifications/read — Mark notifications as read (empty = all)
Marks notifications as read. Send ids to mark specific notifications, or send an empty body (or an empty ids) to mark every unread notification of the account. Identifiers that do not exist, belong to another account or...
GET /v1/client/quota — Resource quota of the account
Returns the resource limits of your account and how much you use. When quota is switched on for the site, limits follow the funds you keep in the wallet: the largest plan whose 24-hour cost your funds cover sets the...
GET /v1/portal/activity — Account activity timeline (paged)
Returns one timeline of what happened on your account, newest first: server events (create, start, stop, reboot, reinstall, destroy, lock, plan change, renewal), wallet deposits and refunds, important notifications and...
GET /v1/portal/ai-analyses — AI analyses of attacks on your IPs
Returns the latest automatic analyses of attacks against your IP addresses: what the attack looked like, the verdict, a confidence figure and a short summary. Only analyses of addresses that belong to you are returned....
GET /v1/portal/bandwidth — Bandwidth used by the account
Returns the traffic of all your servers and VPN addresses added together: live rates, a time series of the chosen range, the attacks seen in that range and totals. With live=1 only the live block is returned, which is...
GET /v1/portal/me — Account profile (read-only)
Returns the profile of the account the API key belongs to: identity, status, preferred language and display currency, whether a password is set, and the DDoS protection workspace. It is read-only; changing the profile...
GET /v1/portal/overview — Overview: balance, burn rate, VMs, checklist
Returns everything the dashboard home page shows, in one call: the wallet balance, how long it will last at the current spend (runway), spend this month with a forecast, your servers, a getting-started checklist, the...
Support Tickets
Open and follow support tickets of your account. A ticket is a conversation between you and the support team: you create it with a subject and a first message, either side can reply, and you can close it when it is solved. Opening a ticket is limited to 5 per hour per account. On sites operated by a reseller the ticket goes to that reseller's support queue, and it is not available when the reseller has turned tickets off.
GET /v1/portal/tickets — List support tickets (filter, paged)
Returns the tickets of your account, newest activity first by default. Filter by status or search the subject with q. Only your own tickets are ever listed.
POST /v1/portal/tickets — Open a support ticket
Opens a ticket with its first message and returns both. The support team is notified. At most 5 tickets can be opened per hour per account; the sixth is rejected with ratelimited. Send the same Idempotency-Key again to...
GET /v1/portal/tickets/{id} — Get one ticket with its messages
Returns one ticket with all of its messages in chronological order. Internal notes written by the support team are never included.
POST /v1/portal/tickets/{id}/close — Close a ticket
Closes one of your tickets. Closing a ticket that is already closed succeeds and changes nothing. Closed tickets stay readable.
POST /v1/portal/tickets/{id}/messages — Reply to a ticket
Adds a message to one of your tickets and sets its status back to open. A closed ticket cannot be replied to: open a new ticket instead. Replies sent with an API key are limited to 30 per hour per account.
Affiliate
Read-only view of your affiliate programme: your referral code and link, the customers you referred, the commissions they generated and your payout history. Joining the programme, converting commission into wallet credit and withdrawing cash are only available in the web console. The programme is only offered on the main site; on reseller sites these calls return feature_disabled.
GET /v1/aff — Affiliate status, referral code and stats
Returns the programme rules, whether you have joined, and (once you have) your referral code, link, status, balances and a 30-day activity series. Use it to check eligibility before sending customers to your link. Cash...
GET /v1/aff/commissions — Commissions (paged)
Lists the commissions generated by your referrals, with the progress each one has made towards maturing. Reversed zero-amount records are not listed.
GET /v1/aff/events — Affiliate ledger events (paged)
Lists the ledger of your affiliate account, newest first: every maturing, payment, clawback, expiry or manual adjustment of a commission. The ledger is append-only.
GET /v1/aff/payouts — Payout history (paged)
Lists your payout history: conversions of commission into wallet credit and cash payout requests, newest first. Creating or cancelling a payout is only possible in the web console.
GET /v1/aff/referrals — Referred users (anonymised, paged)
Lists the customers who registered through your link. Customers are anonymous: you only see a stable label such as #a3f1, never a name or e-mail address. Requires that you joined the programme.
Service Transfers
Read-only view of requests to move a server or a VPN plan to another account. A transfer needs the owner to confirm by e-mail and the recipient to accept, so creating, accepting, declining or cancelling one is only possible in the web console by a signed-in person. These calls let you follow the progress of the requests you sent and the ones addressed to you, and check in advance whether a service can be transferred.
GET /v1/transfers — List service transfer requests (outgoing or incoming)
Lists transfer requests. By default it returns the requests you sent (dir=out); with dir=in it returns the requests addressed to your account, which only appear once the sender confirmed them and show fewer fields.
GET /v1/transfers/precheck — Check whether a service can be transferred
Checks whether one of your services can be transferred right now, without starting anything. ok is true when reasons is empty; otherwise each reason names a blocker, for example an unpaid invoice, a server that is not...
GET /v1/transfers/{id} — Get one transfer request
Returns one transfer request you sent or that is addressed to you. A request addressed to you is only visible after the sender confirmed it.
API Reference
Containers
Kubernetes
Managed Kubernetes clusters: a free, fully managed control plane plus worker nodes that you pick from a fixed list of worker plans. Workers are billed like servers (by the hour while they run, or up front for monthly and longer billing cycles) and the control plane costs nothing. Creating, scaling, starting, stopping and deleting a cluster are asynchronous: the call answers 202 Accepted with an operation, and the cluster reports state and op while the work runs. Creating, scaling and deleting charge or release wallet money, so they require an Idempotency-Key. A cluster is provisioning until it is built, then active or stopped; it becomes locked when the wallet or the site blocks it, and deleting then deleted when removed. Kubernetes is hidden on sites that do not sell it. On such a site the catalog, quote, create and scale calls answer 403 k8s_disabled, while existing clusters can still be listed, started, stopped, deleted and their kubeconfig downloaded.
GET /v1/k8s/catalog — Kubernetes catalog: zones, versions, worker plans, cycles
Returns everything needed to order a cluster: the regions that offer Kubernetes, the versions you can choose, the fixed worker plans with their price per hour and for each billing cycle, the billing cycles, the...
GET /v1/k8s/clusters — List clusters
Lists your clusters with the state, size and price of each. By default deleted clusters are hidden; filter with state=deleted to see the ones deleted in the last 30 days. The items do not include note; fetch a single...
POST /v1/k8s/clusters — Create a cluster (prepaid cycles charge the wallet)
Orders a new cluster. The request is validated and priced at once; the cluster itself is built in the background, so the call returns 202 Accepted with the cluster in state provisioning and the queued operation. Poll...
GET /v1/k8s/clusters/{id} — Get one cluster
Returns one cluster with its configuration, state, price, billing terms, any lock and any operation in progress. can tells which actions are possible right now. A deleted cluster stays readable for 30 days after...
PATCH /v1/k8s/clusters/{id} — Rename / notes / auto-renew
Changes the display name, the note or the auto-renew setting of a cluster. Only the fields you send change; an empty object changes nothing. Renaming only changes the label: the cluster keeps running and existing...
DELETE /v1/k8s/clusters/{id} — Delete the cluster (data is lost)
Deletes the cluster with all its nodes and disks, its stored data and its public IP address. This cannot be undone. Send the exact cluster name in confirm; call Preview a deletion first to see what will be lost and the...
GET /v1/k8s/clusters/{id}/bandwidth — Cluster Bandwidth (per-worker quota, Add-ons, usage)
Returns the traffic allowance and usage of the cluster for the current monthly period: the included quota (which grows with the average number of workers over the period), Add-ons bought for the period, traffic used so...
GET /v1/k8s/clusters/{id}/billing — Cluster billing
Shows what the cluster costs and has cost: its current price and billing terms, what it spent this calendar month (UTC) and in total, and the wallet entries that belong to it, newest first by default. Entries have a...
GET /v1/k8s/clusters/{id}/delete-preview — Preview before deleting the cluster
Shows what Delete a cluster would remove and refund, without deleting anything: the number of nodes, the data that would be lost, the expected refund of the unused prepaid period and the exact text to send as confirm....
GET /v1/k8s/clusters/{id}/events — Cluster event log
Returns the event log of the cluster, newest first by default: what was ordered, started, scaled, renamed, locked or deleted, when the cluster became ready, and every kubeconfig download. actor tells who caused the...
GET /v1/k8s/clusters/{id}/kubeconfig — Download kubeconfig (cluster-admin)
Downloads the kubeconfig file (YAML) of the cluster. It grants cluster-admin rights: anyone holding the file has full control of the cluster and everything running in it, so treat it like a root password and give the...
GET /v1/k8s/clusters/{id}/networking — Endpoint, IP, open ports
Shows how to reach the cluster: the API server endpoint, the public IP address, and the ports that are open on that address. Port 6443 is the Kubernetes API; ports 80 and 443 reach the cluster's ingress (node ports...
GET /v1/k8s/clusters/{id}/nodes — Cluster nodes (free control + workers)
Lists the nodes that currently make up the cluster: the free control plane node first, then the workers, with their size, status and hourly price. Nodes that were removed are not listed. The list is not paginated.
GET /v1/k8s/clusters/{id}/ops — Cluster operations
Lists the background operations of the cluster (creation, scaling, start, stop, deletion and maintenance), newest first by default. Use it to follow a 202 Accepted call: find the operation by the op.id you received and...
POST /v1/k8s/clusters/{id}/scale — Change worker count (costs money)
Changes the number of workers. The call returns 202 Accepted and an operation adds or removes workers in the background; workers.desired keeps the old number until it finishes. Only a running cluster (state active...
POST /v1/k8s/clusters/{id}/start — Start the cluster
Starts a stopped cluster. The call returns 202 Accepted and an operation starts the nodes in the background; the cluster becomes active and can.kubeconfig turns true when it is running. Workers of an hourly cluster are...
POST /v1/k8s/clusters/{id}/stop — Stop the cluster
Stops a running cluster: the nodes are shut down, workloads stop and the Kubernetes API becomes unreachable until you start the cluster again. The call returns 202 Accepted and an operation stops the nodes in the...
GET /v1/k8s/quote — Quote a cluster + required balance (no charge)
Prices a cluster and checks whether you could create it right now, without creating anything and without charging. The response gives the price per hour and per month, the amount charged up front for a prepaid cycle...
GET /v1/k8s/versions — Kubernetes images (sellable versions)
Lists the Kubernetes versions that can be ordered, one entry per region and version, with the smallest worker size each version accepts. Versions that are disabled, withdrawn or past their end-of-life date are not...
API Reference
Storage
Block Storage
Extra data volumes you can attach to a server. A volume is billed per GB-hour from the moment it is ready until it is deleted, also while it is detached, and keeps its data when detached. Creating and enlarging a volume costs money and, like deleting one, requires an Idempotency-Key. Available only on sites that sell Block Storage; when it is switched off every operation fails with 501 feature_disabled.
GET /v1/vm/{id}/data-volumes — Data volumes attached to the VM
Lists the data volumes attached to one server, with how many more it can take and the total size attached. These are the extra volumes you bought; the system disk of the server is not included. Use List volumes for all...
GET /v1/volumes — List data volumes (paged, sortable)
Lists the data volumes of your account, attached or not, with the limits and the price of the smallest volume. Deleted volumes are not listed.
POST /v1/volumes — Create a data volume (billed per GB-hour)
Creates an empty data volume, and optionally attaches it to one of your servers when it is ready. This operation costs money, but nothing is charged at creation. Billing starts when the volume becomes Ready and runs per...
GET /v1/volumes/quote — Quote a data volume by size
Returns the price of a volume of the given size at your site, per hour and per month, without creating anything and without charging. The price is per GB-hour, so the monthly figure is only an estimate for a volume kept...
GET /v1/volumes/{vid} — Get one data volume
Returns one volume with its state, the server it is attached to, its price and what it has cost so far. Poll this operation after a create, attach, detach, resize or delete call until busy is false; a deleted volume...
DELETE /v1/volumes/{vid} — Delete a data volume (data is lost permanently)
Deletes a volume and destroys its data permanently. If the volume is attached it is detached first. Billing stops when the deletion is done.
POST /v1/volumes/{vid}/attach — Attach a volume to a VM
Attaches a detached volume to one of your servers. The call answers 202 with the background jobid; poll Get a volume until its state is Attached, then format and mount it inside the server. Attaching costs nothing; the...
POST /v1/volumes/{vid}/detach — Detach a volume from its VM (data kept, still billed)
Detaches a volume from its server. The data on the volume is kept and the volume is still billed per GB-hour while detached; delete it to stop the charges. Unmount the volume inside the server first so no data is lost....
POST /v1/volumes/{vid}/resize — Enlarge a data volume (grow only, costs money)
Enlarges a volume. This operation costs money: from the moment the resize is done the volume is billed per GB-hour at the new size. A volume can only grow, never shrink; a new size equal to or below the current one is...
Backups
Backups of a virtual server disk, taken on demand or automatically on a schedule and kept on separate backup storage. Backup is switched on per server. Storage is billed per GB-hour of the space a backup really uses, taken from the wallet balance; deleting a backup stops its charge. If the account falls into debt (a negative wallet balance, or servers locked for lack of funds) its backups are deleted automatically and its schedules are switched off, so keep the balance positive. Restoring a backup overwrites the server disk. Destroying a server also deletes its backups. Operations that change something run in the background and return a job_id (follow it with the VM jobs call). When the site does not sell Backup, every operation fails with 501 feature_disabled.
GET /v1/backup-schedules — VMs with backup enabled and their schedule (paged)
Lists the servers that have Backup switched on, with the automatic schedule (if one is set) and the number of backups kept. A server with Backup on but no schedule has hasschedule false and null schedule fields. Servers...
GET /v1/backups — Backups of all VMs in the account (paged)
Lists the backups of all your servers in one paged list. Each item includes the server it belongs to. Backups that were deleted are not shown. Use vmid to narrow the list to one server, or List the backups of a VM for...
GET /v1/vm/{id}/backup — Backup status of one VM: schedule, kept backups, price
Returns the backup status of one server in a single call: whether Backup is enabled, the automatic schedule, every backup that is kept, the price and what you can do right now. Use meta.cancreate before asking for a new...
POST /v1/vm/{id}/backup/disable — Disable backup (only when no backups remain)
Switches Backup off for the server. All backups of the server must be deleted first (see Delete a backup); otherwise the call fails with backupsexist. Switching it off also stops the schedule. The change runs in the...
POST /v1/vm/{id}/backup/enable — Enable backup for the VM (storage is billed)
Switches Backup on for the server, which is required before any backup or schedule can be created. Switching it on costs nothing by itself; you are billed only for backups that exist, per GB-hour of the space they use....
PUT /v1/vm/{id}/backup/schedule — Set the automatic backup schedule
Sets the automatic backup schedule of the server, replacing the previous one (a server has at most one schedule). The call is synchronous and returns the new schedule. Scheduled backups are billed like manual ones; the...
DELETE /v1/vm/{id}/backup/schedule — Remove the backup schedule (existing backups are kept)
Removes the automatic schedule of the server. Backups that already exist are kept (and keep being billed until you delete them), and Backup stays enabled so you can still create backups by hand. Removing a schedule that...
GET /v1/vm/{id}/backups — Backups of one VM (paged, sortable)
Lists the backups of one server with paging and sorting. Backups that were deleted are not shown. The paging details are in meta (this list has no top-level total, page or perpage). For an overview that also includes...
POST /v1/vm/{id}/backups — Create a backup now (storage is billed)
Creates a backup of the server now. The server must be running and Backup must be enabled. The backup is created in the background: the call returns a jobid immediately and the backup appears in the list with status...
DELETE /v1/vm/{id}/backups/{bid} — Delete one backup
Deletes one backup permanently. It cannot be undone. Billing for the backup stops as soon as the deletion starts. The deletion runs in the background and returns a jobid; a backup that never finished being created is...
POST /v1/vm/{id}/backups/{bid}/restore — Restore the VM from a backup (stops, overwrites the disk, restarts)
Restores the server from a backup, in place. This overwrites the server disk: everything written after the backup was taken is lost. A running server is stopped, its disk is replaced with the contents of the backup and...
Object Storage
S3-compatible object storage. An account owns buckets, buckets hold objects, and access keys let S3 clients (AWS CLI, SDKs, rclone) connect to it. These operations manage accounts, buckets, access keys, usage reports and share links, and can issue short-lived signed URLs for uploading and downloading objects. To move large amounts of data, use the S3 protocol itself with an access key.
Usage is billed pay-as-you-go from your wallet: stored data above the free allowance and downloaded data are charged, uploads are free, and downloads covered by a monthly download quota or bandwidth add-on are not charged. Object storage prices and costs are expressed in Vietnamese dong (VND). The secret of an access key is shown once, when the key is created or rotated, and cannot be retrieved later. Available on the main site only.
GET /v1/s3 — List S3 accounts
Returns the S3 accounts you own, newest first. The list is not paginated. Accounts that are being deleted are not listed. Object storage is available on the main site only. Use the id of an account in every other S3...
POST /v1/s3 — Create an S3 account (usage-billed)
Creates an S3 account in a region and returns its id together with the ID of its first access key. Creating an account is free; you pay for what you store and download (see policy in Get an S3 account), but your wallet...
GET /v1/s3/{id} — Get one S3 account: endpoint, quota, stats
Returns one account with what you need to connect and to understand its cost: the S3 endpoint and region to configure in your client, the region that stores the data, the quota and suspension status of the storage user...
PATCH /v1/s3/{id} — Rename / set the cost alert threshold
Renames the account and/or sets its monthly cost alert. Send only the fields you want to change. When the cost of the usage accumulated in the current month reaches alertthresholdvnd, a notification is created for you...
DELETE /v1/s3/{id} — Delete the S3 account (all buckets must be removed first)
Deletes an S3 account. Every bucket must be deleted first (empty a bucket with the purge-bucket action or by deleting its objects, then delete the bucket); otherwise the call fails. The account is locked and disappears...
GET /v1/s3/{id}/buckets — List buckets
Lists the buckets of the account with their creation time, object count and size. Counts and sizes are statistics reported by the storage service and may lag slightly behind very recent uploads or deletions. To list the...
POST /v1/s3/{id}/buckets — Create a bucket
Creates a bucket. Bucket names are 3 to 63 characters long, use only lowercase letters, digits, hyphens and dots, begin and end with a letter or digit, contain no consecutive dots and must not look like an IP address....
GET /v1/s3/{id}/buckets/{bucket} — List objects in a bucket (paged)
Lists the objects of a bucket one folder level at a time. The listing uses / as delimiter: objects directly under prefix are returned in objects and deeper folders are returned as prefixes. A page holds at most 100...
DELETE /v1/s3/{id}/buckets/{bucket} — Delete a bucket (must be empty)
Deletes an empty bucket. A bucket that still holds objects, including old versions, cannot be deleted and the call fails; to remove a bucket together with everything in it use the purge-bucket action of Run a bucket...
POST /v1/s3/{id}/buckets/{bucket}/action — Bucket and object operations selected by the op field (delete ops also need s3:destroy)
Runs one operation on a bucket or on an object inside it. The operation is chosen with op; the other body fields depend on it (table below). Use it for management tasks and to obtain signed URLs. For bulk transfers...
GET /v1/s3/{id}/keys — List access keys (no secrets)
Lists the access keys of the account. Secrets are never included; they are shown only when a key is created or rotated. The response is not cached. An account can hold up to 10 keys.
POST /v1/s3/{id}/keys — Create an access key (the secret is shown once)
Creates an additional access key and returns it with its secret. The secret appears only in this response (the response is marked Cache-Control: no-store); store it now, because it cannot be retrieved later. If it is...
DELETE /v1/s3/{id}/keys/{key} — Delete an access key (at least one key must remain)
Deletes an access key. Clients that use it stop working immediately. The last remaining key cannot be deleted; create another one first. The account must be active.
POST /v1/s3/{id}/keys/{key}/rotate — Rotate an access key (the new secret is shown once)
Replaces an access key: a new key is created, returned with its secret, and the old key is deleted. The secret appears only in this response (marked Cache-Control: no-store). Use it to obtain a secret for the first key...
GET /v1/s3/{id}/share-links — List object share links (includes the link token)
Lists the share links of the account, newest first, at most 500, including revoked ones (revokedat is set). A share link lets anyone who has it open one object without credentials until the link expires, reaches its...
POST /v1/s3/{id}/share-links — Create an object share link
Creates a share link for one existing object and returns its path. Append url to the base URL of your site to get the full link, for example https://cloud.example.com/s/.... You can protect the link with a password, an...
PATCH /v1/s3/{id}/share-links/{link} — Edit expiry / password / limits of a share link
Changes the protection settings of an active link. Expiry, view limit, referrer list and download flag are replaced as a set: a field you omit goes back to its default (never expires, unlimited views, any referrer...
DELETE /v1/s3/{id}/share-links/{link} — Revoke a share link
Revokes a share link. It stops working immediately and visitors see a not-found page. The entry stays in the list with revokedat set. Revoking a link that is already revoked succeeds. Works in every account state.
GET /v1/s3/{id}/usage — Hourly storage, traffic and cost
Returns the hourly usage records of the account, newest first, with the cost computed for each hour, plus the pricing policy that applies. Each record covers one hour: the bytes stored at the end of the hour, the bytes...
GET /v1/s3/{id}/usage-summary — Daily usage summary for a month
Aggregates the hourly records of one calendar month into days (UTC) and returns the month total. Days with no records are omitted. costvnd counts only hours that are billed, so hours forgiven while your account was...
API Reference
AI
AI Models
Manage the AI Models service: models and prices, AI API keys, usage, request logs and budgets. One AI key (sk-ai-…, created in the console) calls every model through the OpenAI-compatible base URL https://<your-site>/ai/v1 (POST /chat/completions, GET /models, streaming, tools) and the Anthropic-compatible base URL https://<your-site>/ai (POST /v1/messages). Usage is billed per token from your wallet. Creating, rotating and deleting AI keys is only possible from a signed-in console session. Public pricing, no Key required: GET https://<your-site>/ai/v1/models/pricing (USD / 1M Tokens, site current rates).
GET /v1/ai/keys — List AI keys (no secrets)
Lists your AI API keys (never the secrets) with the spend of the current budget period.
PATCH /v1/ai/keys/{id} — Edit an AI key: name, status, models, budgets, RPM/TPM, expiry
Edits an AI key: name, enabled/disabled, allowed models, soft/hard budget and period, RPM/TPM, expiry. Only the fields you send change. The secret cannot be changed here (rotate it in the console).
POST /v1/ai/keys/{id}/reset-spend — Reset the AI Key's current cycle Spend to 0 (Key Budget counter, no refund)
Reset Key Spend in the current Budget cycle to 0 to resume using the Key after reaching its Hard Limit. This is only a Key Budget counter: billed usage still applies, and the account-level Budget remains unchanged. The...
GET /v1/ai/logs — Per-request AI logs (paged, filtered, sorted)
Per-request log of the gateway (metadata only — prompts and responses are never stored), newest first by default. Filter by key, model, status (ok/error), time range or request ID (q).
GET /v1/ai/logs/export — Export AI request logs as CSV
Exports the request log as CSV (same filters as ai log list, at most 50,000 rows, newest first). Limited to 10 exports per minute.
GET /v1/ai/logs/{id} — AI Request details: Tokens, Cost and Cost breakdown, duration, IP, Key
A gateway Request (metadata only — prompt and response are never stored) with caller IP, Key hint, completion time, and Cost breakdown by input / Cache / output (prorated by current unit price; total always matches...
GET /v1/ai/models — AI models on sale, prices per 1M tokens and base URLs
AI models you can call now with their retail prices and the base URLs of the gateway. Pass a model id as model in your requests.
GET /v1/ai/settings — Account AI budgets and limits
Account-wide AI budgets and limits, plus the current period spend and the usage not yet charged to the wallet.
PUT /v1/ai/settings — Set soft/hard budgets, period, alert email, RPM/TPM
Sets the account soft budget (alert), hard limit (blocks every key with 402 when reached), budget period, alert email and account RPM/TPM. Only the fields you send change; null removes a budget or resets RPM/TPM to the...
GET /v1/ai/usage — AI usage by day, model or key
AI usage and spend between from and to, grouped by day, model, key, daymodel, daykey, endpoint or dayendpoint. Days are UTC. summary totals the rows. Groups endpoint and dayendpoint are aggregated from Request Logs...
GET /v1/ai/usage/export — Export AI Usage by day / day × Key / day × Model (CSV or JSON) or Request Logs (CSV)
Download AI Usage between from and to: daily (one row per day), dailykey (day × Key), dailymodel (day × Model) in CSV or JSON format, or requests (Request Logs, CSV only, up to the latest 50,000 rows). Dates in UTC....
GET /v1/public/ai/models — Public AI model price list of the site
Public price list of the AI models sold by the site you call, per 1 million tokens. Works without signing in. available is false while the site does not sell the AI service yet.
API Reference
Other
API
Operations that do not have detailed documentation yet.