REST API · v1.0

API личного кабинета

Управляйте услугами из кода: создавайте юзеров на своих VPN и LTE-серверах, получайте готовые ссылки и подписки, продлевайте серверы. Обычный HTTP и JSON, подойдёт для Telegram-бота или собственного магазина. Ключ равен вашему аккаунту: он видит только ваши серверы, покупки и списания через API невозможны.

Base URL

https://my.h1cloud.net

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

Bearer h1_…

Формат

JSON · UTF-8

Ваши API-ключи

Ключи привязаны к аккаунту. Управлять ими можно, только когда вы вошли на сайте в этом браузере.

Проверяем сессию…

Скопируйте ключ сейчас: позже он не будет показан:

Быстрый старт

Три шага до первого запроса.

Создайте ключ

В блоке «Ваши API-ключи» выше нажмите «Создать ключ» и скопируйте значение h1_….

Передайте его в заголовке

Каждый запрос: с заголовком Authorization: Bearer h1_….

Дёрните любой эндпоинт

Например, получите список серверов:

curl -H "Authorization: Bearer h1_..." \
  https://my.h1cloud.net/api/v1/servers

import requests

BASE = "https://my.h1cloud.net"
KEY  = "h1_..."
r = requests.get(f"{BASE}/api/v1/servers",
                 headers={"Authorization": f"Bearer {KEY}"})
print(r.json())

const BASE = "https://my.h1cloud.net";
const KEY  = "h1_...";
const r = await fetch(`${BASE}/api/v1/servers`, {
  headers: { Authorization: `Bearer ${KEY}` }
});
console.log(await r.json());

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

Ключ передаётся в заголовке Authorization. Альтернатива: заголовок X-API-Key.

Authorization: Bearer h1_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Что можно ключом

Читать аккаунт и серверы, забирать конфиги, смотреть статистику, управлять питанием, перевыпускать конфиг, продлевать сервер с баланса.

Что нельзя

Покупать новые серверы, пополнять/списывать деньги произвольно, заходить в админку и создавать другие ключи. Это доступно только из кабинета под вашей сессией.

Логин по данным биллинга

Чтобы бот не зависел от ручного ключа с сайта, логиньтесь логином/почтой и паролем аккаунта, API вернёт ключ.

POST/api/v1/auth/token

Проверяет данные аккаунта и выдаёт API-ключ. Если на аккаунте включена TOTP-2FA: обязателен code. 2FA по email/Telegram через API не поддержана (в этом случае создайте ключ вручную выше).

Тело запроса (JSON)

Поле	Тип	Описание
login обяз.	string	Логин или e-mail аккаунта
password обяз.	string	Пароль от кабинета
code опц.	string	Код TOTP-2FA, если включена
name опц.	string	Название ключа (для списка)

Пример

curl -X POST https://my.h1cloud.net/api/v1/auth/token \
  -H "Content-Type: application/json" \
  -d '{"login":"my@mail.tld","password":"...","name":"bot"}'

Ответ

{ "ok": true, "key": "h1_xxxxxxxx...", "prefix": "h1_xxxxxxxx" }

Полученный ключ храните как пароль. Лимит: 20 активных ключей на аккаунт.

Формат ответов

Все ответы: JSON. Успех содержит "ok": true, ошибка: "ok": false и error. HTTP-код тоже отражает результат.

Успех

{
  "ok": true,
  "account": { "...": "..." }
}

Ошибка

{
  "ok": false,
  "error": "Требуется авторизация"
}

API панели H1: устройства и несколько локаций

Актуализировано 12.09.2026. Если в вашей панели есть «Лимит устройств» и выбор инбаундов с подключённых панелей, используйте API самой панели H1. Описанные ниже /api/v1/servers/{id}/clients относятся к 3x-ui и имеют другой набор полей.

Адрес: ваш адрес панели + /api. Авторизация: Authorization: Bearer PANEL_API_TOKEN или X-API-Key: PANEL_API_TOKEN. Нужен API-токен этой панели; ключ кабинета h1_… не заменяет его. Токен храните на сервере бота.

Запрос	Назначение
`GET /api/inbounds`	Инбаунды текущей панели и их ID.
`GET /api/clients`	Клиенты текущей панели.
`GET /api/clients/{name}`	Клиент, UUID, срок, лимиты, расход и ссылки подписки.
`POST /api/create`	Создать клиента. Также поддерживается POST /api/clients.
`PATCH /api/clients/{name}`	Изменить только переданные настройки.
`DELETE /api/clients/{name}`	Удалить клиента. Имя в URL кодируйте через encodeURIComponent / URL-encoding.

