Справочник API

CheapServ API — небольшой JSON API для задач, которые вы автоматизируете: получение списка тарифов и локаций, заказ серверов с баланса, чтение данных о ваших серверах, создание и отслеживание пополнений. Это тот же интерфейс, которым пользуется панель управления, и никаких дополнительных функций за ним не скрыто.

Базовый URL

https://cheapserv.com/v1

Формат

Тела запросов и ответы в формате JSON, UTF-8

Аутентификация

Authorization: Bearer cs_…

Лимит запросов

120 запросов в минуту на ключ

Аутентификация

Создайте ключ в разделе Аккаунт → API. Полный ключ с префиксом cs_ показывается один раз; сохраните его в менеджере секретов. Передавайте его в каждом запросе, требующем аутентификации, в заголовке Authorization:

curl https://cheapserv.com/v1/account \
  -H "Authorization: Bearer cs_0038063…"

Ключ обладает всеми правами аккаунта. Если ключ утёк, немедленно отзовите его в панели управления; отзыв действует начиная со следующего запроса. Методы GET /v1/plans и GET /v1/locations публичные и не требуют ключа.

Лимиты запросов

Каждый ключ может делать 120 запросов в минуту. Каждый ответ содержит заголовки X-RateLimit-Limit и X-RateLimit-Remaining; когда лимит исчерпан, API отвечает статусом 429 и кодом ошибки rate_limited. Опрашивайте пополнение не чаще чем раз в 10 секунд — состояние меняется только по подтверждениям в сети.

Ошибки

Ошибки возвращаются в виде JSON-объекта со стабильным кодом и сообщением, понятным человеку:

{"error":{"code":"validation","message":"The hostname is invalid."}}

GET /v1/plans

Публичный метод. Возвращает все тарифы, сгруппированные по продуктам, с актуальным наличием. При заказе используйте slug.

curl https://cheapserv.com/v1/plans

{
  "vps": [
    {"slug":"vps-4","name":"VPS-4","monthly_usd":6.99,"stock":"in_stock",
     "specs":{"vcpu":"4","ram":"8 GB","nvme":"160 GB","traffic":"12 TB"}},
    {"slug":"hf-2","name":"HF-2","monthly_usd":12.39,"stock":"low",
     "specs":{"cores":"2","ram":"8 GB","nvme":"120 GB","traffic":"8 TB"}}
  ],
  "dedicated": [ {"slug":"ds-9950x","name":"DS-9950X","monthly_usd":239, "stock":"in_stock","specs":{"cpu":"AMD Ryzen 9 9950X", "ram":"192 GB","storage":"2× 4 TB NVMe Gen4","net":"1 Gbps unmetered"}} ],
  "gpu": [ {"slug":"h100-sxm","name":"H100 SXM","monthly_usd":979,"stock":"in_stock","specs":{"vram":"80 GB HBM3","vcpu":"32","ram":"256 GB","nvme":"2 TB","net":"10 Gbps"}} ],
  "rdp": [ {"slug":"rdp-4","name":"RDP-4","monthly_usd":15.19,"stock":"in_stock","specs":{"vcpu":"4","ram":"8 GB","nvme":"160 GB","os":"Windows Server 2022/2025"}} ]
}

stock принимает одно из значений: in_stock, low (осталось четыре единицы или меньше) или sold_out. Заказ распроданного тарифа завершается ошибкой validation. Группа VPS включает все три линейки; значения slug, начинающиеся с hf-, относятся к высокочастотным тарифам, а начинающиеся с st- — к тарифам для хранения данных.

GET /v1/locations

Публичный метод. Возвращает шесть площадок и продукты, которые может размещать каждая из них. Доступность тарифов определяется списком продуктов: vps_hf и vps_storage указываются отдельно от vps.

curl https://cheapserv.com/v1/locations

[
  {"code":"fra","city":"Frankfurt","country":"DE","hub":true,
   "products":["vps","vps_hf","vps_storage","dedicated","gpu","rdp"]},
  {"code":"hel","city":"Helsinki","country":"FI","hub":false,
   "products":["vps","vps_hf","vps_storage","dedicated","rdp"]}
]

