VPS API

The API lets you order, manage and renew VPS from your own code: a reseller panel, a bot, a script. It also shows the balance and the transaction history. Domains, DNS and protection rules are not managed through the API, only in the panel. Access needs a token.

#Basics

• Base URL: https://turtleguard.cloud/api/v1.
• Header on every request: Authorization: Bearer crp_....
• Request and response bodies are JSON. Ordering a server and every other action answer 200.
• Money is an integer in the minor units of the currency next to it: cents for dollars.
• Times are RFC 3339 strings, ids are UUIDs.
• Every response has an X-Request-Id header. Include it when you contact support about a specific request.

curl -s -H "Authorization: Bearer $TOKEN" https://turtleguard.cloud/api/v1/cloud/vms

To check a token, call GET /auth/me: the answer holds the account, "auth": "token" and the token's permissions in scopes.

#OpenAPI description

Every method, field and response is described in https://turtleguard.cloud/api/v1/openapi.json (OpenAPI 3.1, no token needed). Import it into Postman or Insomnia, or generate a client for your language from it. Where this page and the file disagree, the file is right.

#What a token can reach

• Every /cloud/… method on this page.
• GET /billing/balance and GET /billing/transactions.
• GET /auth/me and GET /openapi.json.

Any other address answers a token with 403 and the code auth.token_area. Topping up the balance, changing the account password, creating or revoking tokens is not possible through the API: that is done in the cabinet.

Each method needs one of three permissions: cloud:read to see servers, cloud:write to order and change them, billing:read to see the balance and transactions. Plans and images (GET /cloud/plans, GET /cloud/cloud-images) are served without a token too.

#Limits

Over the limit the API answers 429 with the code rate_limited and a Retry-After header: the number of seconds to wait before retrying. Each token has its own limits.

#Errors

{"error": {"code": "billing.insufficient_funds", "message": "..."}}

code is stable across versions, so parse the answer by it. message is an English hint. A data error adds field with the field name. A body that is not valid JSON for the method gets a plain-text answer with 400, 415 or 422.

A busy server (cloud.vm_busy) is being created, reinstalled, moved or deleted. Wait until the status changes and retry.

#Plans and images

• You can order in locations with "available": true. The location code is the code field, for example de.
• A plan's price per period is price_monthly. If a location has its own price, it is in country_prices under the location code. traffic_gb: null means unmetered traffic.
• Prices in unit_prices are in millionths of the currency per month, together with the bounds min_cpu…max_disk_gb.

#Ordering a server

curl -s -X POST -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"plan_id": "6f1c2b9e-4d1a-4c47-9b52-1f0e7a3d8c21", "region": "de", "os_key": "ubuntu-24.04",
       "hostname": "client-42", "root_password": "q7-Lm2vX9rTp", "idempotency_key": "order-1042"}' \
  https://turtleguard.cloud/api/v1/cloud/vms

The answer holds vm_id, hostname, the assigned address ip, the amount charged price with currency, and duplicate. The server shows up at once with status creating and turns running when ready. If it cannot be created, the money goes back to the balance.

Ordering needs a confirmed account email. A short balance gives 402; no capacity in the location or no free address gives 409 with cloud.no_capacity or cloud.ip_pool_empty.

#Retrying without a double charge

If the answer to an order is lost (the connection dropped, a timeout hit), repeat the same request with the same idempotency_key. No second server is created: the API returns the first order with "duplicate": true. Any non-empty key works and is scoped to your account; your own order number is a good choice. Without a key every request is a new order and a new charge.

#Server list and details

The key fields of vm: status, the addresses public_ipv4 and ipv6, expires_at (paid until), auto_renew, price_monthly, and the period's traffic traffic_in and traffic_out in bytes. The root password is in root_password: the last one set, or an empty string when unknown.

#Power and deletion

The request waits for the action to finish and returns the new status: {"ok": true, "action": "reboot", "status": "running"}. A server suspended for non-payment cannot be started (402): renew it first. One stopped for abuse cannot either (403).

#Reinstall

Body: os_key and root_password are required, ssh_key is optional. The reinstall runs in the background; meanwhile the status is reinstalling. For apps and game servers os_key is ignored: the container is recreated from the same image and the app is installed again with its current settings.