Поля JSON для создания и изменения

Поле	Тип	Поведение
name	string	Имя при создании. При PATCH имя берётся из URL; для переименования передайте new_name.
uuid	string UUID	При создании можно задать общий UUID для нескольких панелей. Без поля генерируется новый.
days	integer > 0	POST: срок от текущего момента. PATCH: max(текущий срок, сейчас) + days × 86400. Действующие дни сохраняются.
set_days	integer > 0	PATCH: установить срок заново от текущего момента; имеет приоритет над days.
expires_at	integer	Абсолютный Unix timestamp в секундах, в будущем. Имеет приоритет над days и set_days. Передавайте один способ задания срока.
traffic_limit_gb	number ≥ 0	Лимит трафика в ГБ; 0 означает отсутствие лимита. Алиасы: traffic_gb, gb, limit_gb.
device_limit	integer ≥ 0	Лимит устройств; 0 означает отсутствие лимита. Алиасы: devices, device_count, max_devices. Это учёт панели, а не аппаратная идентификация устройства.
inbound_ids	string[]	Локальные ID из GET /api/inbounds. PATCH без поля сохраняет членство; [] убирает клиента из всех пользовательских инбаундов этой панели. Это не удаление самого клиента. Алиас: inbounds.
channels	string[]	Логические каналы main, reality, bs, wscdn. Не являются ID пользовательских инбаундов. PATCH без поля сохраняет каналы.
wg	boolean	Включить/выключить WireGuard при его наличии на панели.
manual	boolean	POST: true для точного выбора inbound_ids/channels. Без него могут примениться настройки панели «Инбаунды для новых клиентов».

Обычный ответ содержит ok и client. В клиенте доступны uuid, expires_at, device_limit, devices_count, traffic_used_gb, traffic_limit_gb, subscription_url и sub_url. Проверяйте HTTP-статус и поле ok: при ошибке есть error. Конфликт имени/UUID при создании возвращает 409.

Один клиент и одна подписка на несколько локаций

Подключите нужные панели в основной панели H1. В интерфейсе это один клиент, технически на локациях создаются записи с одинаковым UUID. Одна подписка объединяет его доступные локации. Самостоятельно склеивать VLESS-ссылки не требуется.

Один массив inbound_ids не принимает ID с разных серверов. Повторите создание на каждой выбранной панели с одним UUID и её локальными inbound_ids. Именно так работает веб-форма. Запросы можно отправить прямо на каждую панель либо через основную: /api/fed/lproxy/{node_id}/create и /api/fed/lproxy/{node_id}/clients/{name}. node_id берите из GET /api/fed/lagg (nodes); это ID подключённой панели, не ID инбаунда.

POST https://YOUR_PANEL/api/create
Authorization: Bearer PANEL_API_TOKEN
Content-Type: application/json

{"name":"tg_12345","uuid":"04b14ac3-ce4c-4e38-a617-01ca2a9fa3c4","days":30,"device_limit":3,"traffic_limit_gb":100,"manual":true,"channels":[],"inbound_ids":["LOCAL_INBOUND_ID"]}

POST https://YOUR_PANEL/api/fed/lproxy/NODE_ID/create
Authorization: Bearer PANEL_API_TOKEN
Content-Type: application/json

{"name":"tg_12345","uuid":"04b14ac3-ce4c-4e38-a617-01ca2a9fa3c4","days":30,"device_limit":3,"traffic_limit_gb":100,"manual":true,"channels":[],"inbound_ids":["REMOTE_INBOUND_ID"]}

UUID в примере замените новым уникальным UUID для каждого покупателя. Проверьте успешный ответ каждой локации, затем получите клиента на основной панели и отдайте общую ссылку sub_url. Подключённые панели должны быть доступны основной панели. Создание на нескольких панелях не является одной атомарной операцией: при частичной ошибке сначала проверьте уже созданные записи по имени/UUID, чтобы безопасно повторить только недостающие.

Продление без изменения инбаундов

PATCH https://YOUR_PANEL/api/clients/tg_12345
Authorization: Bearer PANEL_API_TOKEN
Content-Type: application/json

{"days":30}