GET /v1/account

curl https://cheapserv.com/v1/account \
  -H "Authorization: Bearer $CS_KEY"

{"email":"[email protected]","balance_usd":142.50,"created_at":"2026-09-05T14:40:12Z"}

GET /v1/servers

Возвращает ваши серверы, сначала новые. Каждый объект сервера содержит адреса, назначенные при развёртывании, и дату следующего продления.

curl https://cheapserv.com/v1/servers \
  -H "Authorization: Bearer $CS_KEY"

[
  {"id":1041,"hostname":"web-01","product":"vps","plan":"vps-4","plan_name":"VPS-4",
   "location":"ams","image":"debian-13-12","ipv4":"198.51.100.86","ipv6":"2001:db8:2:411::1",
   "status":"active","rescue":false,"backups":false,"monthly_usd":6.99,
   "renews_at":"2026-10-05 14:41:03","created_at":"2026-09-05 14:41:03"}
]

status принимает одно из значений: provisioning (около 60 секунд после оплаты), active, stopped, rebooting, reinstalling, starting, stopping, suspended или cancelled.

POST /v1/servers

Создаёт заказ и оплачивает его с предоплаченного баланса. Если баланса хватает на стоимость тарифа, серверы создаются сразу и начинается развёртывание; они выходят в онлайн примерно за 60 секунд. Если баланса не хватает, ничего не создаётся, а API отвечает статусом 402 и указывает недостающую сумму — сначала пополните баланс, затем отправьте заказ повторно.

curl -X POST https://cheapserv.com/v1/servers \
  -H "Authorization: Bearer $CS_KEY" \
  -H "Content-Type: application/json" \
  -d '{"product":"vps","plan":"vps-4","location":"fra",
       "image":"ubuntu-24-04-22-04","hostname":"web-01","qty":1}'

HTTP/2 201
{"order_id":1041,"paid":true,
 "servers":[
   {"id":1041,"hostname":"web-01","product":"vps","plan":"vps-4","plan_name":"VPS-4",
    "location":"fra","image":"ubuntu-24-04-22-04","ipv4":"198.51.100.49","ipv6":"2001:db8:1:411::1",
    "status":"provisioning","rescue":false,"backups":false,"monthly_usd":6.99,
    "renews_at":"2026-10-05 14:41:03","created_at":"2026-09-05 14:41:03"}
 ]}

Если баланса не хватает:

HTTP/2 402
{"error":{"code":"insufficient_balance","message":"Your balance does not cover this order. Top up first."},
 "balance_usd":4.20,"total_usd":6.99,"missing_usd":2.79,
 "topup_url":"https://cheapserv.com/account/topup"}

Тариф, который не предлагается в выбранной локации, распроданный тариф или недопустимое имя хоста приводят к ответу 400 validation. Если qty больше 1, для каждой машины возвращается отдельный объект сервера, а к именам хостов добавляются суффиксы -1, -2 и так далее.

Значения slug

Slug тарифа — это название тарифа строчными буквами, в котором пробелы заменены дефисами, а символ × — на x: vps-4, hf-2, st-1, ds-9950x, rtx-5090, h100-sxm, 8x-h100-sxm, rdp-4, rdp-gpu. Slug образа — это название и версия образа строчными буквами, в которых каждая группа подряд идущих символов, не являющихся буквами или цифрами, заменена дефисом: ubuntu-24-04-22-04, debian-13-12, rocky-linux-10-9, windows-server-2022-2025.

GET /v1/topups

Возвращает ваши пополнения, сначала новые, в виде объектов пополнения (см. ниже).

curl https://cheapserv.com/v1/topups \
  -H "Authorization: Bearer $CS_KEY"

POST /v1/topups

Создаёт пополнение и возвращает реквизиты депозита: уникальный адрес, точную сумму в криптовалюте и срок действия 30 минут. Суммы указываются в USD, от $25 до $5,000. Коды монет: BTC, ETH, XMR, USDTTRC (Tether в сети TRC-20) и USDT (Tether в сети ERC-20). Если создать второе пополнение с той же монетой и суммой, пока первый адрес ещё действует, вместо нового адреса вернётся уже существующий.

