Документация/Подключение/Своя панель/Вызовы·6 / 9
Вызовы
Тело и ответ — JSON, кроме QR-кода: он в SVG или PNG. Имя в адресе кодируется, как в encodeURIComponent, вместо имени можно id клиента. Нажмите на вызов — откроются параметры, тело, ответ и готовая команда. Адрес и токен удобно держать в переменных:
VELI=https://panel.example.com/Zq7mT2xP4vLc9wRbE5nK/api
VELI_TOKEN=veli_…Токен, схема, MCP3
GET/meЭтот токен: название, права, срок, версия APIлюбой
application/json{
"name": "cabinet",
"token": true,
"rights": "clients",
"until": 0,
"api": 1
}Ошибки
401 token- Токена нет, он отозван или истёк. Есть ли он ещё, покажет veli token list на сервере панели
403 rights- У токена нет таких прав: например, удалять клиентов может только «Всё». Права покажет GET me
429 wait- Больше 300 запросов в минуту по токену или десять неверных токенов с этого адреса за 15 минут. Подождите столько секунд, сколько в Retry-After
500 db- Панель не смогла записать изменения — повторите, с тем же ключом
curl -s "$VELI/me" \
-H "Authorization: Bearer $VELI_TOKEN"GET/openapi.jsonСхема всего API, OpenAPI 3.1чтение
application/json{
"openapi": "3.1.0",
"info": { "title": "Veli panel API", "version": "1.12.0" },
"paths": {
"/clients": {
"get": {},
"post": {}
},
"…": {}
}
}Ошибки
401 token- Токена нет, он отозван или истёк. Есть ли он ещё, покажет veli token list на сервере панели
403 rights- У токена нет таких прав: например, удалять клиентов может только «Всё». Права покажет GET me
429 wait- Больше 300 запросов в минуту по токену или десять неверных токенов с этого адреса за 15 минут. Подождите столько секунд, сколько в Retry-After
500 db- Панель не смогла записать изменения — повторите, с тем же ключом
curl -s "$VELI/openapi.json" \
-H "Authorization: Bearer $VELI_TOKEN"POST/mcpПанель для ИИ-агента по MCPлюбой
application/json{
"jsonrpc": "2.0",
"id": 1,
"method": "tools/call",
"params": {
"name": "clients_list",
"arguments": { "status": "soon" }
}
}application/json{
"jsonrpc": "2.0",
"id": 1,
"result": {
"content": [
{ "type": "text", "text": "{\"clients\": [ … ], \"total\": 6}" }
]
}
}Ошибки
401 token- Токена нет, он отозван или истёк. Есть ли он ещё, покажет veli token list на сервере панели
403 rights- У токена нет таких прав: например, удалять клиентов может только «Всё». Права покажет GET me
429 wait- Больше 300 запросов в минуту по токену или десять неверных токенов с этого адреса за 15 минут. Подождите столько секунд, сколько в Retry-After
500 db- Панель не смогла записать изменения — повторите, с тем же ключом
curl -s "$VELI/mcp" \
-H "Authorization: Bearer $VELI_TOKEN" \
-H "content-type: application/json" \
-d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"clients_list","arguments":{"status":"soon"}}}'Клиенты12
GET/clientsКлиенты: фильтры, порядок, страницычтение
Параметры
externalв запросе- Внешний ID — только клиенты с ним; «:» в адресе — %3A
tagв запросе- Метка — только клиенты с ней
statusв запросе- Статусы через запятую: on, soon, limit, off, paused, waiting
groupв запросе- Группа; пустое значение — клиенты без группы
qв запросе- Слово в имени, заметке, контакте или внешнем ID, без учёта регистра
until_beforeв запросе- Конец срока раньше этого, unix-время; бессрочные не попадают
until_afterв запросе- Конец срока позже этого, unix-время; бессрочные не попадают
changed_sinceв запросе- Изменён вручную или системой с этого времени — для сверки со своей базой
devicesв запросе- none — устройств нет, some — есть, full — все места заняты
used_overв запросе- Потрачено не меньше этой доли лимита, %; клиенты без лимита не попадают
seen_beforeв запросе- Приложение не брало подписку с этого времени — или не брало ни разу
sortв запросе- name, until, added, used или changed; «-» впереди — наоборот
limitв запросе- Клиентов на странице, 1–1000; без него — все сразу
cursorв запросе- next прошлой страницы
application/json{
"at": 1793754000,
"clients": [
{
"id": "c_Ab3dE5fG7hJ9",
"name": "order-88123",
"changed": 1793750460,
"seen": 1793753400,
"note": "",
"contact": "@anna",
"until": 1796342400,
"devices": 3,
"held": 2,
"veli": 1,
"speed": 0,
"added": 1793750400,
"bytes": 1288490188,
"status": "on",
"group": "",
"limit": 0,
"reset": "never",
"used": 0,
"next": 0,
"external": "88123",
"tags": ["paid", "month"],
"wait": 0,
"first": 1793750520,
"left": { "days": 30, "bytes": null }
}
],
"total": 412,
"next": "eyJrIjoxNzk0MDAwMDAwfQ"
}Поля клиента
id- c_ и 12 знаков — навсегда: переименование его не меняет. Работает в пути вместо имени: clients/c_Ab3dE5fG7hJ9. Храните у себя его, а не имя
name- Имя, 1–40 знаков, у каждого клиента своё; вида c_ и 12 знаков нельзя — так выглядят id
external- Внешний ID — ваш ID клиента; пусто — нет. Он не уникален: один человек может купить две подписки, поэтому поиск отдаёт список
tags- Метки
status- on, soon, limit, off, paused или waiting — выше
until- Конец срока, unix-время; 0 — бессрочно или срок ещё ждёт первого подключения
wait, first- Сколько секунд срока начнутся с первого подключения (0 — не ждёт); когда приложение впервые взяло подписку (0 — ещё не было)
left- Остаток: days и bytes; null — без срока и без лимита
devices, held, veli- Сколько устройств можно, сколько занято всеми приложениями, из них — Veli
speed- Скорость Veli в каждую сторону, Мбит/с; 0 — без ограничения
limit, reset, used, next- Лимит трафика в байтах (0 — без лимита), сброс — never, day, week или month по UTC, потрачено за период, начало следующего
group- Группа; пусто — без группы
bytes- Трафик за всё время
seen, changed- Последний запрос подписки приложением (с точностью до 10 минут, 0 — не было); последнее изменение — вручную или системой
note, contact, added- Заметка, контакт, когда добавлен
Ошибки
401 token- Токена нет, он отозван или истёк. Есть ли он ещё, покажет veli token list на сервере панели
403 rights- У токена нет таких прав: например, удалять клиентов может только «Всё». Права покажет GET me
429 wait- Больше 300 запросов в минуту по токену или десять неверных токенов с этого адреса за 15 минут. Подождите столько секунд, сколько в Retry-After
500 db- Панель не смогла записать изменения — повторите, с тем же ключом
curl -s "$VELI/clients?status=on,soon&sort=-until&limit=100" \
-H "Authorization: Bearer $VELI_TOKEN"POST/clients/findКлиент по ссылке или устройству; ссылку в ответе токен «Только чтение» не видитчтение
application/json{ "link": "https://panel.example.com/s/kV0pX7wQ2mLr9sTb" }application/json{
"at": 1793754000,
"id": "c_Ab3dE5fG7hJ9",
"name": "order-88123",
"changed": 1793750460,
"seen": 1793753400,
"note": "",
"contact": "@anna",
"until": 1796342400,
"devices": 3,
"held": 2,
"veli": 1,
"speed": 0,
"added": 1793750400,
"bytes": 1288490188,
"status": "on",
"group": "",
"limit": 0,
"reset": "never",
"used": 0,
"next": 0,
"external": "88123",
"tags": ["paid", "month"],
"wait": 0,
"first": 1793750520,
"left": { "days": 30, "bytes": null },
"disabled": false,
"link": "https://panel.example.com/s/kV0pX7wQ2mLr9sTb",
"list": [
{
"id": "vk_3fA9c2…",
"kind": "veli",
"os": "Android",
"added": 1793750520,
"bytes": 1073741824
},
{
"id": "a1b2c3d4e5f6",
"kind": "app",
"os": "iOS",
"added": 1793751000
}
],
"lines": [
{
"node": "de-1",
"kind": "Reality",
"line": "vless://…@203.0.113.10:8443?security=reality…#de-1 · Reality"
}
],
"meta": { "order": "88123" },
"page": "https://panel.example.com/s/kV0pX7wQ2mLr9sTb",
"apps": {
"Happ": "happ://add/https://panel.example.com/s/kV0pX7wQ2mLr9sTb",
"v2rayNG": "v2rayng://install-sub?url=…",
"Hiddify": "hiddify://import/…",
"…": "…",
"Veli": "veli://add/https://panel.example.com/s/kV0pX7wQ2mLr9sTb"
}
}Поля клиента
id- c_ и 12 знаков — навсегда: переименование его не меняет. Работает в пути вместо имени: clients/c_Ab3dE5fG7hJ9. Храните у себя его, а не имя
name- Имя, 1–40 знаков, у каждого клиента своё; вида c_ и 12 знаков нельзя — так выглядят id
external- Внешний ID — ваш ID клиента; пусто — нет. Он не уникален: один человек может купить две подписки, поэтому поиск отдаёт список
tags- Метки
status- on, soon, limit, off, paused или waiting — выше
until- Конец срока, unix-время; 0 — бессрочно или срок ещё ждёт первого подключения
wait, first- Сколько секунд срока начнутся с первого подключения (0 — не ждёт); когда приложение впервые взяло подписку (0 — ещё не было)
left- Остаток: days и bytes; null — без срока и без лимита
devices, held, veli- Сколько устройств можно, сколько занято всеми приложениями, из них — Veli
speed- Скорость Veli в каждую сторону, Мбит/с; 0 — без ограничения
limit, reset, used, next- Лимит трафика в байтах (0 — без лимита), сброс — never, day, week или month по UTC, потрачено за период, начало следующего
group- Группа; пусто — без группы
bytes- Трафик за всё время
seen, changed- Последний запрос подписки приложением (с точностью до 10 минут, 0 — не было); последнее изменение — вручную или системой
note, contact, added- Заметка, контакт, когда добавлен
at- Когда собран ответ, unix-время
link- Ссылка подписки — секрет: её отдают только самому клиенту
page- Страница подписки для браузера, с кнопками приложений
apps- Ссылки «Добавить в …» по приложениям
list- Устройства: id, kind — veli (ключ Veli) или app (HWID другого приложения), os, added; у Veli ещё bytes
lines- Строки обычных протоколов по узлам: node, kind, line
meta- Поля вашей системы
disabled- true — клиент отключён
Ошибки
404 none- Запрошено то, чего нет, или неизвестный вызов
401 token- Токена нет, он отозван или истёк. Есть ли он ещё, покажет veli token list на сервере панели
403 rights- У токена нет таких прав: например, удалять клиентов может только «Всё». Права покажет GET me
429 wait- Больше 300 запросов в минуту по токену или десять неверных токенов с этого адреса за 15 минут. Подождите столько секунд, сколько в Retry-After
500 db- Панель не смогла записать изменения — повторите, с тем же ключом
curl -s "$VELI/clients/find" \
-H "Authorization: Bearer $VELI_TOKEN" \
-H "content-type: application/json" \
-d '{"link":"https://panel.example.com/s/kV0pX7wQ2mLr9sTb"}'POST/clientsДобавить клиентаклиенты
application/json{
"name": "order-88123",
"days": 30,
"change": {
"devices": 3,
"external": "88123",
"tags": ["paid", "month"],
"meta": { "order": "88123", "source": "shop" }
}
}Поля change — каждое по желанию
days- Продлить на столько дней: от конца срока, у истёкшего — от сейчас; меньше нуля — укоротить. У ждущего первого подключения — ждать дольше или короче. У нового клиента дни стоят рядом с change, null — бессрочно. ±1–36500
until- Конец срока ровно, unix-время; 0 — бессрочно. Не вместе с days. В прошлом — срок кончается сейчас
start- first_use — срок пойдёт с первого запроса подписки приложением; now — ждущий начинает срок сейчас
name- Новое имя — только одному клиенту; id, ссылка, устройства и трафик остаются
disabled- true — отключить: ссылка не открывается, устройства сняты с узлов, срок идёт; false — включить
relink- true — новая ссылка: старая перестаёт работать, аккаунты обычных протоколов новые, устройства Veli остаются
devices- Сколько устройств можно, 1–100
speed- Мбит/с, 0–100000; 0 — без ограничения
limit, reset, zero- Лимит трафика в байтах, сброс, true — начать счёт с нуля
group- Группа по названию; пусто — без группы
external- Внешний ID, до 128 знаков; пусто — убрать
tags- Метки — весь список заново: до 20, каждая до 32 знаков
tags_add, tags_remove- Добавить и убрать метки, остальные остаются — удобно для многих сразу
meta- Поля вашей системы — все заново: до 20; ключ — латиница, цифры, _ . -, до 40 знаков; значение до 500
note, contact- Заметка до 300 знаков, контакт до 100
Слишком длинное значение не обрезается, а даёт ошибку bad с полем и пределом — {"error": "bad", "field": "change.devices", "max": 100}: иначе ваша система не узнала бы, что сохранилось не то. Новый клиент приходит в ответе целиком, вместе со ссылкой.
application/json{
"done": 1,
"client": {
"at": 1793754000,
"id": "c_Ab3dE5fG7hJ9",
"name": "order-88123",
"changed": 1793750460,
"seen": 1793753400,
"note": "",
"contact": "@anna",
"until": 1796342400,
"devices": 3,
"held": 2,
"veli": 1,
"speed": 0,
"added": 1793750400,
"bytes": 1288490188,
"status": "on",
"group": "",
"limit": 0,
"reset": "never",
"used": 0,
"next": 0,
"external": "88123",
"tags": ["paid", "month"],
"wait": 0,
"first": 1793750520,
"left": { "days": 30, "bytes": null },
"disabled": false,
"link": "https://panel.example.com/s/kV0pX7wQ2mLr9sTb",
"list": [
{
"id": "vk_3fA9c2…",
"kind": "veli",
"os": "Android",
"added": 1793750520,
"bytes": 1073741824
},
{
"id": "a1b2c3d4e5f6",
"kind": "app",
"os": "iOS",
"added": 1793751000
}
],
"lines": [
{
"node": "de-1",
"kind": "Reality",
"line": "vless://…@203.0.113.10:8443?security=reality…#de-1 · Reality"
}
],
"meta": { "order": "88123" },
"page": "https://panel.example.com/s/kV0pX7wQ2mLr9sTb",
"apps": {
"Happ": "happ://add/https://panel.example.com/s/kV0pX7wQ2mLr9sTb",
"v2rayNG": "v2rayng://install-sub?url=…",
"Hiddify": "hiddify://import/…",
"…": "…",
"Veli": "veli://add/https://panel.example.com/s/kV0pX7wQ2mLr9sTb"
}
}
}Поля клиента
id- c_ и 12 знаков — навсегда: переименование его не меняет. Работает в пути вместо имени: clients/c_Ab3dE5fG7hJ9. Храните у себя его, а не имя
name- Имя, 1–40 знаков, у каждого клиента своё; вида c_ и 12 знаков нельзя — так выглядят id
external- Внешний ID — ваш ID клиента; пусто — нет. Он не уникален: один человек может купить две подписки, поэтому поиск отдаёт список
tags- Метки
status- on, soon, limit, off, paused или waiting — выше
until- Конец срока, unix-время; 0 — бессрочно или срок ещё ждёт первого подключения
wait, first- Сколько секунд срока начнутся с первого подключения (0 — не ждёт); когда приложение впервые взяло подписку (0 — ещё не было)
left- Остаток: days и bytes; null — без срока и без лимита
devices, held, veli- Сколько устройств можно, сколько занято всеми приложениями, из них — Veli
speed- Скорость Veli в каждую сторону, Мбит/с; 0 — без ограничения
limit, reset, used, next- Лимит трафика в байтах (0 — без лимита), сброс — never, day, week или month по UTC, потрачено за период, начало следующего
group- Группа; пусто — без группы
bytes- Трафик за всё время
seen, changed- Последний запрос подписки приложением (с точностью до 10 минут, 0 — не было); последнее изменение — вручную или системой
note, contact, added- Заметка, контакт, когда добавлен
at- Когда собран ответ, unix-время
link- Ссылка подписки — секрет: её отдают только самому клиенту
page- Страница подписки для браузера, с кнопками приложений
apps- Ссылки «Добавить в …» по приложениям
list- Устройства: id, kind — veli (ключ Veli) или app (HWID другого приложения), os, added; у Veli ещё bytes
lines- Строки обычных протоколов по узлам: node, kind, line
meta- Поля вашей системы
disabled- true — клиент отключён
Ошибки
400 name- Имя пустое, длиннее 40 знаков, с управляющими символами, вида c_ и 12 знаков или это слово API: bulk, find
400 taken- Такое имя уже есть
400 bad- Значение вне пределов, неизвестная группа или узел. field называет поле, max — предел
409 idempotency- Этот Idempotency-Key уже был у другого запроса. Ключ — на одно действие: у продления и у заведения ключи разные
401 token- Токена нет, он отозван или истёк. Есть ли он ещё, покажет veli token list на сервере панели
403 rights- У токена нет таких прав: например, удалять клиентов может только «Всё». Права покажет GET me
429 wait- Больше 300 запросов в минуту по токену или десять неверных токенов с этого адреса за 15 минут. Подождите столько секунд, сколько в Retry-After
500 db- Панель не смогла записать изменения — повторите, с тем же ключом
curl -s "$VELI/clients" \
-H "Authorization: Bearer $VELI_TOKEN" \
-H "content-type: application/json" \
-d '{"name":"order-88123","days":30,"change":{"devices":3,"external":"88123","tags":["paid","month"],"meta":{"order":"88123","source":"shop"}}}'GET/clients/{name}Клиент целиком: ссылка, кнопки приложений, устройства, поля. Ссылку и кнопки токен «Только чтение» не видитчтение
Параметры
nameв пути- Имя клиента или его id
application/json{
"at": 1793754000,
"id": "c_Ab3dE5fG7hJ9",
"name": "order-88123",
"changed": 1793750460,
"seen": 1793753400,
"note": "",
"contact": "@anna",
"until": 1796342400,
"devices": 3,
"held": 2,
"veli": 1,
"speed": 0,
"added": 1793750400,
"bytes": 1288490188,
"status": "on",
"group": "",
"limit": 0,
"reset": "never",
"used": 0,
"next": 0,
"external": "88123",
"tags": ["paid", "month"],
"wait": 0,
"first": 1793750520,
"left": { "days": 30, "bytes": null },
"disabled": false,
"link": "https://panel.example.com/s/kV0pX7wQ2mLr9sTb",
"list": [
{
"id": "vk_3fA9c2…",
"kind": "veli",
"os": "Android",
"added": 1793750520,
"bytes": 1073741824
},
{
"id": "a1b2c3d4e5f6",
"kind": "app",
"os": "iOS",
"added": 1793751000
}
],
"lines": [
{
"node": "de-1",
"kind": "Reality",
"line": "vless://…@203.0.113.10:8443?security=reality…#de-1 · Reality"
}
],
"meta": { "order": "88123" },
"page": "https://panel.example.com/s/kV0pX7wQ2mLr9sTb",
"apps": {
"Happ": "happ://add/https://panel.example.com/s/kV0pX7wQ2mLr9sTb",
"v2rayNG": "v2rayng://install-sub?url=…",
"Hiddify": "hiddify://import/…",
"…": "…",
"Veli": "veli://add/https://panel.example.com/s/kV0pX7wQ2mLr9sTb"
}
}Поля клиента
id- c_ и 12 знаков — навсегда: переименование его не меняет. Работает в пути вместо имени: clients/c_Ab3dE5fG7hJ9. Храните у себя его, а не имя
name- Имя, 1–40 знаков, у каждого клиента своё; вида c_ и 12 знаков нельзя — так выглядят id
external- Внешний ID — ваш ID клиента; пусто — нет. Он не уникален: один человек может купить две подписки, поэтому поиск отдаёт список
tags- Метки
status- on, soon, limit, off, paused или waiting — выше
until- Конец срока, unix-время; 0 — бессрочно или срок ещё ждёт первого подключения
wait, first- Сколько секунд срока начнутся с первого подключения (0 — не ждёт); когда приложение впервые взяло подписку (0 — ещё не было)
left- Остаток: days и bytes; null — без срока и без лимита
devices, held, veli- Сколько устройств можно, сколько занято всеми приложениями, из них — Veli
speed- Скорость Veli в каждую сторону, Мбит/с; 0 — без ограничения
limit, reset, used, next- Лимит трафика в байтах (0 — без лимита), сброс — never, day, week или month по UTC, потрачено за период, начало следующего
group- Группа; пусто — без группы
bytes- Трафик за всё время
seen, changed- Последний запрос подписки приложением (с точностью до 10 минут, 0 — не было); последнее изменение — вручную или системой
note, contact, added- Заметка, контакт, когда добавлен
at- Когда собран ответ, unix-время
link- Ссылка подписки — секрет: её отдают только самому клиенту
page- Страница подписки для браузера, с кнопками приложений
apps- Ссылки «Добавить в …» по приложениям
list- Устройства: id, kind — veli (ключ Veli) или app (HWID другого приложения), os, added; у Veli ещё bytes
lines- Строки обычных протоколов по узлам: node, kind, line
meta- Поля вашей системы
disabled- true — клиент отключён
Ошибки
404 none- Запрошено то, чего нет, или неизвестный вызов
401 token- Токена нет, он отозван или истёк. Есть ли он ещё, покажет veli token list на сервере панели
403 rights- У токена нет таких прав: например, удалять клиентов может только «Всё». Права покажет GET me
429 wait- Больше 300 запросов в минуту по токену или десять неверных токенов с этого адреса за 15 минут. Подождите столько секунд, сколько в Retry-After
500 db- Панель не смогла записать изменения — повторите, с тем же ключом
curl -s "$VELI/clients/order-88123" \
-H "Authorization: Bearer $VELI_TOKEN"POST/clients/{name}Изменить: продлить, отключить, переименовать, новая ссылка, лимит, поляклиенты
Параметры
nameв пути- Имя клиента или его id
application/json{
"change": {
"days": 30,
"devices": 5,
"tags_add": ["vip"]
}
}Поля change — каждое по желанию
days- Продлить на столько дней: от конца срока, у истёкшего — от сейчас; меньше нуля — укоротить. У ждущего первого подключения — ждать дольше или короче. У нового клиента дни стоят рядом с change, null — бессрочно. ±1–36500
until- Конец срока ровно, unix-время; 0 — бессрочно. Не вместе с days. В прошлом — срок кончается сейчас
start- first_use — срок пойдёт с первого запроса подписки приложением; now — ждущий начинает срок сейчас
name- Новое имя — только одному клиенту; id, ссылка, устройства и трафик остаются
disabled- true — отключить: ссылка не открывается, устройства сняты с узлов, срок идёт; false — включить
relink- true — новая ссылка: старая перестаёт работать, аккаунты обычных протоколов новые, устройства Veli остаются
devices- Сколько устройств можно, 1–100
speed- Мбит/с, 0–100000; 0 — без ограничения
limit, reset, zero- Лимит трафика в байтах, сброс, true — начать счёт с нуля
group- Группа по названию; пусто — без группы
external- Внешний ID, до 128 знаков; пусто — убрать
tags- Метки — весь список заново: до 20, каждая до 32 знаков
tags_add, tags_remove- Добавить и убрать метки, остальные остаются — удобно для многих сразу
meta- Поля вашей системы — все заново: до 20; ключ — латиница, цифры, _ . -, до 40 знаков; значение до 500
note, contact- Заметка до 300 знаков, контакт до 100
Слишком длинное значение не обрезается, а даёт ошибку bad с полем и пределом — {"error": "bad", "field": "change.devices", "max": 100}: иначе ваша система не узнала бы, что сохранилось не то. Новый клиент приходит в ответе целиком, вместе со ссылкой.
application/json{ "done": 1 }Ошибки
400 none- Клиента, узла или группы с таким именем нет
400 bad- Значение вне пределов, неизвестная группа или узел. field называет поле, max — предел
400 taken- Такое имя уже есть
409 idempotency- Этот Idempotency-Key уже был у другого запроса. Ключ — на одно действие: у продления и у заведения ключи разные
401 token- Токена нет, он отозван или истёк. Есть ли он ещё, покажет veli token list на сервере панели
403 rights- У токена нет таких прав: например, удалять клиентов может только «Всё». Права покажет GET me
429 wait- Больше 300 запросов в минуту по токену или десять неверных токенов с этого адреса за 15 минут. Подождите столько секунд, сколько в Retry-After
500 db- Панель не смогла записать изменения — повторите, с тем же ключом
curl -s "$VELI/clients/order-88123" \
-H "Authorization: Bearer $VELI_TOKEN" \
-H "content-type: application/json" \
-d '{"change":{"days":30,"devices":5,"tags_add":["vip"]}}'GET/clients/{name}/qrQR-код ссылки: SVG или PNGклиенты
Параметры
nameв пути- Имя клиента или его id
formatв запросе- svg или png; без него — svg
sizeв запросе- Сторона PNG в точках, 128–2048; без него — 512
ofв запросе- veli — QR ссылки «Добавить в Veli» вместо ссылки подписки
image/svg+xml<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 41 41" shape-rendering="crispEdges">
<path fill="#fff" d="M0 0h41v41H0z"/>
<path d="M4 4h7v1H4z…"/>
</svg>Ошибки
404 none- Запрошено то, чего нет, или неизвестный вызов
401 token- Токена нет, он отозван или истёк. Есть ли он ещё, покажет veli token list на сервере панели
403 rights- У токена нет таких прав: например, удалять клиентов может только «Всё». Права покажет GET me
429 wait- Больше 300 запросов в минуту по токену или десять неверных токенов с этого адреса за 15 минут. Подождите столько секунд, сколько в Retry-After
500 db- Панель не смогла записать изменения — повторите, с тем же ключом
curl -s "$VELI/clients/order-88123/qr?format=svg" \
-H "Authorization: Bearer $VELI_TOKEN" -o qr.svgGET/clients/{name}/statsТрафик клиента по днямчтение
Даты по UTC, от старой к сегодняшней; байты в обе стороны.
Параметры
nameв пути- Имя клиента или его id
daysв запросе- За сколько дней: 7, 30 или 90; без него — 30
application/json{
"days": ["2026-10-29", "2026-10-30", "2026-10-31", "2026-11-01", "2026-11-02", "2026-11-03", "2026-11-04"],
"bytes": [0, 52428800, 104857600, 314572800, 209715200, 419430400, 188743680]
}Ошибки
404 none- Запрошено то, чего нет, или неизвестный вызов
401 token- Токена нет, он отозван или истёк. Есть ли он ещё, покажет veli token list на сервере панели
403 rights- У токена нет таких прав: например, удалять клиентов может только «Всё». Права покажет GET me
429 wait- Больше 300 запросов в минуту по токену или десять неверных токенов с этого адреса за 15 минут. Подождите столько секунд, сколько в Retry-After
500 db- Панель не смогла записать изменения — повторите, с тем же ключом
curl -s "$VELI/clients/order-88123/stats?days=7" \
-H "Authorization: Bearer $VELI_TOKEN"GET/clients/{name}/historyИстория клиентачтение
Параметры
nameв пути- Имя клиента или его id
application/json{
"at": 1793754000,
"client": "order-88123",
"history": [
{
"at": 1793751000,
"kind": "event",
"event": "device.added",
"os": "iOS",
"app": "Happ"
},
{
"at": 1793750460,
"kind": "admin",
"what": "client order-88123",
"by": "cabinet",
"token": true,
"fields": ["days"]
},
{
"at": 1793750400,
"kind": "admin",
"what": "clients add",
"by": "cabinet",
"token": true
}
]
}Ошибки
404 none- Запрошено то, чего нет, или неизвестный вызов
401 token- Токена нет, он отозван или истёк. Есть ли он ещё, покажет veli token list на сервере панели
403 rights- У токена нет таких прав: например, удалять клиентов может только «Всё». Права покажет GET me
429 wait- Больше 300 запросов в минуту по токену или десять неверных токенов с этого адреса за 15 минут. Подождите столько секунд, сколько в Retry-After
500 db- Панель не смогла записать изменения — повторите, с тем же ключом
curl -s "$VELI/clients/order-88123/history" \
-H "Authorization: Bearer $VELI_TOKEN"GET/clients/{name}/diagnosisПочему клиент может не подключатьсячтение
Параметры
nameв пути- Имя клиента или его id
application/json{
"at": 1793754000,
"ok": false,
"checks": [
{ "code": "devices_full", "level": "warn", "action": "unbind", "n": 3 },
{ "code": "nodes_some_down", "level": "info", "n": 1 }
],
"last": { "at": 1793753700, "app": "Happ", "code": 403 }
}Ошибки
404 none- Запрошено то, чего нет, или неизвестный вызов
401 token- Токена нет, он отозван или истёк. Есть ли он ещё, покажет veli token list на сервере панели
403 rights- У токена нет таких прав: например, удалять клиентов может только «Всё». Права покажет GET me
429 wait- Больше 300 запросов в минуту по токену или десять неверных токенов с этого адреса за 15 минут. Подождите столько секунд, сколько в Retry-After
500 db- Панель не смогла записать изменения — повторите, с тем же ключом
curl -s "$VELI/clients/order-88123/diagnosis" \
-H "Authorization: Bearer $VELI_TOKEN"POST/clients/{name}/unbindОтвязать устройствоклиенты
device — id из list клиента. Место освобождается сразу: на нём можно подключить другое устройство.
Параметры
nameв пути- Имя клиента или его id
application/json{ "device": "a1b2c3d4e5f6" }application/json{ "done": 1 }Ошибки
400 none- Клиента, узла или группы с таким именем нет
401 token- Токена нет, он отозван или истёк. Есть ли он ещё, покажет veli token list на сервере панели
403 rights- У токена нет таких прав: например, удалять клиентов может только «Всё». Права покажет GET me
429 wait- Больше 300 запросов в минуту по токену или десять неверных токенов с этого адреса за 15 минут. Подождите столько секунд, сколько в Retry-After
500 db- Панель не смогла записать изменения — повторите, с тем же ключом
curl -s "$VELI/clients/order-88123/unbind" \
-H "Authorization: Bearer $VELI_TOKEN" \
-H "content-type: application/json" \
-d '{"device":"a1b2c3d4e5f6"}'POST/clients/bulkИзменить многих сразу — всех или никогоклиенты
application/json{
"filter": {
"status": ["on", "soon"],
"tag": "paid"
},
"change": { "days": 3 },
"dry": true
}Поля change — каждое по желанию
days- Продлить на столько дней: от конца срока, у истёкшего — от сейчас; меньше нуля — укоротить. У ждущего первого подключения — ждать дольше или короче. У нового клиента дни стоят рядом с change, null — бессрочно. ±1–36500
until- Конец срока ровно, unix-время; 0 — бессрочно. Не вместе с days. В прошлом — срок кончается сейчас
start- first_use — срок пойдёт с первого запроса подписки приложением; now — ждущий начинает срок сейчас
name- Новое имя — только одному клиенту; id, ссылка, устройства и трафик остаются
disabled- true — отключить: ссылка не открывается, устройства сняты с узлов, срок идёт; false — включить
relink- true — новая ссылка: старая перестаёт работать, аккаунты обычных протоколов новые, устройства Veli остаются
devices- Сколько устройств можно, 1–100
speed- Мбит/с, 0–100000; 0 — без ограничения
limit, reset, zero- Лимит трафика в байтах, сброс, true — начать счёт с нуля
group- Группа по названию; пусто — без группы
external- Внешний ID, до 128 знаков; пусто — убрать
tags- Метки — весь список заново: до 20, каждая до 32 знаков
tags_add, tags_remove- Добавить и убрать метки, остальные остаются — удобно для многих сразу
meta- Поля вашей системы — все заново: до 20; ключ — латиница, цифры, _ . -, до 40 знаков; значение до 500
note, contact- Заметка до 300 знаков, контакт до 100
Слишком длинное значение не обрезается, а даёт ошибку bad с полем и пределом — {"error": "bad", "field": "change.devices", "max": 100}: иначе ваша система не узнала бы, что сохранилось не то. Новый клиент приходит в ответе целиком, вместе со ссылкой.
application/json{
"done": 0,
"matched": 412,
"names": ["order-88123", "order-88124", "…"]
}Ошибки
400 none- Клиента, узла или группы с таким именем нет
400 bad- Значение вне пределов, неизвестная группа или узел. field называет поле, max — предел
403 rights- У токена нет таких прав: например, удалять клиентов может только «Всё». Права покажет GET me
409 idempotency- Этот Idempotency-Key уже был у другого запроса. Ключ — на одно действие: у продления и у заведения ключи разные
401 token- Токена нет, он отозван или истёк. Есть ли он ещё, покажет veli token list на сервере панели
429 wait- Больше 300 запросов в минуту по токену или десять неверных токенов с этого адреса за 15 минут. Подождите столько секунд, сколько в Retry-After
500 db- Панель не смогла записать изменения — повторите, с тем же ключом
curl -s "$VELI/clients/bulk" \
-H "Authorization: Bearer $VELI_TOKEN" \
-H "content-type: application/json" \
-d '{"filter":{"status":["on","soon"],"tag":"paid"},"change":{"days":3},"dry":true}'POST/clients/{name}/removeУдалить клиента — в корзину на 30 днейвсё
Параметры
nameв пути- Имя клиента или его id
application/json{ "done": 1 }Ошибки
400 none- Клиента, узла или группы с таким именем нет
401 token- Токена нет, он отозван или истёк. Есть ли он ещё, покажет veli token list на сервере панели
403 rights- У токена нет таких прав: например, удалять клиентов может только «Всё». Права покажет GET me
429 wait- Больше 300 запросов в минуту по токену или десять неверных токенов с этого адреса за 15 минут. Подождите столько секунд, сколько в Retry-After
500 db- Панель не смогла записать изменения — повторите, с тем же ключом
curl -s "$VELI/clients/order-88123/remove" \
-H "Authorization: Bearer $VELI_TOKEN" -X POSTКорзина4
GET/trashУдалённые клиентычтение
application/json{
"at": 1793754000,
"days": 30,
"clients": [
{
"id": "c_Ab3dE5fG7hJ9",
"name": "order-88123",
"gone": 1793751100,
"purge": 1796343100,
"until": 1796342400,
"external": "88123",
"tags": ["paid"],
"contact": "@anna",
"note": "",
"devices": 2,
"taken": false
}
]
}Ошибки
401 token- Токена нет, он отозван или истёк. Есть ли он ещё, покажет veli token list на сервере панели
403 rights- У токена нет таких прав: например, удалять клиентов может только «Всё». Права покажет GET me
429 wait- Больше 300 запросов в минуту по токену или десять неверных токенов с этого адреса за 15 минут. Подождите столько секунд, сколько в Retry-After
500 db- Панель не смогла записать изменения — повторите, с тем же ключом
curl -s "$VELI/trash" \
-H "Authorization: Bearer $VELI_TOKEN"POST/trash/{id}/restoreВернуть из корзинывсё
С той же ссылкой и устройствами. Имя занято — taken. Ответ — клиент целиком.
Параметры
idв пути- id клиента в корзине
application/json{
"done": 1,
"client": {
"at": 1793754000,
"id": "c_Ab3dE5fG7hJ9",
"name": "order-88123",
"changed": 1793750460,
"seen": 1793753400,
"note": "",
"contact": "@anna",
"until": 1796342400,
"devices": 3,
"held": 2,
"veli": 1,
"speed": 0,
"added": 1793750400,
"bytes": 1288490188,
"status": "on",
"group": "",
"limit": 0,
"reset": "never",
"used": 0,
"next": 0,
"external": "88123",
"tags": ["paid", "month"],
"wait": 0,
"first": 1793750520,
"left": { "days": 30, "bytes": null },
"disabled": false,
"link": "https://panel.example.com/s/kV0pX7wQ2mLr9sTb",
"list": [
{
"id": "vk_3fA9c2…",
"kind": "veli",
"os": "Android",
"added": 1793750520,
"bytes": 1073741824
},
{
"id": "a1b2c3d4e5f6",
"kind": "app",
"os": "iOS",
"added": 1793751000
}
],
"lines": [
{
"node": "de-1",
"kind": "Reality",
"line": "vless://…@203.0.113.10:8443?security=reality…#de-1 · Reality"
}
],
"meta": { "order": "88123" },
"page": "https://panel.example.com/s/kV0pX7wQ2mLr9sTb",
"apps": {
"Happ": "happ://add/https://panel.example.com/s/kV0pX7wQ2mLr9sTb",
"v2rayNG": "v2rayng://install-sub?url=…",
"Hiddify": "hiddify://import/…",
"…": "…",
"Veli": "veli://add/https://panel.example.com/s/kV0pX7wQ2mLr9sTb"
}
}
}Ошибки
400 none- Клиента, узла или группы с таким именем нет
400 taken- Такое имя уже есть
401 token- Токена нет, он отозван или истёк. Есть ли он ещё, покажет veli token list на сервере панели
403 rights- У токена нет таких прав: например, удалять клиентов может только «Всё». Права покажет GET me
429 wait- Больше 300 запросов в минуту по токену или десять неверных токенов с этого адреса за 15 минут. Подождите столько секунд, сколько в Retry-After
500 db- Панель не смогла записать изменения — повторите, с тем же ключом
curl -s "$VELI/trash/c_Ab3dE5fG7hJ9/restore" \
-H "Authorization: Bearer $VELI_TOKEN" -X POSTPOST/trash/{id}/removeУдалить из корзины насовсемвсё
Вернуть его больше нельзя.
Параметры
idв пути- id клиента в корзине
application/json{ "done": 1 }Ошибки
400 none- Клиента, узла или группы с таким именем нет
401 token- Токена нет, он отозван или истёк. Есть ли он ещё, покажет veli token list на сервере панели
403 rights- У токена нет таких прав: например, удалять клиентов может только «Всё». Права покажет GET me
429 wait- Больше 300 запросов в минуту по токену или десять неверных токенов с этого адреса за 15 минут. Подождите столько секунд, сколько в Retry-After
500 db- Панель не смогла записать изменения — повторите, с тем же ключом
curl -s "$VELI/trash/c_Ab3dE5fG7hJ9/remove" \
-H "Authorization: Bearer $VELI_TOKEN" -X POSTPOST/trash/clearОчистить корзинувсё
Все удалённые — насовсем. done — сколько их было.
application/json{ "done": 4 }Ошибки
401 token- Токена нет, он отозван или истёк. Есть ли он ещё, покажет veli token list на сервере панели
403 rights- У токена нет таких прав: например, удалять клиентов может только «Всё». Права покажет GET me
429 wait- Больше 300 запросов в минуту по токену или десять неверных токенов с этого адреса за 15 минут. Подождите столько секунд, сколько в Retry-After
500 db- Панель не смогла записать изменения — повторите, с тем же ключом
curl -s "$VELI/trash/clear" \
-H "Authorization: Bearer $VELI_TOKEN" -X POSTЛента событий1
GET/eventsЛента событий: для системы без своего адресачтение
Параметры
afterв запросе- last прошлого ответа; 0 — с начала ленты
waitв запросе- Сколько секунд ждать, если новых нет: 0–25
typesв запросе- Только эти события, через запятую
limitв запросе- Событий за раз, 1–1000; без него — 100
application/json{
"at": 1793754000,
"events": [
{
"seq": 1041,
"id": "evt_mV3xQ8rT2kLp",
"event": "client.added",
"at": 1793750460,
"data": {
"client": {
"id": "c_Ab3dE5fG7hJ9",
"name": "order-88123",
"changed": 1793750460,
"seen": 1793753400,
"note": "",
"contact": "@anna",
"until": 1796342400,
"devices": 3,
"held": 2,
"veli": 1,
"speed": 0,
"added": 1793750400,
"bytes": 1288490188,
"status": "on",
"group": "",
"limit": 0,
"reset": "never",
"used": 0,
"next": 0,
"external": "88123",
"tags": ["paid", "month"],
"wait": 0,
"first": 1793750520,
"left": { "days": 30, "bytes": null }
}
}
}
],
"last": 1041
}Ошибки
401 token- Токена нет, он отозван или истёк. Есть ли он ещё, покажет veli token list на сервере панели
403 rights- У токена нет таких прав: например, удалять клиентов может только «Всё». Права покажет GET me
429 wait- Больше 300 запросов в минуту по токену или десять неверных токенов с этого адреса за 15 минут. Подождите столько секунд, сколько в Retry-After
500 db- Панель не смогла записать изменения — повторите, с тем же ключом
curl -s "$VELI/events?after=1040&wait=25&types=client.added,client.expired&limit=100" \
-H "Authorization: Bearer $VELI_TOKEN"Обзор, статистика, устройства5
GET/overviewСводка: клиенты, устройства, узлы, трафик, событиячтение
application/json{
"at": 1793754000,
"clients": {
"total": 148,
"active": 131,
"expired": 9,
"expiring": 6,
"limited": 1,
"paused": 1
},
"devices": { "veli": 96, "other": 187 },
"online": 74,
"traffic": 5841203482112,
"top": [
{ "name": "order-88123", "bytes": 41231564800 }
],
"nodes": [
{
"name": "de-1",
"host": "203.0.113.10",
"reported": "203.0.113.10",
"address": "",
"port": 443,
"up": true,
"seen": 1793753990,
"connected": 31,
"protocols": ["Veli", "Reality"],
"ports": [
{ "kind": "veli", "label": "Veli", "port": 443 },
{ "kind": "reality", "label": "Reality", "port": 8443 }
],
"version": "1.8.0",
"behind": false,
"disabled": false,
"main": false,
"added": 1791158400,
"devices": 58,
"traffic": 912680550400
}
],
"events": [
{ "kind": "expiring", "count": 6 },
{ "kind": "silent", "node": "nl-1", "since": 1793753400 }
]
}Ошибки
401 token- Токена нет, он отозван или истёк. Есть ли он ещё, покажет veli token list на сервере панели
403 rights- У токена нет таких прав: например, удалять клиентов может только «Всё». Права покажет GET me
429 wait- Больше 300 запросов в минуту по токену или десять неверных токенов с этого адреса за 15 минут. Подождите столько секунд, сколько в Retry-After
500 db- Панель не смогла записать изменения — повторите, с тем же ключом
curl -s "$VELI/overview" \
-H "Authorization: Bearer $VELI_TOKEN"GET/statsТрафик панели по дням: всего и по узламчтение
Параметры
daysв запросе- За сколько дней: 7, 30 или 90; без него — 30
application/json{
"at": 1793754000,
"days": ["2026-10-29", "2026-10-30", "2026-10-31", "2026-11-01", "2026-11-02", "2026-11-03", "2026-11-04"],
"total": [612368384000, 640942080000, 702545920000, 655360000000, 598933504000, 683671552000, 214748364800],
"nodes": [
{
"name": "de-1",
"bytes": [311385128960, 322122547200, 354334801920, 330712481792, 300647710720, 343597383680, 107374182400]
}
],
"top": [
{ "name": "order-88123", "bytes": 1288490188 }
],
"online": 74
}Ошибки
401 token- Токена нет, он отозван или истёк. Есть ли он ещё, покажет veli token list на сервере панели
403 rights- У токена нет таких прав: например, удалять клиентов может только «Всё». Права покажет GET me
429 wait- Больше 300 запросов в минуту по токену или десять неверных токенов с этого адреса за 15 минут. Подождите столько секунд, сколько в Retry-After
500 db- Панель не смогла записать изменения — повторите, с тем же ключом
curl -s "$VELI/stats?days=7" \
-H "Authorization: Bearer $VELI_TOKEN"GET/devicesВсе устройства всех клиентовчтение
application/json{
"at": 1793754000,
"devices": [
{
"id": "vk_3fA9c2…",
"client": "order-88123",
"kind": "veli",
"app": "Veli",
"os": "Android",
"added": 1793750520,
"seen": 1793753940,
"bytes": 1073741824
},
{
"id": "a1b2c3d4e5f6",
"client": "order-88123",
"kind": "app",
"app": "Happ",
"os": "iOS",
"added": 1793751000,
"seen": 1793753700
}
],
"by_app": { "Veli": 96, "Happ": 120, "v2rayN": 67 },
"by_os": { "Android": 140, "iOS": 80, "Windows": 63 }
}Ошибки
401 token- Токена нет, он отозван или истёк. Есть ли он ещё, покажет veli token list на сервере панели
403 rights- У токена нет таких прав: например, удалять клиентов может только «Всё». Права покажет GET me
429 wait- Больше 300 запросов в минуту по токену или десять неверных токенов с этого адреса за 15 минут. Подождите столько секунд, сколько в Retry-After
500 db- Панель не смогла записать изменения — повторите, с тем же ключом
curl -s "$VELI/devices" \
-H "Authorization: Bearer $VELI_TOKEN"GET/requestsПоследние запросы подпискичтение
Параметры
clientв запросе- Только запросы этого клиента
limitв запросе- Сколько последних; без него — 200, больше 2000 не бывает
application/json{
"at": 1793754000,
"requests": [
{
"at": 1793753700,
"client": "order-88123",
"ip": "198.51.100.7",
"app": "Happ",
"code": 200,
"page": false
}
]
}Ошибки
401 token- Токена нет, он отозван или истёк. Есть ли он ещё, покажет veli token list на сервере панели
403 rights- У токена нет таких прав: например, удалять клиентов может только «Всё». Права покажет GET me
429 wait- Больше 300 запросов в минуту по токену или десять неверных токенов с этого адреса за 15 минут. Подождите столько секунд, сколько в Retry-After
500 db- Панель не смогла записать изменения — повторите, с тем же ключом
curl -s "$VELI/requests?client=order-88123&limit=50" \
-H "Authorization: Bearer $VELI_TOKEN"GET/logЖурнал действий: что и откуда сделали токены и консольвсё
Параметры
whoв запросе- Название токена или root — только его действия
whatв запросе- clients, nodes, groups, integrations, plugins или backups
qв запросе- Слова в записи, например имя клиента
beforeв запросе- Старше этого, unix-время: следующая страница
afterв запросе- Новее этого, unix-время
application/json{
"at": 1793754000,
"more": false,
"names": ["root", "cabinet"],
"kept": 20000,
"entries": [
{
"at": 1793753700,
"name": "cabinet",
"token": true,
"from": "198.51.100.7",
"what": "client add order-88123",
"kind": "clients",
"names": ["order-88123"],
"fields": []
},
{
"at": 1793752200,
"name": "root",
"token": false,
"from": null,
"what": "token add cabinet clients",
"kind": "integrations",
"names": [],
"fields": []
}
]
}Ошибки
401 token- Токена нет, он отозван или истёк. Есть ли он ещё, покажет veli token list на сервере панели
403 rights- У токена нет таких прав: например, удалять клиентов может только «Всё». Права покажет GET me
429 wait- Больше 300 запросов в минуту по токену или десять неверных токенов с этого адреса за 15 минут. Подождите столько секунд, сколько в Retry-After
500 db- Панель не смогла записать изменения — повторите, с тем же ключом
curl -s "$VELI/log?who=cabinet&what=clients" \
-H "Authorization: Bearer $VELI_TOKEN"Узлы6
GET/nodesВсе узлычтение
application/json{
"at": 1793754000,
"nodes": [
{
"name": "de-1",
"host": "203.0.113.10",
"reported": "203.0.113.10",
"address": "",
"port": 443,
"up": true,
"seen": 1793753990,
"connected": 31,
"protocols": ["Veli", "Reality"],
"ports": [
{ "kind": "veli", "label": "Veli", "port": 443 },
{ "kind": "reality", "label": "Reality", "port": 8443 }
],
"version": "1.8.0",
"behind": false,
"disabled": false,
"main": false,
"added": 1791158400,
"devices": 58,
"traffic": 912680550400
}
],
"kinds": [
{ "kind": "reality", "label": "Reality", "port": 8443, "udp": false },
{
"kind": "shadowsocks",
"label": "Shadowsocks",
"port": 8388,
"udp": false
},
{ "kind": "hysteria2", "label": "Hysteria2", "port": 8443, "udp": true }
]
}Ошибки
401 token- Токена нет, он отозван или истёк. Есть ли он ещё, покажет veli token list на сервере панели
403 rights- У токена нет таких прав: например, удалять клиентов может только «Всё». Права покажет GET me
429 wait- Больше 300 запросов в минуту по токену или десять неверных токенов с этого адреса за 15 минут. Подождите столько секунд, сколько в Retry-After
500 db- Панель не смогла записать изменения — повторите, с тем же ключом
curl -s "$VELI/nodes" \
-H "Authorization: Bearer $VELI_TOKEN"POST/nodesДобавить узелвсё
application/json{ "name": "de-2", "protocols": "reality,shadowsocks:9388" }application/json{
"command": "sudo veli panel attach https://panel.example.com --protocols reality,shadowsocks:9388 --token -",
"token": "Hq3Zr8vT1kLm…"
}Ошибки
400 name- Имя пустое, длиннее 40 знаков, с управляющими символами, вида c_ и 12 знаков или это слово API: bulk, find
400 taken- Такое имя уже есть
400 bad- Значение вне пределов, неизвестная группа или узел. field называет поле, max — предел
401 token- Токена нет, он отозван или истёк. Есть ли он ещё, покажет veli token list на сервере панели
403 rights- У токена нет таких прав: например, удалять клиентов может только «Всё». Права покажет GET me
429 wait- Больше 300 запросов в минуту по токену или десять неверных токенов с этого адреса за 15 минут. Подождите столько секунд, сколько в Retry-After
500 db- Панель не смогла записать изменения — повторите, с тем же ключом
curl -s "$VELI/nodes" \
-H "Authorization: Bearer $VELI_TOKEN" \
-H "content-type: application/json" \
-d '{"name":"de-2","protocols":"reality,shadowsocks:9388"}'GET/nodes/{name}Один узелчтение
Параметры
nameв пути- Имя узла
application/json{
"name": "de-1",
"host": "203.0.113.10",
"reported": "203.0.113.10",
"address": "",
"port": 443,
"up": true,
"seen": 1793753990,
"connected": 31,
"protocols": ["Veli", "Reality"],
"ports": [
{ "kind": "veli", "label": "Veli", "port": 443 },
{ "kind": "reality", "label": "Reality", "port": 8443 }
],
"version": "1.8.0",
"behind": false,
"disabled": false,
"main": false,
"added": 1791158400,
"devices": 58,
"traffic": 912680550400,
"at": 1793754000,
"sni": "www.samsung.com"
}Ошибки
404 none- Запрошено то, чего нет, или неизвестный вызов
401 token- Токена нет, он отозван или истёк. Есть ли он ещё, покажет veli token list на сервере панели
403 rights- У токена нет таких прав: например, удалять клиентов может только «Всё». Права покажет GET me
429 wait- Больше 300 запросов в минуту по токену или десять неверных токенов с этого адреса за 15 минут. Подождите столько секунд, сколько в Retry-After
500 db- Панель не смогла записать изменения — повторите, с тем же ключом
curl -s "$VELI/nodes/de-1" \
-H "Authorization: Bearer $VELI_TOKEN"POST/nodes/{name}Изменить узелвсё
Параметры
nameв пути- Имя узла
application/json{
"change": { "address": "de1.example.com", "disabled": false }
}application/json{ "done": 1 }Ошибки
400 none- Клиента, узла или группы с таким именем нет
400 bad- Значение вне пределов, неизвестная группа или узел. field называет поле, max — предел
400 main- Главный узел мини-панели не отключается и не убирается
401 token- Токена нет, он отозван или истёк. Есть ли он ещё, покажет veli token list на сервере панели
403 rights- У токена нет таких прав: например, удалять клиентов может только «Всё». Права покажет GET me
429 wait- Больше 300 запросов в минуту по токену или десять неверных токенов с этого адреса за 15 минут. Подождите столько секунд, сколько в Retry-After
500 db- Панель не смогла записать изменения — повторите, с тем же ключом
curl -s "$VELI/nodes/de-1" \
-H "Authorization: Bearer $VELI_TOKEN" \
-H "content-type: application/json" \
-d '{"change":{"address":"de1.example.com","disabled":false}}'GET/nodes/{name}/statsТрафик узла по днямчтение
Как у клиента: даты по UTC, байты в обе стороны.
Параметры
nameв пути- Имя узла
daysв запросе- За сколько дней: 7, 30 или 90; без него — 30
application/json{
"days": ["2026-10-29", "2026-10-30", "2026-10-31", "2026-11-01", "2026-11-02", "2026-11-03", "2026-11-04"],
"bytes": [0, 52428800, 104857600, 314572800, 209715200, 419430400, 188743680]
}Ошибки
404 none- Запрошено то, чего нет, или неизвестный вызов
401 token- Токена нет, он отозван или истёк. Есть ли он ещё, покажет veli token list на сервере панели
403 rights- У токена нет таких прав: например, удалять клиентов может только «Всё». Права покажет GET me
429 wait- Больше 300 запросов в минуту по токену или десять неверных токенов с этого адреса за 15 минут. Подождите столько секунд, сколько в Retry-After
500 db- Панель не смогла записать изменения — повторите, с тем же ключом
curl -s "$VELI/nodes/de-1/stats?days=7" \
-H "Authorization: Bearer $VELI_TOKEN"POST/nodes/{name}/removeУбрать узелвсё
Его строки уходят из подписок. Главный узел мини-панели не убирается — main.
Параметры
nameв пути- Имя узла
application/json{ "done": 1 }Ошибки
400 none- Клиента, узла или группы с таким именем нет
400 main- Главный узел мини-панели не отключается и не убирается
401 token- Токена нет, он отозван или истёк. Есть ли он ещё, покажет veli token list на сервере панели
403 rights- У токена нет таких прав: например, удалять клиентов может только «Всё». Права покажет GET me
429 wait- Больше 300 запросов в минуту по токену или десять неверных токенов с этого адреса за 15 минут. Подождите столько секунд, сколько в Retry-After
500 db- Панель не смогла записать изменения — повторите, с тем же ключом
curl -s "$VELI/nodes/de-2/remove" \
-H "Authorization: Bearer $VELI_TOKEN" -X POSTГруппы4
GET/groupsГруппы клиентовчтение
application/json{
"at": 1793754000,
"groups": [
{
"name": "europe",
"nodes": ["de-1", "nl-1"],
"protocols": null,
"clients": 42
}
],
"nodes": ["de-1", "nl-1", "fi-1"],
"kinds": [
{ "kind": "veli", "label": "Veli" },
{ "kind": "reality", "label": "Reality" }
]
}Ошибки
401 token- Токена нет, он отозван или истёк. Есть ли он ещё, покажет veli token list на сервере панели
403 rights- У токена нет таких прав: например, удалять клиентов может только «Всё». Права покажет GET me
429 wait- Больше 300 запросов в минуту по токену или десять неверных токенов с этого адреса за 15 минут. Подождите столько секунд, сколько в Retry-After
500 db- Панель не смогла записать изменения — повторите, с тем же ключом
curl -s "$VELI/groups" \
-H "Authorization: Bearer $VELI_TOKEN"POST/groupsДобавить группувсё
nodes и protocols — из списков nodes и kinds ответа «GET groups»; null — все.
application/json{
"group": {
"name": "europe",
"nodes": ["de-1", "nl-1"],
"protocols": null
}
}application/json{ "done": 1 }Ошибки
400 name- Имя пустое, длиннее 40 знаков, с управляющими символами, вида c_ и 12 знаков или это слово API: bulk, find
400 taken- Такое имя уже есть
400 bad- Значение вне пределов, неизвестная группа или узел. field называет поле, max — предел
401 token- Токена нет, он отозван или истёк. Есть ли он ещё, покажет veli token list на сервере панели
403 rights- У токена нет таких прав: например, удалять клиентов может только «Всё». Права покажет GET me
429 wait- Больше 300 запросов в минуту по токену или десять неверных токенов с этого адреса за 15 минут. Подождите столько секунд, сколько в Retry-After
500 db- Панель не смогла записать изменения — повторите, с тем же ключом
curl -s "$VELI/groups" \
-H "Authorization: Bearer $VELI_TOKEN" \
-H "content-type: application/json" \
-d '{"group":{"name":"europe","nodes":["de-1","nl-1"],"protocols":null}}'POST/groups/{name}Изменить группувсё
Тело — группа целиком, как при добавлении.
Параметры
nameв пути- Имя группы
application/json{
"group": {
"name": "europe",
"nodes": null,
"protocols": ["veli"]
}
}application/json{ "done": 1 }Ошибки
400 none- Клиента, узла или группы с таким именем нет
400 bad- Значение вне пределов, неизвестная группа или узел. field называет поле, max — предел
401 token- Токена нет, он отозван или истёк. Есть ли он ещё, покажет veli token list на сервере панели
403 rights- У токена нет таких прав: например, удалять клиентов может только «Всё». Права покажет GET me
429 wait- Больше 300 запросов в минуту по токену или десять неверных токенов с этого адреса за 15 минут. Подождите столько секунд, сколько в Retry-After
500 db- Панель не смогла записать изменения — повторите, с тем же ключом
curl -s "$VELI/groups/europe" \
-H "Authorization: Bearer $VELI_TOKEN" \
-H "content-type: application/json" \
-d '{"group":{"name":"europe","nodes":null,"protocols":["veli"]}}'POST/groups/{name}/removeУдалить группувсё
Её клиенты остаются — без группы, со всеми узлами и протоколами. done — сколько их было в группе.
Параметры
nameв пути- Имя группы
application/json{ "done": 42 }Ошибки
400 none- Клиента, узла или группы с таким именем нет
401 token- Токена нет, он отозван или истёк. Есть ли он ещё, покажет veli token list на сервере панели
403 rights- У токена нет таких прав: например, удалять клиентов может только «Всё». Права покажет GET me
429 wait- Больше 300 запросов в минуту по токену или десять неверных токенов с этого адреса за 15 минут. Подождите столько секунд, сколько в Retry-After
500 db- Панель не смогла записать изменения — повторите, с тем же ключом
curl -s "$VELI/groups/europe/remove" \
-H "Authorization: Bearer $VELI_TOKEN" -X POSTСхема OpenAPI и свой клиент
Панель отдаёт схему всего API, OpenAPI 3.1. Тест панели сверяет её с кодом: вызова не из схемы не бывает. По ней собирают клиент на своём языке, её берут Postman, Insomnia, n8n и другие системы.
curl -s "$VELI/openapi.json" \
-H "Authorization: Bearer $VELI_TOKEN" -o veli-openapi.jsonnpx openapi-typescript veli-openapi.json -o veli-api.d.ts # types for TypeScript
npx @openapitools/openapi-generator-cli generate -i veli-openapi.json -g python -o veli_client # a Python clientТокены и вебхуки в API не создаются: их делает только консоль (veli token add, veli webhook add).
Статусы
on- Работает: срок идёт, трафик есть
soon- Работает, но срок кончится за 3 дня — время напомнить
limit- Кончился трафик периода: ссылка открывается, подключиться нельзя до сброса или нового лимита
off- Срок истёк: ссылка открывается и показывает «Подписка закончилась», подключиться нельзя. Продлили — подключается снова
paused- Отключён вручную или системой; срок при этом идёт
waiting- Срок ждёт первого подключения: подарок или «купил заранее»
В списке и в событиях
id- c_ и 12 знаков — навсегда: переименование его не меняет. Работает в пути вместо имени: clients/c_Ab3dE5fG7hJ9. Храните у себя его, а не имя
name- Имя, 1–40 знаков, у каждого клиента своё; вида c_ и 12 знаков нельзя — так выглядят id
external- Внешний ID — ваш ID клиента; пусто — нет. Он не уникален: один человек может купить две подписки, поэтому поиск отдаёт список
tags- Метки
status- on, soon, limit, off, paused или waiting — выше
until- Конец срока, unix-время; 0 — бессрочно или срок ещё ждёт первого подключения
wait, first- Сколько секунд срока начнутся с первого подключения (0 — не ждёт); когда приложение впервые взяло подписку (0 — ещё не было)
left- Остаток: days и bytes; null — без срока и без лимита
devices, held, veli- Сколько устройств можно, сколько занято всеми приложениями, из них — Veli
speed- Скорость Veli в каждую сторону, Мбит/с; 0 — без ограничения
limit, reset, used, next- Лимит трафика в байтах (0 — без лимита), сброс — never, day, week или month по UTC, потрачено за период, начало следующего
group- Группа; пусто — без группы
bytes- Трафик за всё время
seen, changed- Последний запрос подписки приложением (с точностью до 10 минут, 0 — не было); последнее изменение — вручную или системой
note, contact, added- Заметка, контакт, когда добавлен
Только у одного клиента — GET clients/<имя>
at- Когда собран ответ, unix-время
link- Ссылка подписки — секрет: её отдают только самому клиенту
page- Страница подписки для браузера, с кнопками приложений
apps- Ссылки «Добавить в …» по приложениям
list- Устройства: id, kind — veli (ключ Veli) или app (HWID другого приложения), os, added; у Veli ещё bytes
lines- Строки обычных протоколов по узлам: node, kind, line
meta- Поля вашей системы
disabled- true — клиент отключён
Кнопки приложений
apps — готовые ссылки «Добавить в …»: Happ, v2rayNG, Hiddify, Streisand, sing-box, Clash, Shadowrocket, v2RayTun и Veli. Сайт и письмо кладут их в кнопки. Кнопки в чатах и письмах берут только https://, поэтому удобнее page — страница подписки, где кнопки приложений уже есть. У панели по IP со своим сертификатом чужие приложения ссылку не проверят — там только Veli.
Остаток
left — что осталось: days — целые дни срока (у ждущего — его ожидание), bytes — байты периода; null у поля — без срока или без лимита. Это готовая строка для вашего интерфейса: «осталось 12 дней и 30 ГБ».
Что можно менять — поля change
days- Продлить на столько дней: от конца срока, у истёкшего — от сейчас; меньше нуля — укоротить. У ждущего первого подключения — ждать дольше или короче. У нового клиента дни стоят рядом с change, null — бессрочно. ±1–36500
until- Конец срока ровно, unix-время; 0 — бессрочно. Не вместе с days. В прошлом — срок кончается сейчас
start- first_use — срок пойдёт с первого запроса подписки приложением; now — ждущий начинает срок сейчас
name- Новое имя — только одному клиенту; id, ссылка, устройства и трафик остаются
disabled- true — отключить: ссылка не открывается, устройства сняты с узлов, срок идёт; false — включить
relink- true — новая ссылка: старая перестаёт работать, аккаунты обычных протоколов новые, устройства Veli остаются
devices- Сколько устройств можно, 1–100
speed- Мбит/с, 0–100000; 0 — без ограничения
limit, reset, zero- Лимит трафика в байтах, сброс, true — начать счёт с нуля
group- Группа по названию; пусто — без группы
external- Внешний ID, до 128 знаков; пусто — убрать
tags- Метки — весь список заново: до 20, каждая до 32 знаков
tags_add, tags_remove- Добавить и убрать метки, остальные остаются — удобно для многих сразу
meta- Поля вашей системы — все заново: до 20; ключ — латиница, цифры, _ . -, до 40 знаков; значение до 500
note, contact- Заметка до 300 знаков, контакт до 100
Слишком длинное значение не обрезается, а даёт ошибку bad с полем и пределом — {"error": "bad", "field": "change.devices", "max": 100}: иначе ваша система не узнала бы, что сохранилось не то. Новый клиент приходит в ответе целиком, вместе со ссылкой.
Фильтры и порядок
Без параметров GET clients отдаёт всех. Каждый параметр сужает список, их можно складывать.
external, tag- Внешний ID, метка
status- Через запятую: on,soon,limit,off,paused,waiting
group- Группа; пустое значение — без группы
q- Слово в имени, заметке, контакте или внешнем ID, без учёта регистра
until_before, until_after- Конец срока раньше, позже — unix-время; бессрочные не попадают ни туда, ни сюда
changed_since- Изменён вручную или системой с этого времени
devices- none, some, full — устройств нет, есть, все места заняты
used_over- Потрачено не меньше этой доли лимита, %
seen_before- Приложение не брало подписку с этого времени — или не брало ни разу
sort- name, until, added, used, changed; «-» впереди — наоборот
limit, cursor- Страница 1–1000 и курсор из next прошлой страницы
curl -s "$VELI/clients?status=soon&sort=until&limit=100" \
-H "Authorization: Bearer $VELI_TOKEN"curl -s "$VELI/clients?q=anna&tag=paid&group=europe" \
-H "Authorization: Bearer $VELI_TOKEN"curl -s "$VELI/clients?devices=full&used_over=90" \
-H "Authorization: Bearer $VELI_TOKEN"curl -s "$VELI/clients?seen_before=1791158400&status=on" \
-H "Authorization: Bearer $VELI_TOKEN"Страницы
- С limit ответ — {at, clients, total, next}: total — сколько всего под фильтром, next — курсор следующей страницы, null — эта последняя.
- Курсор — место в порядке, а не номер страницы: клиент, добавленный или удалённый между страницами, не сдвинет остальных — никто не придёт дважды и никто не потеряется.
- Следующую страницу просите с теми же фильтрами и sort, меняется только cursor.
{
"at": 1793754000,
"clients": [
{"id": "c_Ab3dE5fG7hJ9", "name": "order-88123", "status": "soon", "…": "…"}
],
"total": 412,
"next": "eyJrIjoxNzk0MDAwMDAwfQ"
}Чей это клиент
Человек прислал в поддержку ссылку или ключ устройства — найдите клиента. Ссылку можно целиком или только её секрет — часть после /s/.
curl -s "$VELI/clients/find" \
-H "Authorization: Bearer $VELI_TOKEN" \
-H "content-type: application/json" \
-d '{"link": "kV0pX7wQ2mLr9sTb"}'
curl -s "$VELI/clients/find" \
-H "Authorization: Bearer $VELI_TOKEN" \
-H "content-type: application/json" \
-d '{"device": "a1b2c3d4e5f6"}'Многие по фильтру
POST clients/bulk с filter вместо names меняет всех, кого берёт фильтр, — все или никто. Сначала посмотрите, кого заденет: dry: true отвечает числом и первыми 100 именами, ничего не меняя.
curl -s "$VELI/clients/bulk" \
-H "Authorization: Bearer $VELI_TOKEN" \
-H "content-type: application/json" \
-d '{"filter": {"tag": "promo-nov", "status": ["on", "soon"]}, "change": {"tags_add": ["thanked"]}, "dry": true}'
curl -s "$VELI/clients/bulk" \
-H "Authorization: Bearer $VELI_TOKEN" \
-H "content-type: application/json" \
-d '{"names": ["order-88123", "c_Ab3dE5fG7hJ9"], "change": {"group": "europe"}}'{
"done": 0,
"matched": 412,
"names": ["order-88123", "order-88124", "…"]
}- Пустой фильтр — bad: «всех» так не изменить случайно. Всем действующим — status: ["on", "soon"].
- tags_add и tags_remove меняют метки, не трогая остальные, — например, отметить тех, кому отправили письмо.
- Удалить многих — remove: true вместо change, нужно право «Всё». Удалённые 30 дней лежат в корзине.