Документация/Подключение/Своя панель/Вызовы·6 / 9

Вызовы

Тело и ответ — JSON, кроме QR-кода: он в SVG или PNG. Имя в адресе кодируется, как в encodeURIComponent, вместо имени можно id клиента. Нажмите на вызов — откроются параметры, тело, ответ и готовая команда. Адрес и токен удобно держать в переменных:

На вашем сервере
VELI=https://panel.example.com/Zq7mT2xP4vLc9wRbE5nK/api
VELI_TOKEN=veli_…

Токен, схема, MCP3

GET/meЭтот токен: название, права, срок, версия APIлюбой
Ответ 200application/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чтение
Ответ 200application/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" }
  }
}
Ответ 200application/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 прошлой страницы
Ответ 200application/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" }
Ответ 200application/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}: иначе ваша система не узнала бы, что сохранилось не то. Новый клиент приходит в ответе целиком, вместе со ссылкой.

Ответ 200application/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
Ответ 200application/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}: иначе ваша система не узнала бы, что сохранилось не то. Новый клиент приходит в ответе целиком, вместе со ссылкой.

Ответ 200application/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» вместо ссылки подписки
Ответ 200image/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.svg
GET/clients/{name}/statsТрафик клиента по днямчтение

Даты по UTC, от старой к сегодняшней; байты в обе стороны.

Параметры

nameв пути
Имя клиента или его id
daysв запросе
За сколько дней: 7, 30 или 90; без него — 30
Ответ 200application/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
Ответ 200application/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
Ответ 200application/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" }
Ответ 200application/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}: иначе ваша система не узнала бы, что сохранилось не то. Новый клиент приходит в ответе целиком, вместе со ссылкой.

Ответ 200application/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
Ответ 200application/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Удалённые клиентычтение
Ответ 200application/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 клиента в корзине
Ответ 200application/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 POST
POST/trash/{id}/removeУдалить из корзины насовсемвсё

Вернуть его больше нельзя.

Параметры

idв пути
id клиента в корзине
Ответ 200application/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 POST
POST/trash/clearОчистить корзинувсё

Все удалённые — насовсем. done — сколько их было.

Ответ 200application/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
Ответ 200application/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Сводка: клиенты, устройства, узлы, трафик, событиячтение
Ответ 200application/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
Ответ 200application/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Все устройства всех клиентовчтение
Ответ 200application/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 не бывает
Ответ 200application/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-время
Ответ 200application/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Все узлычтение
Ответ 200application/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" }
Ответ 200application/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в пути
Имя узла
Ответ 200application/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 }
}
Ответ 200application/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
Ответ 200application/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в пути
Имя узла
Ответ 200application/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Группы клиентовчтение
Ответ 200application/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
  }
}
Ответ 200application/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"]
  }
}
Ответ 200application/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в пути
Имя группы
Ответ 200application/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.json
Типы для TypeScript или готовый клиент на Python
npx 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 прошлой страницы
Кто истекает в ближайшие 3 дня — по сроку
curl -s "$VELI/clients?status=soon&sort=until&limit=100" \
  -H "Authorization: Bearer $VELI_TOKEN"
Поиск по слову среди оплаченных из группы europe
curl -s "$VELI/clients?q=anna&tag=paid&group=europe" \
  -H "Authorization: Bearer $VELI_TOKEN"
Все места заняты и трафик на 90 % — кому предложить продлить или добавить устройства
curl -s "$VELI/clients?devices=full&used_over=90" \
  -H "Authorization: Bearer $VELI_TOKEN"
Действующие, кто не подключался с 1 октября
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 дней лежат в корзине.