Documentation/Connecting/Your own panel/Calls·6 / 9
Calls
The body and the answer are JSON, but the QR code: it is SVG or PNG. A name in the address is encoded as by encodeURIComponent; a client's id may stand in place of the name. Click a call to see its parameters, body, answer and a ready command. The address and the token are handy in variables:
VELI=https://panel.example.com/Zq7mT2xP4vLc9wRbE5nK/api
VELI_TOKEN=veli_…Token, schema, MCP3
GET/meThis token: name, rights, term, API versionany
application/json{
"name": "cabinet",
"token": true,
"rights": "clients",
"until": 0,
"api": 1
}Errors
401 token- No token, or it is revoked or expired. veli token list on the panel's server shows whether it still exists
403 rights- The token lacks the rights: for example, only “All” can delete clients. GET me shows the rights
429 wait- Over 300 requests a minute on the token, or ten wrong tokens from this address within 15 minutes. Wait as many seconds as Retry-After says
500 db- The panel could not save the change — repeat, with the same key
curl -s "$VELI/me" \
-H "Authorization: Bearer $VELI_TOKEN"GET/openapi.jsonThe schema of the whole API, OpenAPI 3.1read
application/json{
"openapi": "3.1.0",
"info": { "title": "Veli panel API", "version": "1.12.0" },
"paths": {
"/clients": {
"get": {},
"post": {}
},
"…": {}
}
}Errors
401 token- No token, or it is revoked or expired. veli token list on the panel's server shows whether it still exists
403 rights- The token lacks the rights: for example, only “All” can delete clients. GET me shows the rights
429 wait- Over 300 requests a minute on the token, or ten wrong tokens from this address within 15 minutes. Wait as many seconds as Retry-After says
500 db- The panel could not save the change — repeat, with the same key
curl -s "$VELI/openapi.json" \
-H "Authorization: Bearer $VELI_TOKEN"POST/mcpThe panel for an AI agent over MCPany
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}" }
]
}
}Errors
401 token- No token, or it is revoked or expired. veli token list on the panel's server shows whether it still exists
403 rights- The token lacks the rights: for example, only “All” can delete clients. GET me shows the rights
429 wait- Over 300 requests a minute on the token, or ten wrong tokens from this address within 15 minutes. Wait as many seconds as Retry-After says
500 db- The panel could not save the change — repeat, with the same key
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"}}}'Clients12
GET/clientsClients: filters, order, pagesread
Parameters
externalin the query- An external ID — only the clients with it; a “:” in the address is %3A
tagin the query- A tag — only the clients with it
statusin the query- Statuses, comma-separated: on, soon, limit, off, paused, waiting
groupin the query- A group; an empty value — the clients with no group
qin the query- A word in the name, note, contact or external ID, case aside
until_beforein the query- The term ends before this, unix time; the ones with no end are left out
until_afterin the query- The term ends after this, unix time; the ones with no end are left out
changed_sincein the query- Changed by hand or by a system since this time — to compare with your database
devicesin the query- none — no devices, some — some, full — all places taken
used_overin the query- At least this share of the limit used, %; the clients with no limit are left out
seen_beforein the query- The app has not taken the subscription since this time — or never has
sortin the query- name, until, added, used or changed; a “-” in front — the other way
limitin the query- Clients per page, 1–1000; without it — all at once
cursorin the query- next of the last page
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"
}The client's fields
id- c_ and 12 characters — for ever: renaming does not change it. Works in the path in place of the name: clients/c_Ab3dE5fG7hJ9. Keep it on your side, not the name
name- The name, 1–40 characters, each client's own; not of the form c_ and 12 characters — that is how ids look
external- The external ID — your ID of the client; empty — none. It is not unique: one person may buy two subscriptions, so the search gives a list
tags- Tags
status- on, soon, limit, off, paused or waiting — see above
until- The term's end, unix time; 0 — no end, or the term still waits for the first connection
wait, first- How many seconds of the term start at the first connection (0 — no waiting); when an app first took the subscription (0 — not yet)
left- What is left: days and bytes; null — no term and no limit
devices, held, veli- How many devices are allowed, how many are taken by all apps, how many of them Veli
speed- Veli's speed each way, Mbit/s; 0 — no limit
limit, reset, used, next- The traffic limit in bytes (0 — no limit), the reset — never, day, week or month by UTC, the period's use, the next period's start
group- The group; empty — none
bytes- The traffic of all time
seen, changed- The app's last request for the subscription (to within 10 minutes, 0 — none); the last change by hand or by a system
note, contact, added- Note, contact, when added
Errors
401 token- No token, or it is revoked or expired. veli token list on the panel's server shows whether it still exists
403 rights- The token lacks the rights: for example, only “All” can delete clients. GET me shows the rights
429 wait- Over 300 requests a minute on the token, or ten wrong tokens from this address within 15 minutes. Wait as many seconds as Retry-After says
500 db- The panel could not save the change — repeat, with the same key
curl -s "$VELI/clients?status=on,soon&sort=-until&limit=100" \
-H "Authorization: Bearer $VELI_TOKEN"POST/clients/findA client by a link or a device; a read-only token sees no link in the answerread
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"
}
}The client's fields
id- c_ and 12 characters — for ever: renaming does not change it. Works in the path in place of the name: clients/c_Ab3dE5fG7hJ9. Keep it on your side, not the name
name- The name, 1–40 characters, each client's own; not of the form c_ and 12 characters — that is how ids look
external- The external ID — your ID of the client; empty — none. It is not unique: one person may buy two subscriptions, so the search gives a list
tags- Tags
status- on, soon, limit, off, paused or waiting — see above
until- The term's end, unix time; 0 — no end, or the term still waits for the first connection
wait, first- How many seconds of the term start at the first connection (0 — no waiting); when an app first took the subscription (0 — not yet)
left- What is left: days and bytes; null — no term and no limit
devices, held, veli- How many devices are allowed, how many are taken by all apps, how many of them Veli
speed- Veli's speed each way, Mbit/s; 0 — no limit
limit, reset, used, next- The traffic limit in bytes (0 — no limit), the reset — never, day, week or month by UTC, the period's use, the next period's start
group- The group; empty — none
bytes- The traffic of all time
seen, changed- The app's last request for the subscription (to within 10 minutes, 0 — none); the last change by hand or by a system
note, contact, added- Note, contact, when added
at- When the answer was made, unix time
link- The subscription's link — a secret: given to the client alone
page- The subscription page for a browser, with app buttons
apps- “Add to …” links by app
list- The devices: id, kind — veli (a Veli key) or app (another app's HWID), os, added; a Veli one also has bytes
lines- The ordinary protocols' lines by node: node, kind, line
meta- Your system's fields
disabled- true — the client is turned off
Errors
404 none- Something that does not exist, or an unknown call
401 token- No token, or it is revoked or expired. veli token list on the panel's server shows whether it still exists
403 rights- The token lacks the rights: for example, only “All” can delete clients. GET me shows the rights
429 wait- Over 300 requests a minute on the token, or ten wrong tokens from this address within 15 minutes. Wait as many seconds as Retry-After says
500 db- The panel could not save the change — repeat, with the same key
curl -s "$VELI/clients/find" \
-H "Authorization: Bearer $VELI_TOKEN" \
-H "content-type: application/json" \
-d '{"link":"https://panel.example.com/s/kV0pX7wQ2mLr9sTb"}'POST/clientsAdd a clientclients
application/json{
"name": "order-88123",
"days": 30,
"change": {
"devices": 3,
"external": "88123",
"tags": ["paid", "month"],
"meta": { "order": "88123", "source": "shop" }
}
}The fields of change — each as you like
days- Extend by so many days: from the term's end, for an expired one from now; below zero — shorten. For one waiting for the first connection — wait longer or shorter. A new client's days stand beside change, null — no end. ±1–36500
until- The term's exact end, unix time; 0 — no end. Not together with days. In the past — the term ends now
start- first_use — the term starts at the app's first request for the subscription; now — a waiting one starts its term now
name- A new name — for one client only; the id, link, devices and traffic stay
disabled- true — turn off: the link does not open, the devices are taken off the nodes, the term runs; false — turn on
relink- true — a new link: the old one stops working, the ordinary protocols' accounts are new, Veli devices stay
devices- How many devices are allowed, 1–100
speed- Mbit/s, 0–100000; 0 — no limit
limit, reset, zero- The traffic limit in bytes, the reset, true — start the count from nothing
group- The group by name; empty — none
external- The external ID, up to 128 characters; empty — remove it
tags- Tags — the whole list anew: up to 20, each up to 32 characters
tags_add, tags_remove- Add and remove tags, the rest stay — handy for many at once
meta- Your system's fields — all anew: up to 20; a key of Latin letters, digits, _ . -, up to 40 characters; a value up to 500
note, contact- A note up to 300 characters, a contact up to 100
A value too long is not cut but gives the bad error with the field and the limit — {"error": "bad", "field": "change.devices", "max": 100}: else your system would not learn that something else was saved. A new client comes back whole in the answer, with the link.
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"
}
}
}The client's fields
id- c_ and 12 characters — for ever: renaming does not change it. Works in the path in place of the name: clients/c_Ab3dE5fG7hJ9. Keep it on your side, not the name
name- The name, 1–40 characters, each client's own; not of the form c_ and 12 characters — that is how ids look
external- The external ID — your ID of the client; empty — none. It is not unique: one person may buy two subscriptions, so the search gives a list
tags- Tags
status- on, soon, limit, off, paused or waiting — see above
until- The term's end, unix time; 0 — no end, or the term still waits for the first connection
wait, first- How many seconds of the term start at the first connection (0 — no waiting); when an app first took the subscription (0 — not yet)
left- What is left: days and bytes; null — no term and no limit
devices, held, veli- How many devices are allowed, how many are taken by all apps, how many of them Veli
speed- Veli's speed each way, Mbit/s; 0 — no limit
limit, reset, used, next- The traffic limit in bytes (0 — no limit), the reset — never, day, week or month by UTC, the period's use, the next period's start
group- The group; empty — none
bytes- The traffic of all time
seen, changed- The app's last request for the subscription (to within 10 minutes, 0 — none); the last change by hand or by a system
note, contact, added- Note, contact, when added
at- When the answer was made, unix time
link- The subscription's link — a secret: given to the client alone
page- The subscription page for a browser, with app buttons
apps- “Add to …” links by app
list- The devices: id, kind — veli (a Veli key) or app (another app's HWID), os, added; a Veli one also has bytes
lines- The ordinary protocols' lines by node: node, kind, line
meta- Your system's fields
disabled- true — the client is turned off
Errors
400 name- The name is empty, longer than 40 characters, has control characters, is of the form c_ and 12 characters or is a word of the API: bulk, find
400 taken- That name is taken
400 bad- A value out of bounds, an unknown group or node. field names the field, max the limit
409 idempotency- This Idempotency-Key was already used by another request. A key is for one action: extending and creating get different keys
401 token- No token, or it is revoked or expired. veli token list on the panel's server shows whether it still exists
403 rights- The token lacks the rights: for example, only “All” can delete clients. GET me shows the rights
429 wait- Over 300 requests a minute on the token, or ten wrong tokens from this address within 15 minutes. Wait as many seconds as Retry-After says
500 db- The panel could not save the change — repeat, with the same key
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}The whole client: link, app buttons, devices, fields. A read-only token sees no link or buttonsread
Parameters
namein the path- The client's name or 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"
}
}The client's fields
id- c_ and 12 characters — for ever: renaming does not change it. Works in the path in place of the name: clients/c_Ab3dE5fG7hJ9. Keep it on your side, not the name
name- The name, 1–40 characters, each client's own; not of the form c_ and 12 characters — that is how ids look
external- The external ID — your ID of the client; empty — none. It is not unique: one person may buy two subscriptions, so the search gives a list
tags- Tags
status- on, soon, limit, off, paused or waiting — see above
until- The term's end, unix time; 0 — no end, or the term still waits for the first connection
wait, first- How many seconds of the term start at the first connection (0 — no waiting); when an app first took the subscription (0 — not yet)
left- What is left: days and bytes; null — no term and no limit
devices, held, veli- How many devices are allowed, how many are taken by all apps, how many of them Veli
speed- Veli's speed each way, Mbit/s; 0 — no limit
limit, reset, used, next- The traffic limit in bytes (0 — no limit), the reset — never, day, week or month by UTC, the period's use, the next period's start
group- The group; empty — none
bytes- The traffic of all time
seen, changed- The app's last request for the subscription (to within 10 minutes, 0 — none); the last change by hand or by a system
note, contact, added- Note, contact, when added
at- When the answer was made, unix time
link- The subscription's link — a secret: given to the client alone
page- The subscription page for a browser, with app buttons
apps- “Add to …” links by app
list- The devices: id, kind — veli (a Veli key) or app (another app's HWID), os, added; a Veli one also has bytes
lines- The ordinary protocols' lines by node: node, kind, line
meta- Your system's fields
disabled- true — the client is turned off
Errors
404 none- Something that does not exist, or an unknown call
401 token- No token, or it is revoked or expired. veli token list on the panel's server shows whether it still exists
403 rights- The token lacks the rights: for example, only “All” can delete clients. GET me shows the rights
429 wait- Over 300 requests a minute on the token, or ten wrong tokens from this address within 15 minutes. Wait as many seconds as Retry-After says
500 db- The panel could not save the change — repeat, with the same key
curl -s "$VELI/clients/order-88123" \
-H "Authorization: Bearer $VELI_TOKEN"POST/clients/{name}Change: extend, turn off, rename, a new link, the limit, the fieldsclients
Parameters
namein the path- The client's name or id
application/json{
"change": {
"days": 30,
"devices": 5,
"tags_add": ["vip"]
}
}The fields of change — each as you like
days- Extend by so many days: from the term's end, for an expired one from now; below zero — shorten. For one waiting for the first connection — wait longer or shorter. A new client's days stand beside change, null — no end. ±1–36500
until- The term's exact end, unix time; 0 — no end. Not together with days. In the past — the term ends now
start- first_use — the term starts at the app's first request for the subscription; now — a waiting one starts its term now
name- A new name — for one client only; the id, link, devices and traffic stay
disabled- true — turn off: the link does not open, the devices are taken off the nodes, the term runs; false — turn on
relink- true — a new link: the old one stops working, the ordinary protocols' accounts are new, Veli devices stay
devices- How many devices are allowed, 1–100
speed- Mbit/s, 0–100000; 0 — no limit
limit, reset, zero- The traffic limit in bytes, the reset, true — start the count from nothing
group- The group by name; empty — none
external- The external ID, up to 128 characters; empty — remove it
tags- Tags — the whole list anew: up to 20, each up to 32 characters
tags_add, tags_remove- Add and remove tags, the rest stay — handy for many at once
meta- Your system's fields — all anew: up to 20; a key of Latin letters, digits, _ . -, up to 40 characters; a value up to 500
note, contact- A note up to 300 characters, a contact up to 100
A value too long is not cut but gives the bad error with the field and the limit — {"error": "bad", "field": "change.devices", "max": 100}: else your system would not learn that something else was saved. A new client comes back whole in the answer, with the link.
application/json{ "done": 1 }Errors
400 none- No client, node or group by that name
400 bad- A value out of bounds, an unknown group or node. field names the field, max the limit
400 taken- That name is taken
409 idempotency- This Idempotency-Key was already used by another request. A key is for one action: extending and creating get different keys
401 token- No token, or it is revoked or expired. veli token list on the panel's server shows whether it still exists
403 rights- The token lacks the rights: for example, only “All” can delete clients. GET me shows the rights
429 wait- Over 300 requests a minute on the token, or ten wrong tokens from this address within 15 minutes. Wait as many seconds as Retry-After says
500 db- The panel could not save the change — repeat, with the same key
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}/qrThe link's QR code: SVG or PNGclients
Parameters
namein the path- The client's name or id
formatin the query- svg or png; without it — svg
sizein the query- The PNG's side in pixels, 128–2048; without it — 512
ofin the query- veli — a QR of the “Add to Veli” link in place of the subscription's link
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>Errors
404 none- Something that does not exist, or an unknown call
401 token- No token, or it is revoked or expired. veli token list on the panel's server shows whether it still exists
403 rights- The token lacks the rights: for example, only “All” can delete clients. GET me shows the rights
429 wait- Over 300 requests a minute on the token, or ten wrong tokens from this address within 15 minutes. Wait as many seconds as Retry-After says
500 db- The panel could not save the change — repeat, with the same key
curl -s "$VELI/clients/order-88123/qr?format=svg" \
-H "Authorization: Bearer $VELI_TOKEN" -o qr.svgGET/clients/{name}/statsThe client's traffic by dayread
Dates by UTC, from the oldest to today; bytes both ways.
Parameters
namein the path- The client's name or id
daysin the query- Over how many days: 7, 30 or 90; without it — 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]
}Errors
404 none- Something that does not exist, or an unknown call
401 token- No token, or it is revoked or expired. veli token list on the panel's server shows whether it still exists
403 rights- The token lacks the rights: for example, only “All” can delete clients. GET me shows the rights
429 wait- Over 300 requests a minute on the token, or ten wrong tokens from this address within 15 minutes. Wait as many seconds as Retry-After says
500 db- The panel could not save the change — repeat, with the same key
curl -s "$VELI/clients/order-88123/stats?days=7" \
-H "Authorization: Bearer $VELI_TOKEN"GET/clients/{name}/historyThe client's historyread
Parameters
namein the path- The client's name or 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
}
]
}Errors
404 none- Something that does not exist, or an unknown call
401 token- No token, or it is revoked or expired. veli token list on the panel's server shows whether it still exists
403 rights- The token lacks the rights: for example, only “All” can delete clients. GET me shows the rights
429 wait- Over 300 requests a minute on the token, or ten wrong tokens from this address within 15 minutes. Wait as many seconds as Retry-After says
500 db- The panel could not save the change — repeat, with the same key
curl -s "$VELI/clients/order-88123/history" \
-H "Authorization: Bearer $VELI_TOKEN"GET/clients/{name}/diagnosisWhy a client may not connectread
Parameters
namein the path- The client's name or 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 }
}Errors
404 none- Something that does not exist, or an unknown call
401 token- No token, or it is revoked or expired. veli token list on the panel's server shows whether it still exists
403 rights- The token lacks the rights: for example, only “All” can delete clients. GET me shows the rights
429 wait- Over 300 requests a minute on the token, or ten wrong tokens from this address within 15 minutes. Wait as many seconds as Retry-After says
500 db- The panel could not save the change — repeat, with the same key
curl -s "$VELI/clients/order-88123/diagnosis" \
-H "Authorization: Bearer $VELI_TOKEN"POST/clients/{name}/unbindUnbind a deviceclients
device — an id from the client's list. The place is free at once: another device can take it.
Parameters
namein the path- The client's name or id
application/json{ "device": "a1b2c3d4e5f6" }application/json{ "done": 1 }Errors
400 none- No client, node or group by that name
401 token- No token, or it is revoked or expired. veli token list on the panel's server shows whether it still exists
403 rights- The token lacks the rights: for example, only “All” can delete clients. GET me shows the rights
429 wait- Over 300 requests a minute on the token, or ten wrong tokens from this address within 15 minutes. Wait as many seconds as Retry-After says
500 db- The panel could not save the change — repeat, with the same key
curl -s "$VELI/clients/order-88123/unbind" \
-H "Authorization: Bearer $VELI_TOKEN" \
-H "content-type: application/json" \
-d '{"device":"a1b2c3d4e5f6"}'POST/clients/bulkChange many at once — all or noneclients
application/json{
"filter": {
"status": ["on", "soon"],
"tag": "paid"
},
"change": { "days": 3 },
"dry": true
}The fields of change — each as you like
days- Extend by so many days: from the term's end, for an expired one from now; below zero — shorten. For one waiting for the first connection — wait longer or shorter. A new client's days stand beside change, null — no end. ±1–36500
until- The term's exact end, unix time; 0 — no end. Not together with days. In the past — the term ends now
start- first_use — the term starts at the app's first request for the subscription; now — a waiting one starts its term now
name- A new name — for one client only; the id, link, devices and traffic stay
disabled- true — turn off: the link does not open, the devices are taken off the nodes, the term runs; false — turn on
relink- true — a new link: the old one stops working, the ordinary protocols' accounts are new, Veli devices stay
devices- How many devices are allowed, 1–100
speed- Mbit/s, 0–100000; 0 — no limit
limit, reset, zero- The traffic limit in bytes, the reset, true — start the count from nothing
group- The group by name; empty — none
external- The external ID, up to 128 characters; empty — remove it
tags- Tags — the whole list anew: up to 20, each up to 32 characters
tags_add, tags_remove- Add and remove tags, the rest stay — handy for many at once
meta- Your system's fields — all anew: up to 20; a key of Latin letters, digits, _ . -, up to 40 characters; a value up to 500
note, contact- A note up to 300 characters, a contact up to 100
A value too long is not cut but gives the bad error with the field and the limit — {"error": "bad", "field": "change.devices", "max": 100}: else your system would not learn that something else was saved. A new client comes back whole in the answer, with the link.
application/json{
"done": 0,
"matched": 412,
"names": ["order-88123", "order-88124", "…"]
}Errors
400 none- No client, node or group by that name
400 bad- A value out of bounds, an unknown group or node. field names the field, max the limit
403 rights- The token lacks the rights: for example, only “All” can delete clients. GET me shows the rights
409 idempotency- This Idempotency-Key was already used by another request. A key is for one action: extending and creating get different keys
401 token- No token, or it is revoked or expired. veli token list on the panel's server shows whether it still exists
429 wait- Over 300 requests a minute on the token, or ten wrong tokens from this address within 15 minutes. Wait as many seconds as Retry-After says
500 db- The panel could not save the change — repeat, with the same key
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}/removeDelete a client — to the trash for 30 daysall
Parameters
namein the path- The client's name or id
application/json{ "done": 1 }Errors
400 none- No client, node or group by that name
401 token- No token, or it is revoked or expired. veli token list on the panel's server shows whether it still exists
403 rights- The token lacks the rights: for example, only “All” can delete clients. GET me shows the rights
429 wait- Over 300 requests a minute on the token, or ten wrong tokens from this address within 15 minutes. Wait as many seconds as Retry-After says
500 db- The panel could not save the change — repeat, with the same key
curl -s "$VELI/clients/order-88123/remove" \
-H "Authorization: Bearer $VELI_TOKEN" -X POSTTrash4
GET/trashDeleted clientsread
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
}
]
}Errors
401 token- No token, or it is revoked or expired. veli token list on the panel's server shows whether it still exists
403 rights- The token lacks the rights: for example, only “All” can delete clients. GET me shows the rights
429 wait- Over 300 requests a minute on the token, or ten wrong tokens from this address within 15 minutes. Wait as many seconds as Retry-After says
500 db- The panel could not save the change — repeat, with the same key
curl -s "$VELI/trash" \
-H "Authorization: Bearer $VELI_TOKEN"POST/trash/{id}/restoreRestore from the trashall
With the same link and devices. The name is taken — taken. The answer is the whole client.
Parameters
idin the path- The client's id in the trash
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"
}
}
}Errors
400 none- No client, node or group by that name
400 taken- That name is taken
401 token- No token, or it is revoked or expired. veli token list on the panel's server shows whether it still exists
403 rights- The token lacks the rights: for example, only “All” can delete clients. GET me shows the rights
429 wait- Over 300 requests a minute on the token, or ten wrong tokens from this address within 15 minutes. Wait as many seconds as Retry-After says
500 db- The panel could not save the change — repeat, with the same key
curl -s "$VELI/trash/c_Ab3dE5fG7hJ9/restore" \
-H "Authorization: Bearer $VELI_TOKEN" -X POSTPOST/trash/{id}/removeDelete from the trash for goodall
It cannot be restored any more.
Parameters
idin the path- The client's id in the trash
application/json{ "done": 1 }Errors
400 none- No client, node or group by that name
401 token- No token, or it is revoked or expired. veli token list on the panel's server shows whether it still exists
403 rights- The token lacks the rights: for example, only “All” can delete clients. GET me shows the rights
429 wait- Over 300 requests a minute on the token, or ten wrong tokens from this address within 15 minutes. Wait as many seconds as Retry-After says
500 db- The panel could not save the change — repeat, with the same key
curl -s "$VELI/trash/c_Ab3dE5fG7hJ9/remove" \
-H "Authorization: Bearer $VELI_TOKEN" -X POSTPOST/trash/clearEmpty the trashall
All the deleted ones, for good. done — how many there were.
application/json{ "done": 4 }Errors
401 token- No token, or it is revoked or expired. veli token list on the panel's server shows whether it still exists
403 rights- The token lacks the rights: for example, only “All” can delete clients. GET me shows the rights
429 wait- Over 300 requests a minute on the token, or ten wrong tokens from this address within 15 minutes. Wait as many seconds as Retry-After says
500 db- The panel could not save the change — repeat, with the same key
curl -s "$VELI/trash/clear" \
-H "Authorization: Bearer $VELI_TOKEN" -X POSTEvent feed1
GET/eventsThe event feed: for a system with no address of its ownread
Parameters
afterin the query- last of the last answer; 0 — from the feed's start
waitin the query- How many seconds to wait if there is nothing new: 0–25
typesin the query- Only these events, comma-separated
limitin the query- Events at a time, 1–1000; without it — 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
}Errors
401 token- No token, or it is revoked or expired. veli token list on the panel's server shows whether it still exists
403 rights- The token lacks the rights: for example, only “All” can delete clients. GET me shows the rights
429 wait- Over 300 requests a minute on the token, or ten wrong tokens from this address within 15 minutes. Wait as many seconds as Retry-After says
500 db- The panel could not save the change — repeat, with the same key
curl -s "$VELI/events?after=1040&wait=25&types=client.added,client.expired&limit=100" \
-H "Authorization: Bearer $VELI_TOKEN"Overview, statistics, devices5
GET/overviewThe summary: clients, devices, nodes, traffic, eventsread
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 }
]
}Errors
401 token- No token, or it is revoked or expired. veli token list on the panel's server shows whether it still exists
403 rights- The token lacks the rights: for example, only “All” can delete clients. GET me shows the rights
429 wait- Over 300 requests a minute on the token, or ten wrong tokens from this address within 15 minutes. Wait as many seconds as Retry-After says
500 db- The panel could not save the change — repeat, with the same key
curl -s "$VELI/overview" \
-H "Authorization: Bearer $VELI_TOKEN"GET/statsThe panel's traffic by day: in all and by noderead
Parameters
daysin the query- Over how many days: 7, 30 or 90; without it — 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
}Errors
401 token- No token, or it is revoked or expired. veli token list on the panel's server shows whether it still exists
403 rights- The token lacks the rights: for example, only “All” can delete clients. GET me shows the rights
429 wait- Over 300 requests a minute on the token, or ten wrong tokens from this address within 15 minutes. Wait as many seconds as Retry-After says
500 db- The panel could not save the change — repeat, with the same key
curl -s "$VELI/stats?days=7" \
-H "Authorization: Bearer $VELI_TOKEN"GET/devicesAll the devices of all the clientsread
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 }
}Errors
401 token- No token, or it is revoked or expired. veli token list on the panel's server shows whether it still exists
403 rights- The token lacks the rights: for example, only “All” can delete clients. GET me shows the rights
429 wait- Over 300 requests a minute on the token, or ten wrong tokens from this address within 15 minutes. Wait as many seconds as Retry-After says
500 db- The panel could not save the change — repeat, with the same key
curl -s "$VELI/devices" \
-H "Authorization: Bearer $VELI_TOKEN"GET/requestsThe last requests for a subscriptionread
Parameters
clientin the query- Only this client's requests
limitin the query- How many of the last ones; without it — 200, never more than 2000
application/json{
"at": 1793754000,
"requests": [
{
"at": 1793753700,
"client": "order-88123",
"ip": "198.51.100.7",
"app": "Happ",
"code": 200,
"page": false
}
]
}Errors
401 token- No token, or it is revoked or expired. veli token list on the panel's server shows whether it still exists
403 rights- The token lacks the rights: for example, only “All” can delete clients. GET me shows the rights
429 wait- Over 300 requests a minute on the token, or ten wrong tokens from this address within 15 minutes. Wait as many seconds as Retry-After says
500 db- The panel could not save the change — repeat, with the same key
curl -s "$VELI/requests?client=order-88123&limit=50" \
-H "Authorization: Bearer $VELI_TOKEN"GET/logThe action log: what the tokens and the console did, and from whereall
Parameters
whoin the query- A token's name, or root — only its actions
whatin the query- clients, nodes, groups, integrations, plugins or backups
qin the query- Words in an entry, a client's name for example
beforein the query- Older than this, unix time: the next page
afterin the query- Newer than this, unix time
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": []
}
]
}Errors
401 token- No token, or it is revoked or expired. veli token list on the panel's server shows whether it still exists
403 rights- The token lacks the rights: for example, only “All” can delete clients. GET me shows the rights
429 wait- Over 300 requests a minute on the token, or ten wrong tokens from this address within 15 minutes. Wait as many seconds as Retry-After says
500 db- The panel could not save the change — repeat, with the same key
curl -s "$VELI/log?who=cabinet&what=clients" \
-H "Authorization: Bearer $VELI_TOKEN"Nodes6
GET/nodesAll the nodesread
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 }
]
}Errors
401 token- No token, or it is revoked or expired. veli token list on the panel's server shows whether it still exists
403 rights- The token lacks the rights: for example, only “All” can delete clients. GET me shows the rights
429 wait- Over 300 requests a minute on the token, or ten wrong tokens from this address within 15 minutes. Wait as many seconds as Retry-After says
500 db- The panel could not save the change — repeat, with the same key
curl -s "$VELI/nodes" \
-H "Authorization: Bearer $VELI_TOKEN"POST/nodesAdd a nodeall
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…"
}Errors
400 name- The name is empty, longer than 40 characters, has control characters, is of the form c_ and 12 characters or is a word of the API: bulk, find
400 taken- That name is taken
400 bad- A value out of bounds, an unknown group or node. field names the field, max the limit
401 token- No token, or it is revoked or expired. veli token list on the panel's server shows whether it still exists
403 rights- The token lacks the rights: for example, only “All” can delete clients. GET me shows the rights
429 wait- Over 300 requests a minute on the token, or ten wrong tokens from this address within 15 minutes. Wait as many seconds as Retry-After says
500 db- The panel could not save the change — repeat, with the same key
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}One noderead
Parameters
namein the path- The node's 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"
}Errors
404 none- Something that does not exist, or an unknown call
401 token- No token, or it is revoked or expired. veli token list on the panel's server shows whether it still exists
403 rights- The token lacks the rights: for example, only “All” can delete clients. GET me shows the rights
429 wait- Over 300 requests a minute on the token, or ten wrong tokens from this address within 15 minutes. Wait as many seconds as Retry-After says
500 db- The panel could not save the change — repeat, with the same key
curl -s "$VELI/nodes/de-1" \
-H "Authorization: Bearer $VELI_TOKEN"POST/nodes/{name}Change a nodeall
Parameters
namein the path- The node's name
application/json{
"change": { "address": "de1.example.com", "disabled": false }
}application/json{ "done": 1 }Errors
400 none- No client, node or group by that name
400 bad- A value out of bounds, an unknown group or node. field names the field, max the limit
400 main- The mini-panel's main node is never turned off or taken away
401 token- No token, or it is revoked or expired. veli token list on the panel's server shows whether it still exists
403 rights- The token lacks the rights: for example, only “All” can delete clients. GET me shows the rights
429 wait- Over 300 requests a minute on the token, or ten wrong tokens from this address within 15 minutes. Wait as many seconds as Retry-After says
500 db- The panel could not save the change — repeat, with the same key
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}/statsThe node's traffic by dayread
As a client's: dates by UTC, bytes both ways.
Parameters
namein the path- The node's name
daysin the query- Over how many days: 7, 30 or 90; without it — 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]
}Errors
404 none- Something that does not exist, or an unknown call
401 token- No token, or it is revoked or expired. veli token list on the panel's server shows whether it still exists
403 rights- The token lacks the rights: for example, only “All” can delete clients. GET me shows the rights
429 wait- Over 300 requests a minute on the token, or ten wrong tokens from this address within 15 minutes. Wait as many seconds as Retry-After says
500 db- The panel could not save the change — repeat, with the same key
curl -s "$VELI/nodes/de-1/stats?days=7" \
-H "Authorization: Bearer $VELI_TOKEN"POST/nodes/{name}/removeTake a node awayall
Its lines leave the subscriptions. The mini-panel's main node is never taken away — main.
Parameters
namein the path- The node's name
application/json{ "done": 1 }Errors
400 none- No client, node or group by that name
400 main- The mini-panel's main node is never turned off or taken away
401 token- No token, or it is revoked or expired. veli token list on the panel's server shows whether it still exists
403 rights- The token lacks the rights: for example, only “All” can delete clients. GET me shows the rights
429 wait- Over 300 requests a minute on the token, or ten wrong tokens from this address within 15 minutes. Wait as many seconds as Retry-After says
500 db- The panel could not save the change — repeat, with the same key
curl -s "$VELI/nodes/de-2/remove" \
-H "Authorization: Bearer $VELI_TOKEN" -X POSTGroups4
GET/groupsThe groups of clientsread
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" }
]
}Errors
401 token- No token, or it is revoked or expired. veli token list on the panel's server shows whether it still exists
403 rights- The token lacks the rights: for example, only “All” can delete clients. GET me shows the rights
429 wait- Over 300 requests a minute on the token, or ten wrong tokens from this address within 15 minutes. Wait as many seconds as Retry-After says
500 db- The panel could not save the change — repeat, with the same key
curl -s "$VELI/groups" \
-H "Authorization: Bearer $VELI_TOKEN"POST/groupsAdd a groupall
nodes and protocols — from the lists nodes and kinds of “GET groups”; null — all.
application/json{
"group": {
"name": "europe",
"nodes": ["de-1", "nl-1"],
"protocols": null
}
}application/json{ "done": 1 }Errors
400 name- The name is empty, longer than 40 characters, has control characters, is of the form c_ and 12 characters or is a word of the API: bulk, find
400 taken- That name is taken
400 bad- A value out of bounds, an unknown group or node. field names the field, max the limit
401 token- No token, or it is revoked or expired. veli token list on the panel's server shows whether it still exists
403 rights- The token lacks the rights: for example, only “All” can delete clients. GET me shows the rights
429 wait- Over 300 requests a minute on the token, or ten wrong tokens from this address within 15 minutes. Wait as many seconds as Retry-After says
500 db- The panel could not save the change — repeat, with the same key
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}Change a groupall
The body is the whole group, as when adding it.
Parameters
namein the path- The group's name
application/json{
"group": {
"name": "europe",
"nodes": null,
"protocols": ["veli"]
}
}application/json{ "done": 1 }Errors
400 none- No client, node or group by that name
400 bad- A value out of bounds, an unknown group or node. field names the field, max the limit
401 token- No token, or it is revoked or expired. veli token list on the panel's server shows whether it still exists
403 rights- The token lacks the rights: for example, only “All” can delete clients. GET me shows the rights
429 wait- Over 300 requests a minute on the token, or ten wrong tokens from this address within 15 minutes. Wait as many seconds as Retry-After says
500 db- The panel could not save the change — repeat, with the same key
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}/removeDelete a groupall
Its clients stay — with no group, with all the nodes and protocols. done — how many were in it.
Parameters
namein the path- The group's name
application/json{ "done": 42 }Errors
400 none- No client, node or group by that name
401 token- No token, or it is revoked or expired. veli token list on the panel's server shows whether it still exists
403 rights- The token lacks the rights: for example, only “All” can delete clients. GET me shows the rights
429 wait- Over 300 requests a minute on the token, or ten wrong tokens from this address within 15 minutes. Wait as many seconds as Retry-After says
500 db- The panel could not save the change — repeat, with the same key
curl -s "$VELI/groups/europe/remove" \
-H "Authorization: Bearer $VELI_TOKEN" -X POSTThe OpenAPI schema and your own client
The panel gives the schema of the whole API, OpenAPI 3.1. A test of the panel holds it to the code: there is no call outside the schema. A client in your language is built from it; Postman, Insomnia, n8n and other systems take it.
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 clientTokens and webhooks are not made through the API: only the console makes them (veli token add, veli webhook add).
Statuses
on- Works: the term runs, there is traffic
soon- Works, but the term ends within 3 days — time to remind
limit- The period's traffic is used up: the link opens, but no connecting until the reset or a new limit
off- The term ended: the link opens and says “Subscription ended”, connecting is not possible. Extended — it connects again
paused- Turned off by hand or by a system; the term runs meanwhile
waiting- The term waits for the first connection: a gift or “bought in advance”
In the list and in the events
id- c_ and 12 characters — for ever: renaming does not change it. Works in the path in place of the name: clients/c_Ab3dE5fG7hJ9. Keep it on your side, not the name
name- The name, 1–40 characters, each client's own; not of the form c_ and 12 characters — that is how ids look
external- The external ID — your ID of the client; empty — none. It is not unique: one person may buy two subscriptions, so the search gives a list
tags- Tags
status- on, soon, limit, off, paused or waiting — see above
until- The term's end, unix time; 0 — no end, or the term still waits for the first connection
wait, first- How many seconds of the term start at the first connection (0 — no waiting); when an app first took the subscription (0 — not yet)
left- What is left: days and bytes; null — no term and no limit
devices, held, veli- How many devices are allowed, how many are taken by all apps, how many of them Veli
speed- Veli's speed each way, Mbit/s; 0 — no limit
limit, reset, used, next- The traffic limit in bytes (0 — no limit), the reset — never, day, week or month by UTC, the period's use, the next period's start
group- The group; empty — none
bytes- The traffic of all time
seen, changed- The app's last request for the subscription (to within 10 minutes, 0 — none); the last change by hand or by a system
note, contact, added- Note, contact, when added
Only for one client — GET clients/<name>
at- When the answer was made, unix time
link- The subscription's link — a secret: given to the client alone
page- The subscription page for a browser, with app buttons
apps- “Add to …” links by app
list- The devices: id, kind — veli (a Veli key) or app (another app's HWID), os, added; a Veli one also has bytes
lines- The ordinary protocols' lines by node: node, kind, line
meta- Your system's fields
disabled- true — the client is turned off
App buttons
apps — ready “Add to …” links: Happ, v2rayNG, Hiddify, Streisand, sing-box, Clash, Shadowrocket, v2RayTun and Veli. A site or a letter puts them into buttons. Buttons in chats and letters take only https://, so page is handier — the subscription page, which already has the app buttons. For a panel by IP with its own certificate, other apps will not check the link — there is only Veli.
What is left
left — what remains: days — whole days of the term (for a waiting one, its wait), bytes — the period's bytes; null in a field — no term or no limit. It is a ready line for your interface: “12 days and 30 GB left”.
What can be changed — the fields of change
days- Extend by so many days: from the term's end, for an expired one from now; below zero — shorten. For one waiting for the first connection — wait longer or shorter. A new client's days stand beside change, null — no end. ±1–36500
until- The term's exact end, unix time; 0 — no end. Not together with days. In the past — the term ends now
start- first_use — the term starts at the app's first request for the subscription; now — a waiting one starts its term now
name- A new name — for one client only; the id, link, devices and traffic stay
disabled- true — turn off: the link does not open, the devices are taken off the nodes, the term runs; false — turn on
relink- true — a new link: the old one stops working, the ordinary protocols' accounts are new, Veli devices stay
devices- How many devices are allowed, 1–100
speed- Mbit/s, 0–100000; 0 — no limit
limit, reset, zero- The traffic limit in bytes, the reset, true — start the count from nothing
group- The group by name; empty — none
external- The external ID, up to 128 characters; empty — remove it
tags- Tags — the whole list anew: up to 20, each up to 32 characters
tags_add, tags_remove- Add and remove tags, the rest stay — handy for many at once
meta- Your system's fields — all anew: up to 20; a key of Latin letters, digits, _ . -, up to 40 characters; a value up to 500
note, contact- A note up to 300 characters, a contact up to 100
A value too long is not cut but gives the bad error with the field and the limit — {"error": "bad", "field": "change.devices", "max": 100}: else your system would not learn that something else was saved. A new client comes back whole in the answer, with the link.
Filters and order
With no parameters GET clients gives everyone. Each parameter narrows the list, and they add up.
external, tag- An external ID, a tag
status- Comma-separated: on,soon,limit,off,paused,waiting
group- A group; an empty value — no group
q- A word in the name, note, contact or external ID, case aside
until_before, until_after- The term ends before, after — unix time; the ones with no end fall into neither
changed_since- Changed by hand or by a system since this time
devices- none, some, full — no devices, some, all places taken
used_over- At least this share of the limit used, %
seen_before- The app has not taken the subscription since this time — or never has
sort- name, until, added, used, changed; a “-” in front — the other way
limit, cursor- A page of 1–1000 and the cursor from the last page's 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"Pages
- With limit the answer is {at, clients, total, next}: total — how many in all match the filter, next — the next page's cursor, null — this one is the last.
- The cursor is a place in the order, not a page number: a client added or deleted between pages does not shift the others — no one comes twice and no one is lost.
- Ask for the next page with the same filters and sort; only cursor changes.
{
"at": 1793754000,
"clients": [
{"id": "c_Ab3dE5fG7hJ9", "name": "order-88123", "status": "soon", "…": "…"}
],
"total": 412,
"next": "eyJrIjoxNzk0MDAwMDAwfQ"
}Whose client is this
A person sent support a link or a device key — find the client. The link may be whole or just its secret — the part after /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"}'Many by a filter
POST clients/bulk with filter in place of names changes everyone the filter takes — all or none. First see whom it touches: dry: true answers with the number and the first 100 names, changing nothing.
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", "…"]
}- An empty filter — bad: that way “everyone” is not changed by accident. For all active ones — status: ["on", "soon"].
- tags_add and tags_remove change tags without touching the rest — say, to mark those who were sent a letter.
- Deleting many — remove: true in place of change, needs the “All” right. The deleted lie in the trash for 30 days.