3x-uiClients
Manage clients as first-class entities that can be attached to one or more inbounds. A single client row drives the settings.clients entry in every inbound it belongs to. Endpoints live under /panel/api/clients.
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 } } ]}API token from Settings → Security → API Token. Send as Authorization: Bearer <token>.
In: header
Query Parameters
1-indexed page number. Defaults to 1.
Rows per page. Defaults to 25, capped at 200.
Case-insensitive substring match on email / subId / comment.
Status bucket: online | active | deactive | depleted | expiring.
Match clients attached to at least one inbound of this protocol (vless, vmess, trojan, shadowsocks, ...).
Sort key: enable | email | inboundIds | traffic | remaining | expiryTime.
ascend or descend.
Response Body
application/json
curl -X GET "https://example.com/panel/api/clients/list/paged?page=0&pageSize=0&search=string&filter=string&protocol=string&sort=string&order=string"{ "success": true, "obj": { "items": [ { "email": "alice@example.com", "subId": "abcd1234", "enable": true, "totalGB": 53687091200, "expiryTime": 1735689600000, "limitIp": 0, "reset": 0, "inboundIds": [ 3, 5 ], "traffic": { "up": 1024, "down": 4096, "enable": true }, "createdAt": 1735000000000, "updatedAt": 1735100000000 } ], "total": 2000, "filtered": 47, "page": 1, "pageSize": 25, "summary": { "total": 2000, "active": 1850, "online": [ "alice@example.com" ], "depleted": [], "expiring": [], "deactive": [] } }}API token from Settings → Security → API Token. Send as Authorization: Bearer <token>.
In: header
Path Parameters
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}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, "enable": true }, "inboundIds": [ 3, 5 ] }'{ "success": true, "msg": "Client added"}API token from Settings → Security → API Token. Send as Authorization: Bearer <token>.
In: header
Path Parameters
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, "tgId": 123456789, "enable": true }'{ "success": true, "msg": "Client updated"}API token from Settings → Security → API Token. Send as Authorization: Bearer <token>.
In: header
Path Parameters
Client email (unique identifier).
Query Parameters
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"}API token from Settings → Security → API Token. Send as Authorization: Bearer <token>.
In: header
Path Parameters
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}API token from Settings → Security → API Token. Send as Authorization: Bearer <token>.
In: header
Path Parameters
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}API token from Settings → Security → API Token. Send as Authorization: Bearer <token>.
In: header
Path Parameters
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" }, { "kind": "subscription", "value": "https://provider.example/sub/abc", "remark": "Provider" } ] }'{ "success": true}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}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 }}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 }}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, "enable": true, "subId": "..." }, "inboundIds": [ 7, 9 ] } ]}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" } ] }}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" } ] }}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" } ] }}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" } ] }}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" } ] }}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, "enable": true }, "inboundIds": [ 7 ] }, { "client": { "email": "bob@example.com", "totalGB": 53687091200, "expiryTime": 0, "enable": true }, "inboundIds": [ 7, 9 ] } ]'{ "success": true, "obj": { "created": 2, "skipped": [ { "email": "alice@example.com", "reason": "email already in use" } ] }}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 }}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 }}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": [] }}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": [] }}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 }}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 } ]}API token from Settings → Security → API Token. Send as Authorization: Bearer <token>.
In: header
Path Parameters
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" ]}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" }}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 }}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 }}API token from Settings → Security → API Token. Send as Authorization: Bearer <token>.
In: header
Path Parameters
Client email.
Response Body
application/json
curl -X POST "https://example.com/panel/api/clients/resetTraffic/string"{ "success": true, "msg": "string", "obj": null}API token from Settings → Security → API Token. Send as Authorization: Bearer <token>.
In: header
Path Parameters
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}API token from Settings → Security → API Token. Send as Authorization: Bearer <token>.
In: header
Path Parameters
Client email.
Response Body
application/json
curl -X POST "https://example.com/panel/api/clients/ips/string"{ "success": true, "msg": "string", "obj": null}API token from Settings → Security → API Token. Send as Authorization: Bearer <token>.
In: header
Path Parameters
Client email.
Response Body
application/json
curl -X POST "https://example.com/panel/api/clients/clearIps/string"{ "success": true, "msg": "string", "obj": null}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" ]}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" ] }}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 } ] } }}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" ] }}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 }}API token from Settings → Security → API Token. Send as Authorization: Bearer <token>.
In: header
Path Parameters
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, "reset": 0, "subId": "i7tvdpeffi0hvvf1", "total": 10737418240, "up": 1048576, "uuid": "e18c9a96-71bf-48d4-933f-8b9a46d4290c" }}API token from Settings → Security → API Token. Send as Authorization: Bearer <token>.
In: header
Path Parameters
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..." ]}API token from Settings → Security → API Token. Send as Authorization: Bearer <token>.
In: header
Path Parameters
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" ]}