3x-ui客户端
将客户端作为一等实体进行管理，可将其挂载到一个或多个入站。单条客户端记录会驱动其所属 每个入站中的 settings.clients 条目。相关端点位于 /panel/api/clients 之下。
AuthorizationBearer <token>Scoped API token from Settings → Security → API Token. Send as Authorization: Bearer <token>.
Successful response
application/json- response
success?booleanmsg?stringobj?unknowncurl -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 } } ]}AuthorizationBearer <token>Scoped API token from Settings → Security → API Token. Send as Authorization: Bearer <token>.
page?integer1-indexed page number. Defaults to 1.
1pageSize?integerRows per page. Defaults to 25, capped at 200.
25search?stringCase-insensitive substring match on email, subId, comment, UUID, password, auth or Telegram ID.
filter?stringCSV status buckets: online, active, deactive, depleted or expiring. Values are ORed.
protocol?stringCSV inbound protocols: vmess, vless, trojan, shadowsocks, wireguard, hysteria, http, mixed, tunnel, tun, mtproto or amneziawg. Values are ORed.
inbound?stringCSV positive inbound IDs. Values are ORed; invalid or non-positive IDs are ignored.
sort?stringSort key. An omitted or unknown value falls back to client ID ascending.
"enable""email""inboundIds""traffic""remaining""expiryTime""createdAt""updatedAt""lastOnline"order?stringSort direction. Only descend selects descending order; otherwise ascending.
"ascend""descend"expiryFrom?integerInclusive minimum expiry time in Unix milliseconds. Zero or negative means unset.
expiryTo?integerInclusive maximum expiry time in Unix milliseconds. Zero or negative means unbounded.
usageFrom?integerInclusive minimum combined upload and download usage in bytes. Zero means unset.
usageTo?integerInclusive maximum combined upload and download usage in bytes. Zero means unbounded.
autoRenew?stringon selects clients with an interval or calendar-day reset; off selects clients without either.
"on""off"hasTgId?stringyes selects clients with a non-zero Telegram ID; no selects clients without one.
"yes""no"hasComment?stringyes selects clients with a non-blank comment; no selects clients without one.
"yes""no"group?stringCSV group names, matched case-insensitively after trimming. Values are ORed.
Successful response
application/json- response
success?booleanmsg?stringobj?ClientPageResponse is the shape returned by ListPaged. Total is the
row count in the DB; Filtered is the count after Search/Filter/Protocol
were applied, before pagination. The page contains at most PageSize items.
Summary is computed across the full DB row set so dashboard counters
on the clients page stay stable as the user paginates/filters.
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, "resetWeekday": 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 }}AuthorizationBearer <token>Scoped API token from Settings → Security → API Token. Send as Authorization: Bearer <token>.
email*stringClient email (unique identifier).
Successful response
application/json- response
success?booleanmsg?stringobj?unknowncurl -X GET "https://example.com/panel/api/clients/get/string"{ "success": true, "msg": "string", "obj": null}AuthorizationBearer <token>Scoped API token from Settings → Security → API Token. Send as Authorization: Bearer <token>.
application/json- body
client*Client fields: email, subId, id (uuid), password, auth, flow, totalGB, expiryTime, limitIp, limitHwid, tgId (numeric Telegram user ID, 0 = none), comment, enable. Protocol-specific: secret and adTag (mtproto), privateKey, publicKey, preSharedKey, allowedIPs and keepAlive (WireGuard).
inboundIds*array<integer>Inbound IDs to attach the client to. At least one required.
Successful response
application/json- response
success?booleanmsg?stringobj?unknowncurl -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"}AuthorizationBearer <token>Scoped API token from Settings → Security → API Token. Send as Authorization: Bearer <token>.
email*stringCurrent client email (unique identifier).
application/json- body
Successful response
application/json- response
success?booleanmsg?stringobj?unknowncurl -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"}AuthorizationBearer <token>Scoped API token from Settings → Security → API Token. Send as Authorization: Bearer <token>.
email*stringClient email (unique identifier).
keepTraffic*integerPass 1 to retain the xray_client_traffic row after deletion.
Successful response
application/json- response
success?booleanmsg?stringobj?unknowncurl -X POST "https://example.com/panel/api/clients/del/string?keepTraffic=0"{ "success": true, "msg": "Client deleted"}AuthorizationBearer <token>Scoped API token from Settings → Security → API Token. Send as Authorization: Bearer <token>.
email*stringClient email (unique identifier).
application/json- body
inboundIds*array<integer>Inbound IDs to attach.
Successful response
application/json- response
success?booleanmsg?stringobj?unknowncurl -X POST "https://example.com/panel/api/clients/string/attach" \ -H "Content-Type: application/json" \ -d '{ "inboundIds": [ 7, 9 ] }'{ "success": true}AuthorizationBearer <token>Scoped API token from Settings → Security → API Token. Send as Authorization: Bearer <token>.
email*stringClient email (unique identifier).
application/json- body
inboundIds*array<integer>Inbound IDs to detach.
Successful response
application/json- response
success?booleanmsg?stringobj?unknowncurl -X POST "https://example.com/panel/api/clients/string/detach" \ -H "Content-Type: application/json" \ -d '{ "inboundIds": [ 5 ] }'{ "success": true}AuthorizationBearer <token>Scoped API token from Settings → Security → API Token. Send as Authorization: Bearer <token>.
email*stringClient email (unique identifier).
application/json- body
externalLinks*array<>Full replacement list; the server replaces all rows. Each row supports { kind, value, remark, enable, expiryTime, namePrefix }. kind=link: value must be a supported share link such as vless://, vmess://, trojan://, ss://, hysteria2://, or wireguard://, and remark overrides the exported node name. kind=subscription: value must be an http(s) subscription URL, and namePrefix is prepended to fetched node names. Omit enable to default true; enable=false or an expired expiryTime keeps the row saved but excludes it from generated subscriptions. expiryTime is a unix millisecond timestamp where 0 means no link-specific expiry; the owning client's enabled state and expiry still apply. A negative value is rejected. Rows are matched by kind+value across saves, so id is ignored on write. lastFetchAt and lastFetchError are read-only status fields returned by GET.
Successful response
application/json- response
success?booleanmsg?stringobj?unknowncurl -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}AuthorizationBearer <token>Scoped API token from Settings → Security → API Token. Send as Authorization: Bearer <token>.
Successful response
application/json- response
success?booleanmsg?stringobj?unknowncurl -X POST "https://example.com/panel/api/clients/resetAllTraffics"{ "success": true}AuthorizationBearer <token>Scoped API token from Settings → Security → API Token. Send as Authorization: Bearer <token>.
Successful response
application/json- response
success?booleanmsg?stringobj?unknowncurl -X POST "https://example.com/panel/api/clients/delDepleted"{ "success": true, "obj": { "deleted": 0 }}AuthorizationBearer <token>Scoped API token from Settings → Security → API Token. Send as Authorization: Bearer <token>.
Successful response
application/json- response
success?booleanmsg?stringobj?unknowncurl -X POST "https://example.com/panel/api/clients/delOrphans"{ "success": true, "obj": { "deleted": 0 }}AuthorizationBearer <token>Scoped API token from Settings → Security → API Token. Send as Authorization: Bearer <token>.
Successful response
application/json- response
success?booleanmsg?stringobj?unknowncurl -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 ], "traffic": { "up": 1048576, "down": 2097152, "resetCount": 0, "lastOnline": 1735680000000 } } ]}AuthorizationBearer <token>Scoped API token from Settings → Security → API Token. Send as Authorization: Bearer <token>.
application/json- body
Successful response
application/json- response
success?booleanmsg?stringobj?unknowncurl -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" } ] }}AuthorizationBearer <token>Scoped API token from Settings → Security → API Token. Send as Authorization: Bearer <token>.
application/json- body
Successful response
application/json- response
success?booleanmsg?stringobj?unknowncurl -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", "limitHwid": 2, "adTag": "0123456789abcdef0123456789abcdef" }'{ "success": true, "obj": { "adjusted": 2, "skipped": [ { "email": "carol", "reason": "unlimited expiry" } ] }}AuthorizationBearer <token>Scoped API token from Settings → Security → API Token. Send as Authorization: Bearer <token>.
application/json- body
Successful response
application/json- response
success?booleanmsg?stringobj?unknowncurl -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" } ] }}AuthorizationBearer <token>Scoped API token from Settings → Security → API Token. Send as Authorization: Bearer <token>.
application/json- body
Successful response
application/json- response
success?booleanmsg?stringobj?unknowncurl -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" } ] }}AuthorizationBearer <token>Scoped API token from Settings → Security → API Token. Send as Authorization: Bearer <token>.
application/json- body
Successful response
application/json- response
success?booleanmsg?stringobj?unknowncurl -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" } ] }}AuthorizationBearer <token>Scoped API token from Settings → Security → API Token. Send as Authorization: Bearer <token>.
application/json- body
Successful response
application/json- response
success?booleanmsg?stringobj?unknowncurl -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" } ] }}AuthorizationBearer <token>Scoped API token from Settings → Security → API Token. Send as Authorization: Bearer <token>.
application/json- body
Successful response
application/json- response
success?booleanmsg?stringobj?unknowncurl -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 }}AuthorizationBearer <token>Scoped API token from Settings → Security → API Token. Send as Authorization: Bearer <token>.
application/json- body
Successful response
application/json- response
success?booleanmsg?stringobj?unknowncurl -X POST "https://example.com/panel/api/clients/groups/bulkRemove" \ -H "Content-Type: application/json" \ -d '{ "emails": [ "alice", "bob" ] }'{ "success": true, "obj": { "affected": 2 }}AuthorizationBearer <token>Scoped API token from Settings → Security → API Token. Send as Authorization: Bearer <token>.
application/json- body
emails*array<string>Emails of existing clients to attach.
inboundIds*array<integer>Target inbound IDs to attach every client to.
Successful response
application/json- response
success?booleanmsg?stringobj?unknowncurl -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": [] }}AuthorizationBearer <token>Scoped API token from Settings → Security → API Token. Send as Authorization: Bearer <token>.
application/json- body
emails*array<string>Emails of existing clients to detach.
inboundIds*array<integer>Inbound IDs to detach the clients from.
Successful response
application/json- response
success?booleanmsg?stringobj?unknowncurl -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": [] }}AuthorizationBearer <token>Scoped API token from Settings → Security → API Token. Send as Authorization: Bearer <token>.
application/json- body
Successful response
application/json- response
success?booleanmsg?stringobj?unknowncurl -X POST "https://example.com/panel/api/clients/bulkResetTraffic" \ -H "Content-Type: application/json" \ -d '{ "emails": [ "alice", "bob" ] }'{ "success": true, "obj": { "affected": 2 }}AuthorizationBearer <token>Scoped API token from Settings → Security → API Token. Send as Authorization: Bearer <token>.
Successful response
application/json- response
success?booleanmsg?stringobj?unknowncurl -X GET "https://example.com/panel/api/clients/groups"{ "success": true, "obj": [ { "name": "customer-a", "clientCount": 5 }, { "name": "internal", "clientCount": 0 } ]}AuthorizationBearer <token>Scoped API token from Settings → Security → API Token. Send as Authorization: Bearer <token>.
name*stringGroup name (URL-encoded).
Successful response
application/json- response
success?booleanmsg?stringobj?unknowncurl -X GET "https://example.com/panel/api/clients/groups/string/emails"{ "success": true, "obj": [ "alice", "bob", "carol" ]}AuthorizationBearer <token>Scoped API token from Settings → Security → API Token. Send as Authorization: Bearer <token>.
application/json- body
Successful response
application/json- response
success?booleanmsg?stringobj?unknowncurl -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" }}AuthorizationBearer <token>Scoped API token from Settings → Security → API Token. Send as Authorization: Bearer <token>.
application/json- body
Successful response
application/json- response
success?booleanmsg?stringobj?unknowncurl -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 }}AuthorizationBearer <token>Scoped API token from Settings → Security → API Token. Send as Authorization: Bearer <token>.
application/json- body
Successful response
application/json- response
success?booleanmsg?stringobj?unknowncurl -X POST "https://example.com/panel/api/clients/groups/delete" \ -H "Content-Type: application/json" \ -d '{ "name": "customer-a" }'{ "success": true, "obj": { "affected": 5 }}AuthorizationBearer <token>Scoped API token from Settings → Security → API Token. Send as Authorization: Bearer <token>.
email*stringClient email.
Successful response
application/json- response
success?booleanmsg?stringobj?unknowncurl -X POST "https://example.com/panel/api/clients/resetTraffic/string"{ "success": true, "msg": "string", "obj": null}AuthorizationBearer <token>Scoped API token from Settings → Security → API Token. Send as Authorization: Bearer <token>.
email*stringClient email.
application/json- body
Successful response
application/json- response
success?booleanmsg?stringobj?unknowncurl -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}AuthorizationBearer <token>Scoped API token from Settings → Security → API Token. Send as Authorization: Bearer <token>.
email*stringClient email.
Successful response
application/json- response
success?booleanmsg?stringobj?unknowncurl -X POST "https://example.com/panel/api/clients/ips/string"{ "success": true, "msg": "string", "obj": null}AuthorizationBearer <token>Scoped API token from Settings → Security → API Token. Send as Authorization: Bearer <token>.
email*stringClient email.
Successful response
application/json- response
success?booleanmsg?stringobj?unknowncurl -X POST "https://example.com/panel/api/clients/clearIps/string"{ "success": true, "msg": "string", "obj": null}AuthorizationBearer <token>Scoped API token from Settings → Security → API Token. Send as Authorization: Bearer <token>.
Successful response
application/json- response
success?booleanmsg?stringobj?unknowncurl -X POST "https://example.com/panel/api/clients/onlines"{ "success": true, "obj": [ "user1", "user2" ]}AuthorizationBearer <token>Scoped API token from Settings → Security → API Token. Send as Authorization: Bearer <token>.
Successful response
application/json- response
success?booleanmsg?stringobj?unknowncurl -X POST "https://example.com/panel/api/clients/onlinesByGuid"{ "success": true, "obj": { "a1b2-...": [ "user1" ], "c3d4-...": [ "user1", "user2" ] }}AuthorizationBearer <token>Scoped API token from Settings → Security → API Token. Send as Authorization: Bearer <token>.
Successful response
application/json- response
success?booleanmsg?stringobj?unknowncurl -X POST "https://example.com/panel/api/clients/clientIpsByGuid"{ "success": true, "obj": { "a1b2-...": { "user1": [ { "ip": "1.2.3.4", "timestamp": 1700000000 } ] } }}AuthorizationBearer <token>Scoped API token from Settings → Security → API Token. Send as Authorization: Bearer <token>.
Successful response
application/json- response
success?booleanmsg?stringobj?unknowncurl -X POST "https://example.com/panel/api/clients/activeInbounds"{ "success": true, "obj": { "a1b2-...": [ "in-443-tcp", "in-8443-tcp" ] }}AuthorizationBearer <token>Scoped API token from Settings → Security → API Token. Send as Authorization: Bearer <token>.
Successful response
application/json- response
success?booleanmsg?stringobj?unknowncurl -X POST "https://example.com/panel/api/clients/lastOnline"{ "success": true, "obj": { "user1": 1700000000, "user2": 1699999000 }}AuthorizationBearer <token>Scoped API token from Settings → Security → API Token. Send as Authorization: Bearer <token>.
email*stringClient email (unique across the panel).
Successful response
application/json- response
success?booleanmsg?stringobj?ClientTraffic represents traffic statistics and limits for a specific client. It tracks upload/download usage, expiry times, and online status for inbound clients.
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, "resetWeekday": 0, "subId": "i7tvdpeffi0hvvf1", "total": 10737418240, "up": 1048576, "uuid": "e18c9a96-71bf-48d4-933f-8b9a46d4290c" }}AuthorizationBearer <token>Scoped API token from Settings → Security → API Token. Send as Authorization: Bearer <token>.
subId*stringSubscription ID, taken from the client's subId field.
Successful response
application/json- response
success?booleanmsg?stringobj?unknowncurl -X GET "https://example.com/panel/api/clients/subLinks/string"{ "success": true, "obj": [ "vless://uuid@host:443?security=reality&...#user1", "vmess://eyJ2IjoyLC..." ]}AuthorizationBearer <token>Scoped API token from Settings → Security → API Token. Send as Authorization: Bearer <token>.
email*stringClient email (unique identifier).
Successful response
application/json- response
success?booleanmsg?stringobj?unknowncurl -X GET "https://example.com/panel/api/clients/links/string"{ "success": true, "obj": [ "vless://uuid@host:443?...#user1" ]}