curl -X POST https://cheapserv.com/v1/topups \
  -H "Authorization: Bearer $CS_KEY" \
  -H "Content-Type: application/json" \
  -d '{"amount_usd":50,"coin":"USDTTRC"}'

HTTP/2 201
{"ref":"cs-k7m2qp4xh9b1zt3v6nwd","amount_usd":50,"bonus_usd":0,"coin":"USDTTRC","status":"pending",
 "deposit_address":"TX3…","deposit_amount":"50.01","deposit_network":"TRX","deposit_tag":null,
 "received":null,"missing":null,"txid":null,
 "expires_at":"2026-09-05 15:11:03","paid_at":null,"created_at":"2026-09-05 14:41:03",
 "url":"https://cheapserv.com/account/topup/cs-k7m2qp4xh9b1zt3v6nwd"}

Отправьте ровно deposit_amount в монете coin на адрес deposit_address в сети deposit_network до момента expires_at. Сумма меньше $25 или больше $5,000 либо неподдерживаемая монета приводят к ответу 400 validation; слишком много адресов, открытых за короткое время, — к ответу 429 rate_limited; если платёжная сеть не отвечает, возвращается 503 orchestrator_down, и ничего не создаётся.

GET /v1/topups/{ref}

Возвращает одно пополнение и обновляет его статус по данным платёжной сети. status принимает одно из значений: pending (ожидается депозит), confirming, underpaid (тогда в received и missing указаны суммы в криптовалюте; отправьте missing на тот же адрес), completed (баланс пополнен), expired, cancelled или error. Истёкшее пополнение возобновить нельзя: вместо этого создайте новое.

curl https://cheapserv.com/v1/topups/cs-k7m2qp4xh9b1zt3v6nwd \
  -H "Authorization: Bearer $CS_KEY"

{"ref":"cs-k7m2qp4xh9b1zt3v6nwd","amount_usd":50,"bonus_usd":0,"coin":"USDTTRC","status":"completed",
 "deposit_address":"TX3…","deposit_amount":"50.01","deposit_network":"TRX","deposit_tag":null,
 "received":null,"missing":null,"txid":"7c1e…",
 "expires_at":"2026-09-05 15:11:03","paid_at":"2026-09-05 14:52:40","created_at":"2026-09-05 14:41:03",
 "url":"https://cheapserv.com/account/topup/cs-k7m2qp4xh9b1zt3v6nwd"}

Пример: пополнить баланс, дождаться зачисления и сделать заказ

#!/bin/sh
set -e
API=https://cheapserv.com/v1
ref=$(curl -sf -X POST "$API/topups" \
  -H "Authorization: Bearer $CS_KEY" -H "Content-Type: application/json" \
  -d '{"amount_usd":50,"coin":"USDTTRC"}' | jq -r .ref)
echo "top-up $ref — send the deposit shown at $API/topups/$ref"
while :; do
  st=$(curl -sf "$API/topups/$ref" -H "Authorization: Bearer $CS_KEY" | jq -r .status)
  [ "$st" = completed ] && break
  [ "$st" = expired ] && { echo expired; exit 1; }
  sleep 10
done
curl -sf -X POST "$API/servers" \
  -H "Authorization: Bearer $CS_KEY" -H "Content-Type: application/json" \
  -d '{"product":"vps","plan":"hf-2","location":"nyc","hostname":"db-01"}' | jq '.servers[]'

Версионирование

Версия задаётся префиксом пути /v1. В пределах одной версии поля в ответы только добавляются и никогда не удаляются и не переименовываются; игнорируйте поля, которые вам неизвестны. Изменения, нарушающие обратную совместимость, будут выходить как /v2, причём обе версии будут работать параллельно не менее шести месяцев; об этом объявят на странице статуса и по e-mail всем владельцам аккаунтов, у которых есть API-ключ.

Чего-то не хватает или на странице есть ошибка? Сообщите нам: Открыть тикет.