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:

On your server
VELI=https://panel.example.com/Zq7mT2xP4vLc9wRbE5nK/api
VELI_TOKEN=veli_…

Token, schema, MCP3

GET/meThis token: name, rights, term, API versionany
Answer 200application/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
Command
curl -s "$VELI/me" \
  -H "Authorization: Bearer $VELI_TOKEN"
GET/openapi.jsonThe schema of the whole API, OpenAPI 3.1read
Answer 200application/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
Command
curl -s "$VELI/openapi.json" \
  -H "Authorization: Bearer $VELI_TOKEN"
POST/mcpThe panel for an AI agent over MCPany
Request bodyapplication/json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "clients_list",
    "arguments": { "status": "soon" }
  }
}
Answer 200application/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
Command
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
Answer 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"
}

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
Command
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
Request bodyapplication/json
{ "link": "https://panel.example.com/s/kV0pX7wQ2mLr9sTb" }
Answer 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"
  }
}

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
Command
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
Request bodyapplication/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.

Answer 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"
    }
  }
}

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
Command
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
Answer 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"
  }
}

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
Command
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
Request bodyapplication/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.

Answer 200application/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
Command
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
Answer 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>

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
Command
curl -s "$VELI/clients/order-88123/qr?format=svg" \
  -H "Authorization: Bearer $VELI_TOKEN" -o qr.svg
GET/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
Answer 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]
}

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
Command
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
Answer 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
    }
  ]
}

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
Command
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
Answer 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 }
}

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
Command
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
Request bodyapplication/json
{ "device": "a1b2c3d4e5f6" }
Answer 200application/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
Command
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
Request bodyapplication/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.

Answer 200application/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
Command
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
Answer 200application/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
Command
curl -s "$VELI/clients/order-88123/remove" \
  -H "Authorization: Bearer $VELI_TOKEN" -X POST

Trash4

GET/trashDeleted clientsread
Answer 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
    }
  ]
}

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
Command
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
Answer 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"
    }
  }
}

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
Command
curl -s "$VELI/trash/c_Ab3dE5fG7hJ9/restore" \
  -H "Authorization: Bearer $VELI_TOKEN" -X POST
POST/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
Answer 200application/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
Command
curl -s "$VELI/trash/c_Ab3dE5fG7hJ9/remove" \
  -H "Authorization: Bearer $VELI_TOKEN" -X POST
POST/trash/clearEmpty the trashall

All the deleted ones, for good. done — how many there were.

Answer 200application/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
Command
curl -s "$VELI/trash/clear" \
  -H "Authorization: Bearer $VELI_TOKEN" -X POST

Event 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
Answer 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
}

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
Command
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
Answer 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 }
  ]
}

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
Command
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
Answer 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
}

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
Command
curl -s "$VELI/stats?days=7" \
  -H "Authorization: Bearer $VELI_TOKEN"
GET/devicesAll the devices of all the clientsread
Answer 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 }
}

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
Command
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
Answer 200application/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
Command
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
Answer 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": []
    }
  ]
}

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
Command
curl -s "$VELI/log?who=cabinet&what=clients" \
  -H "Authorization: Bearer $VELI_TOKEN"

Nodes6

GET/nodesAll the nodesread
Answer 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 }
  ]
}

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
Command
curl -s "$VELI/nodes" \
  -H "Authorization: Bearer $VELI_TOKEN"
POST/nodesAdd a nodeall
Request bodyapplication/json
{ "name": "de-2", "protocols": "reality,shadowsocks:9388" }
Answer 200application/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
Command
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
Answer 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"
}

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
Command
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
Request bodyapplication/json
{
  "change": { "address": "de1.example.com", "disabled": false }
}
Answer 200application/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
Command
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
Answer 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]
}

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
Command
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
Answer 200application/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
Command
curl -s "$VELI/nodes/de-2/remove" \
  -H "Authorization: Bearer $VELI_TOKEN" -X POST

Groups4

GET/groupsThe groups of clientsread
Answer 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" }
  ]
}

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
Command
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.

Request bodyapplication/json
{
  "group": {
    "name": "europe",
    "nodes": ["de-1", "nl-1"],
    "protocols": null
  }
}
Answer 200application/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
Command
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
Request bodyapplication/json
{
  "group": {
    "name": "europe",
    "nodes": null,
    "protocols": ["veli"]
  }
}
Answer 200application/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
Command
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
Answer 200application/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
Command
curl -s "$VELI/groups/europe/remove" \
  -H "Authorization: Bearer $VELI_TOKEN" -X POST

The 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.

The schema — into a file
curl -s "$VELI/openapi.json" \
  -H "Authorization: Bearer $VELI_TOKEN" -o veli-openapi.json
Types for TypeScript or a ready client in 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

Tokens 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
Who expires in the next 3 days — by term
curl -s "$VELI/clients?status=soon&sort=until&limit=100" \
  -H "Authorization: Bearer $VELI_TOKEN"
Search by a word among the paid ones of the europe group
curl -s "$VELI/clients?q=anna&tag=paid&group=europe" \
  -H "Authorization: Bearer $VELI_TOKEN"
All places taken and 90% of the traffic used — whom to offer to extend or add devices
curl -s "$VELI/clients?devices=full&used_over=90" \
  -H "Authorization: Bearer $VELI_TOKEN"
Active ones who have not connected since October 1
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.
Answer
{
  "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/.

On your server
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.

On your server
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"}}'
Preview: how many and who
{
  "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.