Документация

API Hostix

Один HTTP-интерфейс для всего, что умеет кабинет: покупка серверов, продление, доступы, установка ПО, SSH-ключи и события через вебхуки. Ответы — JSON в UTF-8, суммы в рублях, время — Unix-секунды UTC.

Что умеет API

• смотреть каталог, локации, системы и цены без авторизации;
• покупать серверы с баланса аккаунта и продлевать их;
• включать, выключать и перезагружать VPS, переустанавливать систему, менять IP;
• получать доступы, менять root-пароль, включать и выключать вход по паролю;
• ставить готовые скрипты на чистую ОС и следить за ходом установки;
• управлять SSH-ключами аккаунта;
• читать историю операций и счета;
• получать события на свой адрес вебхуком.

Базовый адрес: https://hostix-vps.cc/api/v1

Ключи и доступ

Ключ создаётся в кабинете (раздел «Партнёрка и API») или в боте — кнопка «API» в главном меню. Ключ всегда виден в кабинете и в боте — храните его как пароль, а если он утёк, удалите и выпустите новый.

Authorization: Bearer hx_ваш_ключ

Область	Что можно
read	Только чтение: аккаунт, серверы, метрики, история, счета.
full	Всё то же плюс покупка, продление, действия с VPS, установка ПО, SSH-ключи, вебхуки. Выдаётся участникам партнёрской программы.

Партнёрская скидка

Участникам партнёрской программы заказы через API считаются со скидкой: базовый процент задаётся в настройках сервиса, отдельному партнёру можно поставить свой. В кабинете и в боте цена обычная — скидка действует только на запросы с ключом.

Скидка уже учтена в поле price ответа POST /quotes: заказ подтверждается именно этой суммой. Текущий процент виден в GET /partner.

{
  "status": "active",
  "active": true,
  "pct": 10.0,
  "base_pct": 10.0,
  "personal": false,
  "api_url": "https://hostix-vps.cc/api/v1",
  "docs_url": "https://hostix-vps.cc/api"
}

Заявку на партнёрство оставляют из кабинета или бота: POST /partner с полем note — пара предложений о проекте.

Ошибки и лимиты

Ошибка всегда приходит в поле error с понятным текстом.

{ "error": "Недостаточно средств. Пополните баланс и повторите заказ." }

Код	Значение
400	Неверные данные запроса
401	Нужен ключ или он недействителен
403	Ключу не хватает прав
404	Объект не найден
409	Действие сейчас невозможно: занят заказ, изменилась цена, не хватает денег
429	Слишком много запросов
503	Временный сбой, повторите позже

Лимит — 360 запросов в минуту на адрес. Отдельные ограничения: покупка и платные действия — 20 в час, установка ПО — 10 в час, создание вебхуков — 10 в час.

Каталог и цены

Открыто без авторизации. Тарифы, локации, системы и сроки оплаты.

curl https://hostix-vps.cc/api/v1/tariffs

{
  "currency": "RUB",
  "tariffs": [
    { "id": "nl:0", "idx": 0, "location": "nl", "name": "nl-1",
      "cpu": 1, "ram_gb": 1, "disk_gb": 10, "channel": "200 Мбит/с",
      "price_month": 270.0, "prices": { "1m": 270.0, "3m": 770.0, "6m": 1460.0, "1y": 2760.0 } }
  ],
  "locations": [ { "code": "nl", "name": "Нидерланды", "channel": "25 Гбит/с" } ],
  "periods": [ { "code": "1m", "title": "1 месяц", "days": 30, "discount": 0 } ],
  "systems": [ { "code": "ubuntu2404", "name": "Ubuntu 24.04 LTS", "family": "ubuntu" } ]
}

Способы оплаты, лимиты пополнения и контакты. Тоже без авторизации.

Аккаунт и баланс

{ "name": "Денис", "email": "you@example.com", "balance": 2480.0,
  "total_spent": 15300.0, "servers": 3, "is_admin": false }

Баланс пополняется в кабинете или в боте: платёжные страницы по API не создаются.

Покупка сервера

Покупка идёт в два шага: расчёт и подтверждение. Расчёт живёт 10 минут и фиксирует цену — в том числе партнёрскую скидку.

