Developer API

Five minutes from nothing to your first API response. All you need is a VDSok account and a terminal.

1. Get a key

Keys are issued by the account owner in the cabinet: Settings → API (/my/api). You pick the mode (live or test), the set of scopes and, if you want, an IP allow-list. The secret is shown once — nobody can show it again, you would have to issue a new key.

Start with a test key (vk_test_…): it talks to the same base URL and reads your real data, but performs no writes for real — see Sandbox.

2. First request

GET /me is the cheapest way to prove the key works. Samples in four languages are right below this section.

Look at three things in the answer: key.mode (live or test), scopes — what this key is allowed to do, and the X-Request-ID header, worth quoting in any support request. What is left of your rate limit arrives in X-RateLimit-Remaining.

3. First write, for free

A test key can walk the whole ordering path without spending anything: the balance does not move, no VM is created, no payment gateway is called. Every such answer carries X-Sandbox: true, and the server you get has a fake id from 9000000000 that lives for 24 hours.

BASE=https://vdsok.guru/api/v1
KEY=vk_test_XXXXXXXXXXXXXXXXXXXXXXXX

# order: returns the order invoice_id and the server_id to come
curl -sS -X POST $BASE/servers \
  -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"tariff_id": 12, "os": "ubuntu-22.04", "months": 1}'

# how the order is going — by the invoice_id above, not by server_id
curl -sS $BASE/orders/4242 -H "Authorization: Bearer $KEY"

# clean up: deletion is simulated too
curl -sS -X DELETE $BASE/servers/9000000001 \
  -H "Authorization: Bearer $KEY" -H "Idempotency-Key: $(uuidgen)"

Once the same thing works with a live key, the only difference is the key prefix and the missing X-Sandbox header.

Where to go next

• Authentication, scopes and presets — what to actually allow a key.
• Errors: envelope and codes — every working client starts by handling these.
• Servers: full walkthrough — order, status, power, renewal, delete with refund.
• SDKs — if you would rather not write HTTP by hand.
• Glossary — if "quote" is unfamiliar, or the difference between an order and an invoice is unclear.

The VDSok Client API is a REST interface over HTTPS with JSON bodies. It covers everything a client can do in the cabinet except tickets, dedicated servers, sub-accounts and profile editing: balance and invoices, the VDS catalog, servers (order, renew, power, reinstall, IPs, PTR, SSH keys, delete with refund), domains, API keys and webhooks.

Base URL

Every path in this guide is relative to:

https://vdsok.guru/api/v1

The version lives in the path. Breaking changes will go to /v2; v1 only grows additively: new fields and endpoints may appear at any time, so ignore unknown fields in responses.

Conventions

• JSON only. A POST/PUT/PATCH body that is not application/json is rejected with 415; a body over 64 KB with 413.
• Timestamps are RFC 3339 in UTC with a trailing Z: 2026-09-15T10:00:00Z.
• Money is a decimal string with 2–4 fraction digits, never a float, always next to a currency field (ISO 4217).
• server_id is the panel id of the VM, the same number the cabinet shows in the URL.
• Every response carries X-Request-ID; quote it in support requests.

If this is your first visit, start with the quick start: a key, a first request and a free ordering loop in the sandbox.

Every request carries Authorization: Bearer <key>. A key starts with vk_live_ (live) or vk_test_ (test, see Sandbox).

Keys are created by the account owner in the cabinet (/my/api): a name, live/test mode, a set of scopes, an optional IP/CIDR allow-list and a validity window (not_before/expires_at). The secret is shown once. A key is independent of cabinet sessions and stays valid until it expires or is revoked. Keys cannot be created through the API, only listed (GET /keys) and the calling key can be revoked.

Scopes

Every operation lists its required scopes in x-scopes of the specification; an empty list means "any valid key" (catalog, /me). Only GET /health (always 200 with status: ok | disabled — it is an availability probe, not a protected endpoint) and GET /openapi.json need no key at all. A missing scope → 403 insufficient_scope with details.required naming what is missing.

Presets

A preset is a ready-made bundle of scopes; you can adjust it after picking one.

Kill switch

DELETE /keys/{key_id} revokes only the key that makes the request, whatever its scopes. A leaked key can be killed from anywhere — CI, a server. Other keys are revoked in the cabinet. Works for test keys too.

A test key (vk_test_…) is created in the same cabinet as a live one and talks to the same base URL: there is no separate staging host.

What a test key does:

• Moves no money: ordering, renewing, topping up, paying an invoice and deleting return a plausible response, but the balance does not change, no VM or domain is created and no payment gateway is called.
• Ordering a server returns a fake server with id >= 9000000000. It lives 24 hours and shows up in GET /servers for that key only; status, power, reinstall, IPs and delete can be called on it and are simulated too.
• Every response to a test key carries the X-Sandbox: true header. Assert on it in your tests so the modes never get mixed up.
• Idempotency, rate limits and validation errors behave as in live: 402, 409 and 429 can happen in the sandbox as well.

The behaviour of each operation under a test key is described by x-sandbox in the specification:

The words you will meet in API answers and further down this guide.

The API has exactly one error shape, for every status including app-level 404/405/413/500:

{
  "error": {
    "code": "insufficient_funds",
    "message": "Balance 4.10 USD is below the required 5.90 USD",
    "request_id": "9f1c2a9d-4b7e-4a21-8d3f-0c6e5b2a1d44",
    "details": {"required": "5.90", "balance": "4.10", "shortfall": "1.80", "currency": "USD"}
  }
}

• code: a machine code from the closed list below. Branch on it, not on message.
• message: human-readable English, not for parsing; wording may change.
• request_id: the same value as the X-Request-ID header; quote it to support.
• details: code-specific extras: required (scopes), fields (per-field validation errors), money figures for insufficient_funds, status for service_state.

The list is closed per status, but a client should still tolerate unknown codes and handle them by HTTP status, so adding a code never breaks an integration.

What to retry: 429, 502, 503, 504 are safe to retry for GET and for mutations sent with an Idempotency-Key. Do not blindly retry other mutations.

The default is 120 requests per minute per key plus a separate bucket of 20 per minute for expensive calls. Limits are per key (not per account, not per IP) over a fixed 60-second window. The ceiling and what is left of it come back in the X-RateLimit-Limit and X-RateLimit-Remaining headers of every response; the limits of a specific key are in GET /keys/{key_id}. If the standard ceiling is not enough, ask support.

Expensive calls are marked x-expensive: true in the specification:

• GET /servers/{server_id}/status and GET /servers/{server_id}?include=live: a live query to the panel;
• GET /domains/availability: a registrar lookup;
• GET /catalog/quote;
• GET /servers/{server_id}/ips, GET /servers/{server_id}/ips/quote;
• POST /servers, POST /servers/{server_id}/renew, POST /servers/{server_id}/ips, POST /balance/topup;
• GET /invoices/{invoice_id}/pdf;
• POST /webhooks/{webhook_id}/test, POST /webhooks/deliveries/{delivery_id}/redeliver.

Separately, POST /servers/{server_id}/actions/reset-password is limited to 5 calls per 5 minutes per server. Requests with an invalid key are limited to 30 per minute per IP, against brute force.

Headers

On 429 rate_limited the details carry bucket (normal/expensive) and limit. The right reaction is to sleep for Retry-After and retry, not to hammer in a loop: the window is fixed and will not open earlier.

Lists that can grow large (/servers, /invoices, /transactions, /orders, /domains, /webhooks/{id}/deliveries) return a page and a cursor:

{"data": [ … ], "next_cursor": "eyJpZCI6MjAwMSwic2lnIjoi…"}

• limit: 1 to 100, default 50.
• next_cursor: pass it back as ?cursor= to get the next page; null means this was the last one.
• Cursors are opaque and signed: never build or parse them by hand. A tampered cursor answers 400 invalid_cursor. A cursor is bound to its filters: change status and start again from the first page.
• Order is fixed: newest first. Items added while you iterate may land at the front, but there are no duplicates or gaps within one walk.

