Developer API

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.

Quick start

• Create a key in the cabinet: Settings → API (/my/api). The key is shown once.
• Call GET /me: the cheapest way to validate the key and see its scopes and limits.
• Then read authentication, errors and the servers walkthrough.

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). Creation is confirmed with a TOTP code or the password; the secret is shown once. Keys are independent of cabinet sessions: password changes, "log out everywhere" and 2FA changes do not touch them; a ban revokes all keys. 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

Presets in the cabinet are just bundles of scopes; you can adjust the checkboxes 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) without giving every key the power to destroy the whole integration. 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:

If test keys are switched off on the VDSok side, every request answers 403 sandbox_disabled.

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. VDSok staff can raise the limits of a specific key; the effective ceiling and what is left of it come back in the X-RateLimit-Limit and X-RateLimit-Remaining headers of every response, and a specific key’s settings are in GET /keys/{id}. Reads in the cabinet do not count against the API.

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;
• POST /servers, 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: otherwise a retry would get idempotency_in_progress forever. That 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: 0.1 + 0.2 is not 0.3 in binary arithmetic, and in billing that error becomes a discrepancy on an invoice.

• 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: running or at least not stopped by billing; stopped: powered off by the client; suspended: switched off for non-payment or by staff; 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 (locked by staff, 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 staff locked the domain 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 is written to disabled_reason as text) and send 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 (the Node package generates its types straight from it). 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 iterators (for server in client.servers.list() walks every 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 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.