curl -X POST https://hostix-vps.cc/api/v1/quotes \
  -H "Authorization: Bearer $HOSTIX_KEY" \
  -H "Content-Type: application/json" \
  -d '{"location":"nl","idx":2,"period":"1m","os":"ubuntu2404","name":"web-01"}'

{ "id": "0f3c…", "price": 891.0, "cpu": 2, "ram": 4, "disk": 40,
  "note": "скидка партнёра 10%", "expires": 1790000000 }

curl -X POST https://hostix-vps.cc/api/v1/operations \
  -H "Authorization: Bearer $HOSTIX_KEY" \
  -H "Idempotency-Key: 7c1f0b8e5a394d2b9f6c" \
  -H "Content-Type: application/json" \
  -d '{"kind":"purchase","quote_id":"0f3c…","confirm":true}'

Ответ — операция со статусом. Опрашивайте её, пока статус не станет окончательным.

{ "id": "…", "kind": "purchase", "status": "success",
  "server_id": 128, "message": "Сервер готов." }

Статус	Значение
pending / running	В работе, продолжайте опрашивать
success	Готово
failed	Не получилось, деньги возвращены
uncertain	Результат проверяет поддержка. Повторять запрос не нужно

Серверы

В карточке — ресурсы, IP, система, срок оплаты, цена продления, доступные действия, состояние SSH-ключей и входа по паролю.

Логин и текущий root-пароль.

Периоды: hour, day, week, month. Память и диск — в байтах, скорость — байты в секунду, CPU — проценты. Пропуски в сборе остаются пропусками (null), нулями их не подменяем.

Действия и продление

Все действия отправляются в POST /operations полем kind.

kind	Что делает	Поля
renew	Продлить на 30 дней	server_id, expected_price
upgrade	Поднять тариф без переустановки	server_id, idx, expected_price
start / stop / reboot	Питание	server_id
reinstall	Переустановить систему	server_id, os, name_confirmation
change-ip	Сменить IP	server_id, expected_price
password_login	Вход по паролю вкл/выкл	server_id, enabled
delete	Удалить сервер	server_id, name_confirmation
vnc	Ссылка на консоль	server_id

expected_price защищает от изменения цены: если она успела поменяться, операция отклоняется, а не списывает больше. Переустановка и удаление требуют name_confirmation с точным именем сервера.

Меняет root-пароль без переустановки системы. Пустое поле password — сгенерируем сами.

Установка ПО

Доступные скрипты, что уже установлено и ход текущей установки.

{ "script_id": 2 }

Некоторые скрипты задают вопросы — они перечислены в поле fields скрипта в ответе GET. Ответы передаются в params, например для Remnawave Node:

{
  "script_id": 4,
  "params": {
    "NODE_DOMAIN": "node.example.com",
    "PANEL_IP": "203.0.113.10",
    "SECRET_KEY": "eyJub2RlQ2VydFBlbSI6…"
  }
}

Ответы хранятся зашифрованными только до конца установки, ключи вырезаются из журнала.

Ставится только на чистую систему и только один раз: чтобы поставить другое, переустановите ОС. Реквизиты доступа попадают в файл /root/hostix_secrets.txt на самом сервере и один раз приходят в Telegram-бота. В API и в базе Hostix они не хранятся.

SSH-ключи

{ "public_key": "ssh-ed25519 AAAAC3Nza… you@laptop", "name": "ci-runner" }

Ключи сами встают на все Linux-серверы аккаунта, включая новые и переустановленные. Удаление — {"delete": 12}, переименование — {"rename": 12, "name": "…"}.

История и платежи