Этот запрос добавляет 30 дней и сохраняет inbound_ids, каналы и лимиты. Повторный PATCH с days добавляет дни ещё раз: при неопределённом ответе сначала проверьте expires_at. Для повторяемых запросов задавайте заранее вычисленный expires_at. При настроенной федерации общие изменения передаются репликам; проверяйте итоговый срок на каждой локации.

Важно для 3x-ui: в PATCH /api/v1/servers/{id}/clients/{email} поле days означает новый срок от сейчас, 0 — бессрочно. device_limit и межсерверный inbound_ids в этом API не реализованы; пропуск inbound_ids не меняет текущий инбаунд. Не переносите семантику этого API на панель H1.

Свой бот на 3x-ui: клиенты (юзеры)

Это основной сценарий для реселлера: вы пишете своего бота на нашем API, а он сам заводит VPN-юзеров на вашем 3x-ui сервере и раздаёт им готовые ссылки. В отличие от Remnawave, тут панель: наша, на ноде, поэтому мы управляем клиентами за вас: вам не нужны ни своя панель, ни правка конфигов.

Как это работает

3x-ui-сервер = ваша панель на нашей ноде

Обход (BS) и CDN уже настроены нами при покупке. Вы работаете внутри готового инбаунда и просто добавляете в него юзеров через API.

Юзер = клиент на инбаунде

У каждого свой UUID, лимит трафика (gb) и срок (days). Имя юзера (name): просто метка; если не задать, сгенерим.

Создали → сразу получили рабочую ссылку

Ответ содержит готовую vless-ссылку с обходом и sub-ссылки. Отдаёте их клиенту, работает из коробки в v2rayNG / Hiddify / NekoBox, ничего собирать вручную не надо.

Ведёте юзеров

Смотрите их трафик, продлевайте срок, меняйте лимит, отключайте (бан) и удаляйте. Трафик всех юзеров списывается из общего LTE-пакета сервера.

Полный цикл в боте (пример)

# 1) завести юзера при оплате у вашего клиента
curl -X POST https://my.h1cloud.net/api/v1/servers/123/clients \
  -H "Authorization: Bearer h1_..." -H "Content-Type: application/json" \
  -d '{"name":"vasya","gb":50,"days":30}'
#    -> ответ содержит client.link (vless://...) и client.sub_links: отдаёте клиенту

# 2) показать остаток трафика
curl -H "Authorization: Bearer h1_..." \
  https://my.h1cloud.net/api/v1/servers/123/clients/vasya

# 3) продлить ещё на 30 дней
curl -X PATCH https://my.h1cloud.net/api/v1/servers/123/clients/vasya \
  -H "Authorization: Bearer h1_..." -H "Content-Type: application/json" -d '{"days":30}'

# 4) забанить неплательщика (не удаляя)
curl -X PATCH https://my.h1cloud.net/api/v1/servers/123/clients/vasya \
  -H "Authorization: Bearer h1_..." -H "Content-Type: application/json" -d '{"enable":false}'

# 5) удалить совсем
curl -X DELETE https://my.h1cloud.net/api/v1/servers/123/clients/vasya \
  -H "Authorization: Bearer h1_..."

{id}: id вашего 3x-ui сервера из /servers (у него xui_enabled: true). {email}: это name юзера.

GET/api/v1/servers/{id}/clients

Список юзеров инбаунда с трафиком (up/down), лимитом и сроком.

Пример ответа

{
  "ok": true,
  "inbound_id": 1,
  "count": 2,
  "clients": [
    {
      "email": "vasya",
      "uuid": "0c7ade4b-....",
      "sub_id": "b5a16eda83270cb7",
      "enable": true,
      "total_gb": 5.0,
      "expiry_ms": 1785500000000,
      "up_bytes": 1048576,
      "down_bytes": 5242880
    }
  ]
}

POST/api/v1/servers/{id}/clients

Создать юзера. Возвращает готовую vless-ссылку (с рабочим обходом) и sub-ссылки: отдайте их клиенту.

Тело запроса (JSON)

Поле	Тип	Описание
name опц.	string	Имя юзера (email в панели). Если пусто/занято: сгенерируем.
gb опц.	number	Лимит трафика, ГБ. 0 = без лимита.
days опц.	integer	Срок в днях. 0 = бессрочно.

Пример запроса

curl -X POST https://my.h1cloud.net/api/v1/servers/123/clients \
  -H "Authorization: Bearer h1_..." -H "Content-Type: application/json" \
  -d '{"name":"vasya","gb":50,"days":30}'

Ответ

