3x-ui3x-ui
مرجعمرجع API

کلاینت‌ها

کلاینت‌ها را به‌عنوان موجودیت‌های مستقل مدیریت کنید که می‌توانند به یک یا چند inbound متصل شوند. هر رکورد کلاینت، ورودی settings.clients را در تمام inboundهایی که به آن‌ها تعلق دارد هدایت می‌کند. این endpointها زیر مسیر /panel/api/clients قرار دارند.

List every client with its attached inbound IDs and traffic record. The reverse field, if set, is returned as a nested JSON object (legacy JSON-encoded-string form is still accepted on write).

GET
/panel/api/clients/list

Authorization

AuthorizationBearer <token>

API token from Settings → Security → API Token. Send as Authorization: Bearer <token>.

In: header

Response Body

application/json

curl -X GET "https://example.com/panel/api/clients/list"
{  "success": true,  "obj": [    {      "id": 1,      "email": "alice@example.com",      "subId": "abcd1234",      "uuid": "...",      "totalGB": 53687091200,      "expiryTime": 1735689600000,      "enable": true,      "reverse": null,      "inboundIds": [        3,        5      ],      "traffic": {        "up": 1024,        "down": 4096,        "enable": true      }    }  ]}

Filter, sort, and paginate clients on the server. Each item is a slim row (no uuid/password/auth/flow/security/reverse/tgId) so the clients page can ship 25-ish rows in a few KB instead of the full table. The response also includes a summary computed across the full DB row set so dashboard counters stay stable as the user paginates or filters: the *Count fields are exact, while the email arrays beside them stop at 200 entries so the payload does not grow with the panel. Page size capped at 200; fetch /get/:email to obtain the full per-client payload for an edit/info modal.

GET
/panel/api/clients/list/paged

Authorization

AuthorizationBearer <token>

API token from Settings → Security → API Token. Send as Authorization: Bearer <token>.

In: header

Query Parameters

page?integer

1-indexed page number. Defaults to 1.

Default1
pageSize?integer

Rows per page. Defaults to 25, capped at 200.

Default25
search?string

Case-insensitive substring match on email, subId, comment, UUID, password, auth or Telegram ID.

filter?string

CSV status buckets: online, active, deactive, depleted or expiring. Values are ORed.

protocol?string

CSV inbound protocols: vmess, vless, trojan, shadowsocks, wireguard, hysteria, http, mixed, tunnel, tun, mtproto or amneziawg. Values are ORed.

inbound?string

CSV positive inbound IDs. Values are ORed; invalid or non-positive IDs are ignored.

sort?string

Sort key. An omitted or unknown value falls back to client ID ascending.

Value in

  • "enable"
  • "email"
  • "inboundIds"
  • "traffic"
  • "remaining"
  • "expiryTime"
  • "createdAt"
  • "updatedAt"
  • "lastOnline"
order?string

Sort direction. Only descend selects descending order; otherwise ascending.

Value in

  • "ascend"
  • "descend"
expiryFrom?integer

Inclusive minimum expiry time in Unix milliseconds. Zero or negative means unset.

expiryTo?integer

Inclusive maximum expiry time in Unix milliseconds. Zero or negative means unbounded.

usageFrom?integer

Inclusive minimum combined upload and download usage in bytes. Zero means unset.

usageTo?integer

Inclusive maximum combined upload and download usage in bytes. Zero means unbounded.

autoRenew?string

on selects clients with an interval or calendar-day reset; off selects clients without either.

Value in

  • "on"
  • "off"
hasTgId?string

yes selects clients with a non-zero Telegram ID; no selects clients without one.

Value in

  • "yes"
  • "no"
hasComment?string

yes selects clients with a non-blank comment; no selects clients without one.

Value in

  • "yes"
  • "no"
group?string

CSV group names, matched case-insensitively after trimming. Values are ORed.

Response Body

application/json