Движения по балансу с понятными названиями («Продление VM услуги #128») и счета на пополнение.

Вебхуки

Добавьте адрес в кабинете или через API — и события о ваших серверах поедут к вам. Отправляем POST с телом JSON, ждём ответ 2xx в течение 10 секунд. Неудачные попытки повторяем через 1, 5, 30 минут и 2 часа.

{ "url": "https://example.com/hostix", "events": "server.ready,server.expiring" }

Пустое поле events — присылать все. В ответ приходит секрет подписи: он показывается один раз.

Каждый запрос подписан: заголовок X-Hostix-Signature — это HMAC-SHA256 от тела запроса вашим секретом. Проверяйте подпись до того, как доверять содержимому.

# Python: проверка подписи
import hashlib, hmac

def valid(body: bytes, signature: str, secret: str) -> bool:
    expected = hmac.new(secret.encode(), body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, signature)

Тело события:

{
  "event": "server.ready",
  "created": 1790000000,
  "data": { "server_id": 128, "name": "web-01", "ip": "203.0.113.10",
            "status": "active", "location": "nl", "os": "ubuntu2404",
            "cpu": 2, "ram_gb": 4, "disk_gb": 40,
            "expires_at": "2026-10-18T09:21:00+00:00" }
}

Список событий

Событие	Когда приходит
server.ready	сервер выдан и готов к работе
server.renewed	сервер продлён
server.expiring	срок заканчивается (по умолчанию за 72 часа)
server.expired	срок закончился
server.suspended	сервер приостановлен
server.deleted	сервер удалён
server.failed	заказ не выдан, деньги вернулись на баланс
install.finished	установка ПО завершена
payment.paid	баланс пополнен
system.notice	системное уведомление и тестовое событие

Примеры

curl

export HOSTIX_KEY=hx_ваш_ключ

# список серверов
curl -H "Authorization: Bearer $HOSTIX_KEY" https://hostix-vps.cc/api/v1/servers

# продлить сервер 128 на месяц
curl -X POST https://hostix-vps.cc/api/v1/operations \
  -H "Authorization: Bearer $HOSTIX_KEY" \
  -H "Idempotency-Key: $(openssl rand -hex 10)" \
  -H "Content-Type: application/json" \
  -d '{"kind":"renew","server_id":128,"expected_price":990,"confirm":true}'

Python

import os, time, uuid, requests

API = "https://hostix-vps.cc/api/v1"
HEAD = {"Authorization": f"Bearer {os.environ['HOSTIX_KEY']}"}

def buy(location="nl", idx=2, period="1m", os_name="ubuntu2404", name="web-01"):
    quote = requests.post(f"{API}/quotes", headers=HEAD, json={
        "location": location, "idx": idx, "period": period, "os": os_name, "name": name,
    }).json()
    op = requests.post(f"{API}/operations", headers={**HEAD, "Idempotency-Key": uuid.uuid4().hex},
                       json={"kind": "purchase", "quote_id": quote["id"], "confirm": True}).json()
    while op["status"] in ("pending", "running"):
        time.sleep(2)
        op = requests.get(f"{API}/operations/{op['id']}", headers=HEAD).json()
    if op["status"] != "success":
        raise RuntimeError(op.get("message", "покупка не удалась"))
    return requests.get(f"{API}/servers/{op['server_id']}", headers=HEAD).json()

server = buy()
print(server["ip"], server["os_name"])

Node.js

const API = 'https://hostix-vps.cc/api/v1';
const head = { Authorization: `Bearer ${process.env.HOSTIX_KEY}`, 'Content-Type': 'application/json' };

async function call(path, options = {}) {
  const response = await fetch(API + path, { ...options, headers: { ...head, ...options.headers } });
  const data = await response.json();
  if (!response.ok) throw new Error(data.error);
  return data;
}

const servers = await call('/servers');
console.log(servers.servers.map(s => `${s.name} ${s.ip}`));

Готовые сценарии

Купить сервер и поставить на него панель

# 1. расчёт и покупка (см. пример на Python выше)
# 2. дождаться, пока сервер станет active, и поставить ПО
curl -X POST https://hostix-vps.cc/api/v1/servers/128/software \
  -H "Authorization: Bearer $HOSTIX_KEY" \
  -H "Content-Type: application/json" \
  -d '{"script_id": 2}'

# 3. следить за ходом установки
curl -H "Authorization: Bearer $HOSTIX_KEY" \
  https://hostix-vps.cc/api/v1/servers/128/software

Автопродление на своей стороне

# подпишитесь на server.expiring вебхуком и продлевайте по событию
{"kind":"renew","server_id":128,"expected_price":990,"confirm":true}

Ключ доступа на новый сервер

curl -X POST https://hostix-vps.cc/api/v1/ssh-keys \
  -H "Authorization: Bearer $HOSTIX_KEY" \
  -H "Content-Type: application/json" \
  -d '{"public_key":"ssh-ed25519 AAAAC3Nza… ci","name":"ci-runner"}'

Ключ встанет на все серверы аккаунта, включая те, что вы купите позже.