#Password and SSH keys

The password and keys are written through cloud-init. On a running server the password is also changed through the guest agent, in the background.

#Changing the IP

• The change is paid; the price is shown in the panel on the server page. The money is debited from the balance, and the amount comes back in charged. A short balance gives 402.
• A running server is restarted to pick up the new address.
• Changes on one server need at least 60 seconds between them, otherwise 409 cloud.ip_change_cooldown.
• The number of changes in the last 24 hours is limited, separately per server (cloud.ip_change_vm_daily) and for the whole account (cloud.ip_change_user_daily).
• The answer holds the old address old_ip and the new ip. A non-empty apply_error means the address is assigned but could not be applied on the node right away; we retry on our own.

#Changing the plan or size

On a plan change the surcharge covers all the prepaid time, not just the current month: price difference × days left ÷ days in the period. A started day counts as a whole one. If the server is renewed several periods ahead, you pay for all of them. Each option from /upgrades shows the amount in advance in charge_now, along with days_left and period_days. Moving to a smaller plan is not possible.

A custom size is priced by the per-core, memory and disk prices of the server's location. If it costs more than before, the price difference for a period is charged at once; if it costs less, nothing is charged or refunded and the new price applies from the next renewal. The disk can only grow.

Either way a running server is restarted ("restarting": true in the answer). A short balance gives 402. Marketplace app servers cannot be changed this way.

#Renewal

• A renewal is tied to the current expiry date: repeating the same request does not charge again but returns "duplicate": true and "charged": 0. The new date is in expires_at.
• A server suspended for non-payment starts again on its own after renewal.
• With auto-renew the money is debited from the balance on the expiry day.
• If the balance is short on that day, the server is powered off and gets the status suspended. Top up within the grace period and it is renewed and started on its own; otherwise it is deleted.

#Snapshots

Taking and deleting run in the background, so the list is not updated at once. With max snapshots already there, no new one is taken: 409 cloud.snapshot_limit. POST /cloud/vms/{id}/snapshot is the same as POST …/snapshots.

#Rescue mode

Use it when the system does not boot. The server restarts and boots from the rescue image while your disk stays attached, so you can mount and repair it. Calling the method again restores the normal boot, and the server restarts again.

#Console

With the pass, open the websocket wss://turtleguard.cloud/api/v1/vnc/{token} (subprotocol binary), for example with noVNC, and enter password. The pass works once. Do not add an Authorization header to this connection: the pass is already in the address, and with a token the address answers 403.

#Load graphs

Each point has time in Unix seconds and the values cpu, mem, maxmem, disk, maxdisk, netin, netout (network in bytes per second).

#Name and comment

Fields: name up to 64 characters, comment up to 200, avatar a #rrggbb colour or a data:image/... picture up to 400,000 bytes. An empty string clears a field; fields you leave out stay as they are. In the server data they show up as display_name, comment and avatar.

#Balance and transactions

A transaction has the amount amount (debits are negative), the balance after it balance_after, the type kind (for example cloud_vm for a server order, renewal or plan change, cloud_ip for an IP change, topup for a top-up), a description and ref_id, the server it belongs to. The balance cannot be topped up through the API, only in the cabinet.

#For resellers

The usual flow when you sell our VPS to your own customers:

1. Check the balance: GET /billing/balance. Orders and renewals are paid from it.
2. Get plans, locations and images: GET /cloud/plans and GET /cloud/cloud-images.
3. Order the server: POST /cloud/vms with idempotency_key set to the order number in your system. On a network error, retry with the same key.
4. Poll GET /cloud/vms/{vm_id} until status is running.
5. Give the customer the address from public_ipv4 and the root password: the one you set when ordering, also in root_password.
6. Tag the server: PATCH /cloud/vms/{id}/profile with the customer's name in name and a contract number or contact in comment. The panel shows the name instead of the hostname, and the comment is in the server data through the API.
7. Watch the term via expires_at: renew with POST /cloud/vms/{id}/renew when the customer has paid, or turn on auto-renew and keep a reserve on the balance.

This needs a Manage VPS token. A storefront that only shows customers the state of their servers can do with a Read only token.