curl -X GET "https://example.com/panel/api/clients/list/paged"
{  "success": true,  "obj": {    "filtered": 47,    "groups": [      "staff",      "trial"    ],    "items": [      {        "comment": "Primary device",        "createdAt": 1735000000000,        "email": "alice@example.com",        "enable": true,        "expiryTime": 1735689600000,        "group": "staff",        "inboundIds": [          3,          5        ],        "limitHwid": 0,        "limitIp": 0,        "reset": 0,        "resetDay": 0,        "resetMax": 0,        "subId": "abcd1234",        "totalGB": 53687091200,        "traffic": null,        "updatedAt": 1735100000000      }    ],    "page": 1,    "pageSize": 25,    "summary": {      "active": 1850,      "deactive": [        "bob@example.com"      ],      "deactiveCount": 150,      "depleted": [],      "depletedCount": 0,      "expiring": [],      "expiringCount": 0,      "online": [        "alice@example.com"      ],      "onlineCount": 1,      "total": 2000    },    "total": 2000  }}

Fetch one client by email, including the inbound IDs and external config IDs it is attached to.

GET
/panel/api/clients/get/{email}

Authorization

AuthorizationBearer <token>

API token from Settings → Security → API Token. Send as Authorization: Bearer <token>.

In: header

Path Parameters

email*string

Client email (unique identifier).

Response Body

application/json

curl -X GET "https://example.com/panel/api/clients/get/string"
{  "success": true,  "msg": "string",  "obj": null}

Create a new client and attach it to one or more inbounds in a single call. Body is JSON. Per-protocol secrets are generated server-side when omitted, so callers can send only the universal fields.

POST
/panel/api/clients/add

Authorization

AuthorizationBearer <token>

API token from Settings → Security → API Token. Send as Authorization: Bearer <token>.

In: header

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Response Body

application/json

curl -X POST "https://example.com/panel/api/clients/add" \  -H "Content-Type: application/json" \  -d '{    "client": {      "email": "alice@example.com",      "totalGB": 53687091200,      "expiryTime": 1735689600000,      "tgId": 0,      "limitIp": 0,      "limitHwid": 0,      "enable": true    },    "inboundIds": [      3,      5    ]  }'
{  "success": true,  "msg": "Client added"}

Update an existing client by email. Changes propagate to every attached inbound. Body is the JSON client payload — supply the full set of fields you want to keep (the server replaces the row, it does not patch).

POST
/panel/api/clients/update/{email}

Authorization

AuthorizationBearer <token>

API token from Settings → Security → API Token. Send as Authorization: Bearer <token>.

In: header

Path Parameters

email*string

Current client email (unique identifier).

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Response Body

application/json

curl -X POST "https://example.com/panel/api/clients/update/string" \  -H "Content-Type: application/json" \  -d '{    "email": "alice@example.com",    "totalGB": 107374182400,    "expiryTime": 1767225600000,    "limitHwid": 2,    "tgId": 123456789,    "enable": true  }'
{  "success": true,  "msg": "Client updated"}

Delete a client by email. Removes it from every attached inbound and drops its traffic record unless keepTraffic=1 is passed.

POST
/panel/api/clients/del/{email}

Authorization

AuthorizationBearer <token>

API token from Settings → Security → API Token. Send as Authorization: Bearer <token>.

In: header

Path Parameters

email*string

Client email (unique identifier).

Query Parameters

keepTraffic*integer

Pass 1 to retain the xray_client_traffic row after deletion.

Response Body

application/json

curl -X POST "https://example.com/panel/api/clients/del/string?keepTraffic=0"
{  "success": true,  "msg": "Client deleted"}

Attach an existing client to one or more additional inbounds. Body is JSON.

POST
/panel/api/clients/{email}/attach

Authorization

AuthorizationBearer <token>

API token from Settings → Security → API Token. Send as Authorization: Bearer <token>.

In: header

Path Parameters

email*string

Client email (unique identifier).

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Response Body

application/json

curl -X POST "https://example.com/panel/api/clients/string/attach" \  -H "Content-Type: application/json" \  -d '{    "inboundIds": [      7,      9    ]  }'
{  "success": true}

Detach a client from one or more inbounds without deleting the client.