{
  "ok": true,
  "client": {
    "email": "vasya",
    "uuid": "0c7ade4b-....",
    "sub_id": "b5a16eda83270cb7",
    "link": "vless://0c7ade4b-...@cdn.host:443?...&type=xhttp&...#vasya",
    "sub_links": ["vless://...", "vless://..."],
    "total_gb": 50.0,
    "expiry_days": 30
  }
}

GET/api/v1/servers/{id}/clients/{email}

Один юзер: статус, лимит, срок и израсходованный трафик (up/down в байтах).

PATCH/api/v1/servers/{id}/clients/{email}

Изменить юзера: продлить, поменять лимит трафика, включить/выключить (бан).

Тело запроса (JSON): любое из полей

Поле	Тип	Описание
gb	number	Новый лимит трафика, ГБ (0 = без лимита)
days	integer	Новый срок в днях от текущего момента (0 = бессрочно)
enable	boolean	false: отключить (забанить), true: включить

Пример: забанить юзера

curl -X PATCH https://my.h1cloud.net/api/v1/servers/123/clients/vasya \
  -H "Authorization: Bearer h1_..." -H "Content-Type: application/json" \
  -d '{"enable":false}'

DELETE/api/v1/servers/{id}/clients/{email}

Удалить юзера с инбаунда. Его ссылка перестаёт работать.

GET/api/v1/servers/{id}/inbounds

Список инбаундов панели: id, remark, порт, протокол, сеть, путь и число клиентов.

Топология инбаундов (порты, CDN, маршруты обхода) настроена нами, юзеров вы ведёте внутри готового BS-инбаунда. Нужно больше локаций: берите ещё сервер.

Remnawave (remnanode)

Remnanode-серверы устроены иначе, чем 3x-ui: это xray-нода, а юзеров вставляет Remnawave-панель (по сквадам). Панель ваша, поэтому юзеров вы заводите в ней, а наш API даёт то, что нужно ей на вход: Config Profile.

Забрать конфиг: GET /api/v1/servers/{id}/config вернёт Xray Config Profile (JSON): импортируйте его в свою Remnawave-панель как ноду. Инбаунды идут с clients: []: юзеров добавляет панель.
Создать новый конфиг: POST /api/v1/servers/{id}/config/regenerate сгенерит свежие reality-ключи и вернёт новый профиль в поле profile. Переимпортируйте его, старые ключи перестают действовать.
Юзеры/лимиты/трафик у remnanode: на стороне вашей Remnawave-панели (её API), не через нас. Наши client-эндпоинты (/clients) работают только для 3x-ui.

Забрать профиль

curl -H "Authorization: Bearer h1_..." \
  https://my.h1cloud.net/api/v1/servers/123/config -o profile.json

Серверы и аккаунт

GET/api/v1/me

Данные вашего аккаунта: Telegram-ID, никнейм, баланс и число серверов.

Пример ответа

{
  "ok": true,
  "account": {
    "tgid": 123456789,
    "username": "example_user",
    "balance": 1520.50,
    "servers_total": 3
  }
}

GET/api/v1/servers

Все ваши серверы. Чувствительные поля (пароли панели) не отдаются, за ними идите в /config.

Пример ответа

{
  "ok": true,
  "servers": [
    {
      "id": 123,
      "name": "3x-ui (bs)",
      "tariff_id": "vpn-nl",
      "tariff_name": "Нидерланды",
      "status": "active",
      "days_left": 21,
      "expiration_date": "2026-08-03 12:00:00",
      "cpu": 100, "memory": 512, "disk": 5120,
      "vpn_bs_enabled": true,
      "xui_enabled": true,
      "remnanode_enabled": false
    }
  ]
}

Поле status: active · expired · suspended.

GET/api/v1/servers/{id}

Подробности одного сервера: тот же объект, что и в списке.

Параметры пути

Параметр	Тип	Описание
id обяз.	integer	ID сервера из `/servers`

GET/api/v1/servers/{id}/config

Готовый VPN-конфиг для сервера. Эндпоинт сам определяет тип и возвращает нужное: для 3x-ui: данные панели, для Remnawave (remnanode): Xray Config Profile (JSON), который вы импортируете в свою Remnawave-панель. Идемпотентно.

Нужны привязанный e-mail и никнейм в аккаунте, иначе вернётся 403. Если для сервера ещё не куплен LTE-доступ, придёт 402. Про remnanode: см. раздел Remnawave ниже.