Short reference lists (/catalog/*, /servers/{id}/ips, /ssh-keys, /keys, /webhooks) return {"data": [...]} in full, without a cursor.

Operations that move money or touch external systems are marked x-idempotent: true and require an Idempotency-Key header: POST /balance/topup, POST /invoices/{id}/pay, POST /servers, DELETE /servers/{id}, POST /servers/{id}/renew, POST /servers/{id}/ips, POST /domains, POST /domains/{id}/renew, POST /domains/transfers.

The key is any string of 16..128 characters, unique per logical operation; a UUID v4 is fine. Generate it before the first attempt and reuse it on retries: that is the whole point. The key is remembered for 7 days together with a digest of the endpoint and the body:

The outcome is always recorded, 5xx responses included, which is why a retry never charges twice. A server order that hit a panel timeout (202 provisioning) replays the same 202 with the same invoice_id on retry; poll GET /orders/{invoice_id} from there.

Money

Every amount is a string like "5.90", "0.0083", "-12.00" (pattern ^-?[0-9]+\.[0-9]{2,4}$), always next to currency, the ISO 4217 code of the account currency (e.g. USD). Floats are never used in JSON.

• Parse amounts into a decimal type: Decimal in Python, BigInt in minor units or decimal.js in Node, bcmath/BigDecimal in PHP.
• In request bodies (amount on top-up) send a string with two fraction digits: "25.00". The number 25 is accepted as well, 25.005 is not.
• Hourly prices (price_hourly) have up to 4 fraction digits: "0.0083".
• Transactions carry an absolute amount and a separate direction (credit/debit); a signed Money appears only in adjustments.

Dates

Every point in time is RFC 3339 in UTC with a trailing Z: 2026-09-15T10:00:00Z. Fields that can be empty (next_due_at, expires_at, paid_at) come as null, never as an empty string or 0000-00-00.

• In requests (since/until on /transactions) send RFC 3339 with Z or an offset as well.
• X-RateLimit-Reset and X-Webhook-Timestamp are unix seconds, not milliseconds.
• Refunds on deletion are computed by whole days of the unused period (days_left in RefundQuote); compare your own figures in days, not seconds.

Below is the life cycle of one VDS from the catalog to deletion. It is exactly what the cabinet does, with the same checks and prices. server_id is always the panel id of the VM (id in /servers responses).

Server statuses (status): active: the service is active; stopped: powered off by the client; suspended: the service is suspended, usually for non-payment; pending_cancel: a cancel request at end of period is approved; cancelled: deleted by the client or by a cancel request; terminated: removed after prolonged non-payment. The flags flags.blocked (the server is locked, every mutation → 403 server_blocked), flags.expired and flags.is_test tell what can still be done.

While an order, a deletion or an IP change is running on a server, a parallel mutation of the same object answers 409 operation_in_progress: wait and retry.

Domains are registered with the contact data of the account profile, the same as the cabinet uses; it cannot be changed through the API. Statuses (status): pending: the registrar accepted the request and the domain becomes active on the next sync; active; expired; transfer_pending; cancelled. blocked: true means the domain is locked and mutations answer 403 domain_blocked. locked is the transfer lock at the registrar.

Every money operation on domains (POST /domains, /domains/{id}/renew, /domains/transfers) requires Idempotency-Key and the domains:order scope; reads need domains:read; nameservers, privacy and auto-renew need domains:manage.

Every service is paid from the account balance in its currency (currency). Top-ups go through a payment gateway by link; the API takes no cards and stores no payment details. Ordering, renewing and buying IPs charge the balance synchronously, so check GET /balance or GET /catalog/quote → balance_sufficient first.

A webhook is a POST from VDSok to your https:// URL when something happens in the account. Subscriptions are created only with a live key that has the webhooks:manage scope; a test key gets 403 sandbox_not_supported on every /webhooks* endpoint. The URL must be on a public address; redirects are not followed.

Event catalogue

The current list with descriptions comes from GET /webhooks/events.

Envelope

{
  "id": "evt_01J7ZK3Q9X4R",
  "type": "server.suspended",
  "created_at": "2026-09-15T10:00:00Z",
  "livemode": true,
  "account_id": 57,
  "api_version": "1",
  "data": {
    "object": {"id": 2001, "name": "web-01", "status": "suspended", "...": "full Server object"},
    "previous": {"status": "active"}
  },
  "resource": "/api/v1/servers/2001"
}

data.object is the full snapshot in the same shape the REST API returns; data.previous holds the fields that changed or null; resource is the API path of the object. The envelope is serialized once when the event is queued: retries and redeliveries send the identical bytes, so id and created_at never change. X-Webhook-Timestamp is the time of that particular attempt, so the signature is recomputed for every attempt: deduplicate on X-Webhook-Id, never on the signature.

Delivery headers

Delivery and retries

Answer any 2xx within 10 seconds; the response body is ignored. Process events asynchronously: accept, enqueue on your side, answer 200. Otherwise the delivery is retried after 60 s, 5 min, 15 min, 1 h and 6 h and marked dead after the 6th failure. 20 failures in a row auto-disable the subscription (the reason lands in disabled_reason), and the account owner gets an e-mail; re-enable it with PATCH /webhooks/{id} and {"active": true}. The log keeps delivered rows for 14 days and dead ones for 30.

The official SDKs cover all of v1 and follow the same specification as this site. Common to all three:

• constructor (apiKey, {baseUrl, timeout = 30 s, maxRetries = 2}); headers Authorization, Accept, User-Agent: vdsok-sdk-<lang>/<ver>;
• automatic retries on 429/502/503/504 honouring Retry-After, only for GET and for mutations sent with an Idempotency-Key; on money endpoints the SDK generates the idempotency key itself and hands it back to the caller;
• a single ApiError {status, code, message, requestId, details} and RateLimitInfo parsed from the headers. In PHP the machine-readable code is errorCode, not code: \Exception already owns an inherited $code (the HTTP status) that cannot be redeclared;
• pagination: every page is walked by client.servers.list_all() in Python, for await (… of await client.servers.list()) in Node and $client->servers->iterate() in PHP; list() returns a single page;
• Webhooks.verify(secret, headers, rawBody, tolerance = 300) and construct_event(), the signature check from the webhooks section;
• groups account, balance, invoices, catalog, servers, domains, ssh_keys, keys, webhooks; money as strings/Decimal, dates as native types.

SDK 1.x versions track API v1; breaking API changes ship only together with /v2 and a new SDK major. Sources and issue trackers live on GitHub under the VDSok organization (sdk-node, sdk-python, sdk-php).

API changes are documented here and in the info.version field of the specification. Within v1 everything is added compatibly: new fields, new endpoints, new error codes and webhook events. A client must ignore unknown fields and handle unknown codes by HTTP status.

1.0.0 — 2026-09-15

• First public release of Client API v1: /me, account, balance and transactions, top-up, invoices (list, PDF, pay from balance, payment link), catalog (tariffs, OS images, locations, zones, quote), servers (order, status, power, reinstall, password reset, renew, delete with refund, notes and auto-renew), orders, additional IPs and PTR, SSH keys, domains (availability, registration, renewal, nameservers, privacy, transfer), API keys (view and kill switch), webhooks (subscriptions, log, redeliver, test).
• vk_live_/vk_test_ keys, scopes and presets, IP allow-lists, validity windows.
• Idempotency on money operations, cursor pagination, 120/20 per-minute limits.
• Sandbox: test keys read real data and simulate writes.
• 14 webhook event types with HMAC-SHA256 signatures and retries.
• SDKs: @vdsok/sdk (Node), vdsok (Python), vdsok/sdk (PHP).

The full list of v1 operations — the same as in the interactive reference, but as one table and without JavaScript.

Columns: Scope — what the key must carry (a dash means any valid key will do); Idem — whether Idempotency-Key is required; Expensive — whether the call draws from the separate rate-limit bucket; Sandbox — behaviour under a test key (real — as in live, fake — simulated without writing, forbidden — 403).

Meta

Account

Invoices

Catalog

Servers

Server actions

Orders

IPs

SSH keys

Domains

Keys

Webhooks

The machine-readable description of the API is an OpenAPI 3.1 document, the same one this site and the SDKs are built from. It is available without a key:

• Download openapi.json: a cacheable copy; the live document is served by GET /api/v1/openapi.json.
• Interactive reference: every operation, schema, request and response example, with the option to run a request with your own key right from the browser.

The document uses these extensions: x-scopes (required scopes), x-idempotent (Idempotency-Key needed), x-expensive (counted in the 20/min bucket), x-sandbox (real | fake | forbidden: behaviour under a test key). You can generate a client for any language from it (openapi-typescript, openapi-generator, oapi-codegen) or import it into Postman/Insomnia.

What to include in a report

Every API answer carries an X-Request-ID header. With it we find your request in the logs in seconds. So please send:

• the request_id from X-Request-ID (it is in the error body too);
• the method and path: POST /servers/2001/renew, not "renewal is broken";
• the time in UTC, to the minute at least;
• the key id from GET /keys and its mode (live or test). Never send the key itself — if it ends up in a message, revoke it with DELETE /keys/{key_id} and issue a new one.

Where to write

• A cabinet ticket is the main route: your account, services and history are all visible there.
• Email: support@vdsok.guru.
• Contacts and working hours: the contacts page.

API availability

There is no public status page. The availability probe is GET /health: it answers 200 without a key and says whether the API is switched on (status: ok | disabled). It is a probe, not a protected endpoint — handy for telling whether the silence is ours or yours.

A bug in an SDK or in these docs

• The SDKs live on GitHub: sdk-node, sdk-python, sdk-php — open an issue there.
• Something wrong on this page: a ticket or an email, with the section anchor (#idempotency, for example).