POST
/panel/api/clients/{email}/detach

Authorization

AuthorizationBearer <token>

API token from Settings → Security → API Token. Send as Authorization: Bearer <token>.

In: header

Path Parameters

email*string

Client email (unique identifier).

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Response Body

application/json

curl -X POST "https://example.com/panel/api/clients/string/detach" \  -H "Content-Type: application/json" \  -d '{    "inboundIds": [      5    ]  }'
{  "success": true}
POST
/panel/api/clients/{email}/externalLinks

Authorization

AuthorizationBearer <token>

API token from Settings → Security → API Token. Send as Authorization: Bearer <token>.

In: header

Path Parameters

email*string

Client email (unique identifier).

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Response Body

application/json

curl -X POST "https://example.com/panel/api/clients/string/externalLinks" \  -H "Content-Type: application/json" \  -d '{    "externalLinks": [      {        "kind": "link",        "value": "vless://uuid@host:443?...#srv",        "remark": "DE",        "enable": true,        "expiryTime": 0      },      {        "kind": "subscription",        "value": "https://provider.example/sub/abc",        "remark": "Provider",        "enable": false,        "expiryTime": 1767225600000,        "namePrefix": "[zjh] "      }    ]  }'
{  "success": true}

Reset the up/down counters for every client globally. Quotas and expiry are not affected. Triggers an Xray restart if any counter actually moved.

POST
/panel/api/clients/resetAllTraffics

Authorization

AuthorizationBearer <token>

API token from Settings → Security → API Token. Send as Authorization: Bearer <token>.

In: header

Response Body

application/json

curl -X POST "https://example.com/panel/api/clients/resetAllTraffics"
{  "success": true}

Delete every client whose traffic quota is exhausted (used >= total, when reset is disabled) or whose expiry has passed. Returns the deleted count and triggers an Xray restart when any client was on a running inbound.

POST
/panel/api/clients/delDepleted

Authorization

AuthorizationBearer <token>

API token from Settings → Security → API Token. Send as Authorization: Bearer <token>.

In: header

Response Body

application/json

curl -X POST "https://example.com/panel/api/clients/delDepleted"
{  "success": true,  "obj": {    "deleted": 0  }}
POST
/panel/api/clients/delOrphans

Authorization

AuthorizationBearer <token>

API token from Settings → Security → API Token. Send as Authorization: Bearer <token>.

In: header

Response Body

application/json

curl -X POST "https://example.com/panel/api/clients/delOrphans"
{  "success": true,  "obj": {    "deleted": 0  }}

Return every client as a {client, inboundIds} array — the same shape /bulkCreate and /import accept — so the payload round-trips straight back through /import. Clients with no inbound attachment are included with an empty inboundIds list. The UI shows this in a CodeMirror viewer (copy / download); programmatic callers get the array in obj.

GET
/panel/api/clients/export

Authorization

AuthorizationBearer <token>

API token from Settings → Security → API Token. Send as Authorization: Bearer <token>.

In: header

Response Body

application/json

curl -X GET "https://example.com/panel/api/clients/export"
{  "success": true,  "obj": [    {      "client": {        "email": "alice@example.com",        "id": "...",        "totalGB": 53687091200,        "expiryTime": 0,        "limitHwid": 2,        "enable": true,        "subId": "..."      },      "inboundIds": [        7,        9      ]    }  ]}

Import clients from a JSON body { "data": "<json>" }, where data is a string-encoded array produced by /export ([{client, inboundIds}]). Items with inboundIds are created and attached to those inbounds; items with an empty inboundIds list are restored as unattached client records. Existing emails are never overwritten — they are returned in skipped. Triggers a single Xray restart at the end if any target inbound was running.

POST
/panel/api/clients/import

Authorization

AuthorizationBearer <token>

API token from Settings → Security → API Token. Send as Authorization: Bearer <token>.

In: header

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Response Body

application/json