Пример ответа (3x-ui за CDN)

{
  "ok": true,
  "manual_client": true,
  "panel_url": "http://203.0.113.10:25214/aB3xYz9QwErT4uIo",
  "username": "u7Kp2mQx9RtL",
  "password": "eXaMpLePaSsW0rD1",
  "web_path": "aB3xYz9QwErT4uIo",
  "node_address": "203.0.113.10"
}

POST/api/v1/servers/{id}/config/regenerate

Создать свежий конфиг. Для 3x-ui: новый инбаунд (клиенты на старом перестанут работать). Для Remnawave (remnanode): новые reality-ключи и новый Config Profile (в ответе поле profile): импортируйте его в свою Remnawave-панель заново.

Действие необратимо: старые ключи/ссылки перестают действовать. Раздайте/переимпортируйте новый конфиг.

Пример ответа (remnanode)

{
  "ok": true,
  "regenerated": true,
  "kind": "remnanode",
  "profile": { "log": {...}, "inbounds": [ ... ] }
}

GET/api/v1/servers/{id}/stats

Live-статистика из панели: состояние (running/offline), загрузка CPU и RAM, аптайм.

POST/api/v1/servers/{id}/power

Управление питанием сервера.

Тело запроса (JSON)

Поле	Тип	Значения
action обяз.	string	start · stop · restart

Пример

curl -X POST https://my.h1cloud.net/api/v1/servers/123/power \
  -H "Authorization: Bearer h1_..." \
  -H "Content-Type: application/json" \
  -d '{"action":"restart"}'

POST/api/v1/servers/{id}/xray-update

Поменять версию ядра Xray сервера: то же самое, что кнопка «Поменять версию Xray (обход)» в кабинете. Версия ядра сервера должна совпадать с версией ядра Xray клиентского приложения (Happ), иначе туннель подключается, но трафик не идёт. Тело запроса: {"version": "26.6.27"}, {"version": "26.7.28"} или {"version": "26.7.11"}; без тела ставится 26.6.27.

Сервер жёстко перезапустится и будет недоступен 2–3 минуты: после этого переподключитесь по ссылке обхода. Не вызывайте в цикле: одного вызова достаточно, частые рестарты только продлят даунтайм.

Пример

curl -X POST https://my.h1cloud.net/api/v1/servers/123/xray-update \
  -H "Authorization: Bearer h1_..." \
  -H "Content-Type: application/json" \
  -d '{"version":"26.6.27"}'

Возможные ошибки: 503: сервер не запущен (подождите ~30 секунд), 409: на сервере нет блока пина ядра (напишите в поддержку), 502: не удалось прочитать/записать файлы сервера.

POST/api/v1/servers/{id}/renew

Продлить сервер на 30 дней списанием с баланса. Другие способы оплаты через API недоступны: если баланса не хватает, вернётся ошибка 400, деньги не списываются.

Пример ответа

{
  "ok": true,
  "message": "Сервер продлён на 30 дней",
  "balance": 1220.50,
  "server": { "id": 123, "days_left": 51, "...": "..." }
}

Коды ошибок

При ошибке HTTP-статус отражает причину, а тело содержит error с человекочитаемым текстом.

Код	Значение
401	Ключ отсутствует, недействителен или отозван
402	Для действия нужен купленный LTE-доступ на сервере
403	Не выполнены требования аккаунта (привяжите e-mail и никнейм)
404	Сервер не найден или не принадлежит вам
400	Некорректный запрос (например, не хватает баланса на продление)
502 / 503	Панель/нода временно недоступна: повторите позже

Безопасность

Ключ = доступ к вашим серверам. Храните его как пароль, не публикуйте в коде/репозиториях.
Полное значение ключа показывается один раз: при создании. Потеряли: создайте новый и отзовите старый.
Скомпрометирован? Нажмите «Отозвать» в блоке ключей: он мгновенно перестанет работать.
До 20 активных ключей на аккаунт. Заведите отдельный ключ под каждый скрипт/сервис.
Ключом нельзя тратить деньги произвольно и заходить в админку, доступно только чтение и управление вашими серверами.

Полезное

Готовый конфиг и веб-панель сервера: в личном кабинете, раздел «Мои серверы».
Управление ключами и этот гайд: на /api-docs (также кнопка «API-доступ» в разделе «Аккаунт» кабинета).

H1Cloud API · v1.0 · Вопросы и лимиты: через поддержку в кабинете.