curl -X POST "https://example.com/panel/api/clients/import" \  -H "Content-Type: application/json" \  -d '{    "data": "[{\\"client\\":{\\"email\\":\\"alice@example.com\\",\\"enable\\":true},\\"inboundIds\\":[7]}]"  }'
{  "success": true,  "obj": {    "created": 2,    "skipped": [      {        "email": "alice@example.com",        "reason": "email already in use: alice@example.com"      }    ]  }}

Shift expiry and/or traffic quota for many clients in one call. addDays/addBytes may be negative. Clients with unlimited expiry (expiryTime=0) or unlimited traffic (totalGB=0) are skipped for the corresponding field — bulk extend never converts unlimited to limited. A client that was auto-disabled solely because it was depleted (expired or over quota) is automatically re-enabled — locally and on its node — when the adjustment lifts it out of depletion; a manually-disabled or still-depleted client is left disabled. The optional flow directive sets the XTLS flow on every client: "none" clears it, "xtls-rprx-vision"/"xtls-rprx-vision-udp443" set it where the inbound supports it (omit or "" to leave it unchanged). Returns the adjusted count and per-email skip reasons.

POST
/panel/api/clients/bulkAdjust

Authorization

AuthorizationBearer <token>

API token from Settings → Security → API Token. Send as Authorization: Bearer <token>.

In: header

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Response Body

application/json

curl -X POST "https://example.com/panel/api/clients/bulkAdjust" \  -H "Content-Type: application/json" \  -d '{    "emails": [      "alice",      "bob"    ],    "addDays": 30,    "addBytes": 53687091200,    "flow": "xtls-rprx-vision"  }'
{  "success": true,  "obj": {    "adjusted": 2,    "skipped": [      {        "email": "carol",        "reason": "unlimited expiry"      }    ]  }}

Enable many clients in one call. Emails are grouped by inbound and applied with a single read-modify-write per inbound; the running Xray (local or remote node) is updated to add each user. Note that enabling a client whose quota is exhausted or whose expiry has passed only flips the flag — the traffic loop will disable it again on the next tick. Returns the changed count and per-email skip reasons.

POST
/panel/api/clients/bulkEnable

Authorization

AuthorizationBearer <token>

API token from Settings → Security → API Token. Send as Authorization: Bearer <token>.

In: header

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Response Body

application/json

curl -X POST "https://example.com/panel/api/clients/bulkEnable" \  -H "Content-Type: application/json" \  -d '{    "emails": [      "alice",      "bob"    ]  }'
{  "success": true,  "obj": {    "changed": 2,    "skipped": [      {        "email": "carol",        "reason": "client not found"      }    ]  }}

Disable many clients in one call. Emails are grouped by inbound and applied with a single read-modify-write per inbound; the running Xray (local or remote node) is updated to remove each user. Returns the changed count and per-email skip reasons.

POST
/panel/api/clients/bulkDisable

Authorization

AuthorizationBearer <token>

API token from Settings → Security → API Token. Send as Authorization: Bearer <token>.

In: header

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Response Body

application/json

curl -X POST "https://example.com/panel/api/clients/bulkDisable" \  -H "Content-Type: application/json" \  -d '{    "emails": [      "alice",      "bob"    ]  }'
{  "success": true,  "obj": {    "changed": 2,    "skipped": [      {        "email": "carol",        "reason": "client not found"      }    ]  }}

Delete many clients in one call. The server processes the list sequentially so each delete sees the committed state of the previous one — avoids the race the per-email fan-out had on the panel side. Pass keepTraffic=true to retain the xray_client_traffic rows after deletion.

POST
/panel/api/clients/bulkDel

Authorization

AuthorizationBearer <token>

API token from Settings → Security → API Token. Send as Authorization: Bearer <token>.

In: header

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Response Body

application/json

curl -X POST "https://example.com/panel/api/clients/bulkDel" \  -H "Content-Type: application/json" \  -d '{    "emails": [      "alice",      "bob"    ],    "keepTraffic": false  }'
{  "success": true,  "obj": {    "deleted": 2,    "skipped": [      {        "email": "carol",        "reason": "client not found"      }    ]  }}

Create many clients in one call. Body is a JSON array of {client, inboundIds} payloads — the same shape /add accepts. Items are processed sequentially; per-email skip reasons are returned for items that fail (e.g., duplicate email). Triggers a single Xray restart at the end if any inbound was running.

POST
/panel/api/clients/bulkCreate

Authorization

AuthorizationBearer <token>

API token from Settings → Security → API Token. Send as Authorization: Bearer <token>.

In: header

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Response Body

application/json

curl -X POST "https://example.com/panel/api/clients/bulkCreate" \  -H "Content-Type: application/json" \  -d '[    {      "client": {        "email": "alice@example.com",        "totalGB": 53687091200,        "expiryTime": 0,        "limitHwid": 2,        "enable": true      },      "inboundIds": [        7      ]    },    {      "client": {        "email": "bob@example.com",        "totalGB": 53687091200,        "expiryTime": 0,        "limitHwid": 0,        "enable": true      },      "inboundIds": [        7,        9      ]    }  ]'
{  "success": true,  "obj": {    "created": 2,    "skipped": [      {        "email": "alice@example.com",        "reason": "email already in use"      }    ]  }}

Add many clients to a group in one call. Updates clients.group_name and patches the matching client entry inside every owning inbound's settings JSON in a single transaction. If the group name does not yet exist (in client_groups or as a derived label), it is auto-created as a persistent group. To clear the group label, use /groups/bulkRemove instead.

POST
/panel/api/clients/groups/bulkAdd

Authorization

AuthorizationBearer <token>

API token from Settings → Security → API Token. Send as Authorization: Bearer <token>.

In: header

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Response Body

application/json

curl -X POST "https://example.com/panel/api/clients/groups/bulkAdd" \  -H "Content-Type: application/json" \  -d '{    "emails": [      "alice",      "bob"    ],    "group": "customer-a"  }'
{  "success": true,  "obj": {    "affected": 2  }}

Clear the group label on many clients in one call. Inverse of /groups/bulkAdd. Clients themselves are kept — only the group label is cleared from clients.group_name and from each owning inbound's settings JSON. Groups become empty if all their members are removed.

POST
/panel/api/clients/groups/bulkRemove

Authorization

AuthorizationBearer <token>

API token from Settings → Security → API Token. Send as Authorization: Bearer <token>.

In: header

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Response Body

application/json

curl -X POST "https://example.com/panel/api/clients/groups/bulkRemove" \  -H "Content-Type: application/json" \  -d '{    "emails": [      "alice",      "bob"    ]  }'
{  "success": true,  "obj": {    "affected": 2  }}

Attach many existing clients to many inbounds in one call. Each client keeps its identity (email/UUID/password/subId) and a shared traffic row; all clients are added to a target inbound in a single AddInboundClient call. Clients already present on a target are reported under skipped. Returns per-email attached/skipped/errors lists and triggers a single Xray restart if any target inbound was running.

POST
/panel/api/clients/bulkAttach

Authorization

AuthorizationBearer <token>

API token from Settings → Security → API Token. Send as Authorization: Bearer <token>.

In: header

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Response Body

application/json

curl -X POST "https://example.com/panel/api/clients/bulkAttach" \  -H "Content-Type: application/json" \  -d '{    "emails": [      "alice",      "bob"    ],    "inboundIds": [      7,      9    ]  }'
{  "success": true,  "obj": {    "attached": [      "alice",      "bob"    ],    "skipped": [      "bob"    ],    "errors": []  }}

Mirror of bulkAttach: detach many existing clients from many inbounds in one call. For each email, intersects the client's current inbounds with the requested set and detaches from those only; (email, inbound) pairs where the client is not currently attached are silently no-ops. Emails not attached to any of the requested inbounds are reported under skipped. Client records are kept even if they become orphaned — use bulkDel for full removal. Returns per-email detached/skipped/errors lists and triggers a single Xray restart if any target inbound was running.

POST
/panel/api/clients/bulkDetach

Authorization

AuthorizationBearer <token>

API token from Settings → Security → API Token. Send as Authorization: Bearer <token>.

In: header

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Response Body

application/json

curl -X POST "https://example.com/panel/api/clients/bulkDetach" \  -H "Content-Type: application/json" \  -d '{    "emails": [      "alice",      "bob"    ],    "inboundIds": [      7,      9    ]  }'
{  "success": true,  "obj": {    "detached": [      "alice",      "bob"    ],    "skipped": [],    "errors": []  }}

Zero up/down counters for many clients in one call. Loops the single-reset path so each client is re-enabled across its attached inbounds and pushed to Xray/remote nodes. Returns the count of successfully reset clients.

POST
/panel/api/clients/bulkResetTraffic

Authorization

AuthorizationBearer <token>

API token from Settings → Security → API Token. Send as Authorization: Bearer <token>.

In: header

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Response Body

application/json

curl -X POST "https://example.com/panel/api/clients/bulkResetTraffic" \  -H "Content-Type: application/json" \  -d '{    "emails": [      "alice",      "bob"    ]  }'
{  "success": true,  "obj": {    "affected": 2  }}

List all client groups with their member counts. Merges persisted groups (rows in client_groups, including empty placeholders) with the distinct group_name values currently set on clients. Sorted alphabetically (case-insensitive).

GET
/panel/api/clients/groups

Authorization

AuthorizationBearer <token>

API token from Settings → Security → API Token. Send as Authorization: Bearer <token>.

In: header

Response Body

application/json

curl -X GET "https://example.com/panel/api/clients/groups"
{  "success": true,  "obj": [    {      "name": "customer-a",      "clientCount": 5    },    {      "name": "internal",      "clientCount": 0    }  ]}

Return just the email list of clients that currently belong to the given group. Useful for fanning a single bulk action over an entire group without round-tripping the full client list.

GET
/panel/api/clients/groups/{name}/emails

Authorization

AuthorizationBearer <token>

API token from Settings → Security → API Token. Send as Authorization: Bearer <token>.

In: header

Path Parameters

name*string

Group name (URL-encoded).

Response Body

application/json

curl -X GET "https://example.com/panel/api/clients/groups/string/emails"
{  "success": true,  "obj": [    "alice",    "bob",    "carol"  ]}

Create a new empty (placeholder) group. The group becomes selectable in client forms and the filter drawer even before any client is added to it. Errors if a group with the same name already exists.

POST
/panel/api/clients/groups/create

Authorization

AuthorizationBearer <token>

API token from Settings → Security → API Token. Send as Authorization: Bearer <token>.

In: header

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Response Body

application/json

curl -X POST "https://example.com/panel/api/clients/groups/create" \  -H "Content-Type: application/json" \  -d '{    "name": "customer-a"  }'
{  "success": true,  "obj": {    "name": "customer-a"  }}

Rename a group. The new name is applied to the client_groups row AND propagated to every matching client (both clients.group_name and the client entry inside every owning inbound's settings JSON) in a single transaction. Returns the number of clients whose label was updated.

POST
/panel/api/clients/groups/rename

Authorization

AuthorizationBearer <token>

API token from Settings → Security → API Token. Send as Authorization: Bearer <token>.

In: header

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Response Body

application/json

curl -X POST "https://example.com/panel/api/clients/groups/rename" \  -H "Content-Type: application/json" \  -d '{    "oldName": "customer-a",    "newName": "tier-1"  }'
{  "success": true,  "obj": {    "affected": 5  }}

Remove a group. Deletes the client_groups row and clears the group label from every matching client (both clients.group_name and the inbound settings JSON). The clients themselves are NOT deleted — use /bulkDel after filtering by group for that. Returns the count of clients whose label was cleared.

POST
/panel/api/clients/groups/delete

Authorization

AuthorizationBearer <token>

API token from Settings → Security → API Token. Send as Authorization: Bearer <token>.

In: header

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Response Body

application/json

curl -X POST "https://example.com/panel/api/clients/groups/delete" \  -H "Content-Type: application/json" \  -d '{    "name": "customer-a"  }'
{  "success": true,  "obj": {    "affected": 5  }}

Zero out a single client’s up/down counters. Re-enables the client across every attached inbound and pushes the change to Xray (or the remote node) so depleted users can connect again immediately.

POST
/panel/api/clients/resetTraffic/{email}

Authorization

AuthorizationBearer <token>

API token from Settings → Security → API Token. Send as Authorization: Bearer <token>.

In: header

Path Parameters

email*string

Client email.

Response Body

application/json

curl -X POST "https://example.com/panel/api/clients/resetTraffic/string"
{  "success": true,  "msg": "string",  "obj": null}

Manually adjust a client’s upload + download counters. Useful for migrations from external accounting systems.

POST
/panel/api/clients/updateTraffic/{email}

Authorization

AuthorizationBearer <token>

API token from Settings → Security → API Token. Send as Authorization: Bearer <token>.

In: header

Path Parameters

email*string

Client email.

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Response Body

application/json

curl -X POST "https://example.com/panel/api/clients/updateTraffic/string" \  -H "Content-Type: application/json" \  -d '{    "upload": 1073741824,    "download": 5368709120  }'
{  "success": true,  "msg": "string",  "obj": null}

List source IPs that have connected with the given client’s credentials. Returns an array of "ip (timestamp)" strings.

POST
/panel/api/clients/ips/{email}

Authorization

AuthorizationBearer <token>

API token from Settings → Security → API Token. Send as Authorization: Bearer <token>.

In: header

Path Parameters

email*string

Client email.

Response Body

application/json

curl -X POST "https://example.com/panel/api/clients/ips/string"
{  "success": true,  "msg": "string",  "obj": null}

Reset the recorded IP list for a client.

POST
/panel/api/clients/clearIps/{email}

Authorization

AuthorizationBearer <token>

API token from Settings → Security → API Token. Send as Authorization: Bearer <token>.

In: header

Path Parameters

email*string

Client email.

Response Body

application/json

curl -X POST "https://example.com/panel/api/clients/clearIps/string"
{  "success": true,  "msg": "string",  "obj": null}

List the emails of currently connected clients (last seen within the heartbeat window), deduped across every node.

POST
/panel/api/clients/onlines

Authorization

AuthorizationBearer <token>

API token from Settings → Security → API Token. Send as Authorization: Bearer <token>.

In: header

Response Body

application/json

curl -X POST "https://example.com/panel/api/clients/onlines"
{  "success": true,  "obj": [    "user1",    "user2"  ]}

Online client emails grouped by the panelGuid of the node that physically hosts each client. The local panel uses its own GUID; each node (at any depth in a chain) uses its GUID. Lets the inbounds page attribute online status to the real node instead of the intermediate one it syncs through.

POST
/panel/api/clients/onlinesByGuid

Authorization

AuthorizationBearer <token>

API token from Settings → Security → API Token. Send as Authorization: Bearer <token>.

In: header

Response Body

application/json

curl -X POST "https://example.com/panel/api/clients/onlinesByGuid"
{  "success": true,  "obj": {    "a1b2-...": [      "user1"    ],    "c3d4-...": [      "user1",      "user2"    ]  }}

Per-client source IPs grouped by the panelGuid of the node that observed them. Lets the central panel attribute and enforce per-client IP limits using the real visitor IPs each node sees, instead of the address of the intermediate panel it syncs through.

POST
/panel/api/clients/clientIpsByGuid

Authorization

AuthorizationBearer <token>

API token from Settings → Security → API Token. Send as Authorization: Bearer <token>.

In: header

Response Body

application/json

curl -X POST "https://example.com/panel/api/clients/clientIpsByGuid"
{  "success": true,  "obj": {    "a1b2-...": {      "user1": [        {          "ip": "1.2.3.4",          "timestamp": 1700000000        }      ]    }  }}

Inbound tags that carried traffic within the heartbeat window, grouped by the hosting node's panelGuid. Pairs with onlinesByGuid so the inbounds page only marks a multi-inbound client online on the inbounds it actually used. Nodes that do not report per-inbound activity are absent.

POST
/panel/api/clients/activeInbounds

Authorization

AuthorizationBearer <token>

API token from Settings → Security → API Token. Send as Authorization: Bearer <token>.

In: header

Response Body

application/json

curl -X POST "https://example.com/panel/api/clients/activeInbounds"
{  "success": true,  "obj": {    "a1b2-...": [      "in-443-tcp",      "in-8443-tcp"    ]  }}

Map of client email → last-seen unix timestamp.

POST
/panel/api/clients/lastOnline

Authorization

AuthorizationBearer <token>

API token from Settings → Security → API Token. Send as Authorization: Bearer <token>.

In: header

Response Body

application/json

curl -X POST "https://example.com/panel/api/clients/lastOnline"
{  "success": true,  "obj": {    "user1": 1700000000,    "user2": 1699999000  }}

Traffic counters for a client identified by email.

GET
/panel/api/clients/traffic/{email}

Authorization

AuthorizationBearer <token>

API token from Settings → Security → API Token. Send as Authorization: Bearer <token>.

In: header

Path Parameters

email*string

Client email (unique across the panel).

Response Body

application/json

curl -X GET "https://example.com/panel/api/clients/traffic/string"
{  "success": true,  "obj": {    "down": 2097152,    "email": "user1",    "enable": true,    "expiryTime": 1735689600000,    "id": 14825,    "inboundId": 1,    "lastOnline": 1735680000000,    "lastSubFetch": 1735680000000,    "reset": 0,    "resetCount": 0,    "resetDay": 0,    "resetMax": 0,    "subId": "i7tvdpeffi0hvvf1",    "total": 10737418240,    "up": 1048576,    "uuid": "e18c9a96-71bf-48d4-933f-8b9a46d4290c"  }}

Return every protocol URL (vless://, vmess://, trojan://, ss://, hysteria://, hy2://) for clients matching the subscription ID. Same result set as the configured subPath endpoint, but as a JSON array — no base64. When an inbound has streamSettings.externalProxy set, one URL is emitted per external proxy. Empty array when the subId has no enabled clients.

GET
/panel/api/clients/subLinks/{subId}

Authorization

AuthorizationBearer <token>

API token from Settings → Security → API Token. Send as Authorization: Bearer <token>.

In: header

Path Parameters

subId*string

Subscription ID, taken from the client's subId field.

Response Body

application/json

curl -X GET "https://example.com/panel/api/clients/subLinks/string"
{  "success": true,  "obj": [    "vless://uuid@host:443?security=reality&...#user1",    "vmess://eyJ2IjoyLC..."  ]}

Return every URL for one client across all attached inbounds — the same strings the Copy URL button copies in the panel UI. Supported protocols: vmess, vless, trojan, shadowsocks, hysteria. If streamSettings.externalProxy is set, returns one URL per external proxy. Protocols without a URL form (socks, http, mixed, wireguard, dokodemo, tunnel) contribute nothing.

GET
/panel/api/clients/links/{email}

Authorization

AuthorizationBearer <token>

API token from Settings → Security → API Token. Send as Authorization: Bearer <token>.

In: header

Path Parameters

email*string

Client email (unique identifier).

Response Body

application/json

curl -X GET "https://example.com/panel/api/clients/links/string"
{  "success": true,  "obj": [    "vless://uuid@host:443?...#user1"  ]}

ورودی‌ها

مدیریت پیکربندی‌های ورودی و کلاینت‌های آن‌ها. همهٔ endpointها زیر /panel/api/inbounds قرار دارند و به یک نشست واردشده یا توکن Bearer نیاز دارند. endpointهای تولیدکنندهٔ لینک تنها زمانی به هدرهای forwarded اعتنا می‌کنند که درخواست از یک پراکسی مورد اعتماد پیکربندی‌شده برسد.

سرور

وضعیت سیستم، دریافت لاگ، تولیدکننده‌های گواهی، مدیریت باینری Xray و پشتیبان‌گیری/بازیابی. همگی زیرمجموعهٔ /panel/api/server.