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

ورودی‌ها

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

List every inbound owned by the authenticated user, including each inbound’s clientStats traffic counters. settings, streamSettings, and sniffing are returned as nested JSON objects (no escaped strings); legacy callers that send them back as JSON-encoded strings are still accepted on write.

GET
/panel/api/inbounds/list

Authorization

headerAuthorizationBearer <token>

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

Response Body

Successful response

application/json
  1. response
success?boolean
msg?string
obj?array<>
curl -X GET "https://example.com/panel/api/inbounds/list"
{  "success": true,  "obj": [    {      "clientStats": [        {          "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"        }      ],      "disableFlow": false,      "down": 0,      "enable": true,      "excludeFromSub": false,      "expiryTime": 0,      "fallbackParent": null,      "id": 1,      "lastTrafficResetTime": 0,      "listen": "",      "nodeId": null,      "originNodeGuid": "",      "port": 443,      "protocol": "vless",      "remark": "VLESS-443",      "settings": null,      "shareAddr": "",      "shareAddrStrategy": "node",      "sniffing": null,      "streamSettings": null,      "subSortIndex": 1,      "tag": "in-443-tcp",      "total": 0,      "trafficReset": "never",      "trafficResetDay": 1,      "up": 0    }  ]}

Same shape as /list but with settings.clients[] stripped down to {email, enable, comment} and ClientStats not enriched with UUID/SubId. Use this for list pages; fetch /get/:id when you need the full per-client payload (uuid, password, flow, ...).

GET
/panel/api/inbounds/list/slim

Authorization

headerAuthorizationBearer <token>

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

Response Body

Successful response

application/json
  1. response
success?boolean
msg?string
obj?unknown
curl -X GET "https://example.com/panel/api/inbounds/list/slim"
{  "success": true,  "obj": [    {      "id": 1,      "remark": "VLESS-443",      "settings": {        "clients": [          {            "email": "alice",            "enable": true          }        ],        "decryption": "none"      },      "clientStats": []    }  ]}

Lightweight picker projection of the authenticated user’s inbounds. Returns id, remark, tag, protocol, port, a server-computed tlsFlowCapable flag (true for VLESS on TCP with tls or reality, or on XHTTP with VLESS encryption / vlessenc enabled), and ssMethod (the Shadowsocks cipher, empty for non-Shadowsocks inbounds — used by the client UI to generate a valid Shadowsocks 2022 PSK). Use this for dropdowns and attach pickers — it skips settings, streamSettings, and clientStats so the payload stays small even on panels with thousands of clients.

GET
/panel/api/inbounds/options

Authorization

headerAuthorizationBearer <token>

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

Response Body

Successful response

application/json
  1. response
success?boolean
msg?string
obj?array<>
curl -X GET "https://example.com/panel/api/inbounds/options"
{  "success": true,  "obj": [    {      "awgServer": null,      "enable": true,      "id": 1,      "listen": "",      "mtprotoDomain": "",      "network": "",      "nodeAddress": "",      "nodeId": null,      "port": 443,      "protocol": "vless",      "remark": "VLESS-443",      "security": "",      "shareAddr": "",      "shareAddrStrategy": "",      "ssMethod": "",      "tag": "in-443-tcp",      "tlsFlowCapable": true,      "tuicServer": null,      "wgDns": "",      "wgMtu": 0,      "wgPublicKey": ""    }  ]}

Fetch a single inbound by numeric ID.

GET
/panel/api/inbounds/get/{id}

Authorization

headerAuthorizationBearer <token>

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

Path Parameters

id*integer

Inbound ID.

Response Body

Successful response

application/json
  1. response
success?boolean
msg?string
obj?unknown
curl -X GET "https://example.com/panel/api/inbounds/get/0"
{  "success": true,  "msg": "string",  "obj": null}

Create a new inbound. Send the full inbound payload (protocol, port, settings, streamSettings, sniffing, remark, expiryTime, total, enable). settings, streamSettings, and sniffing may be sent as nested JSON objects (preferred) or as JSON-encoded strings (legacy).

POST
/panel/api/inbounds/add

Authorization

headerAuthorizationBearer <token>

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

Request Body

application/json
  1. body

Response Body

Successful response

application/json
  1. response
success?boolean
msg?string
obj?unknown
curl -X POST "https://example.com/panel/api/inbounds/add" \  -H "Content-Type: application/json" \  -d '{    "enable": true,    "remark": "VLESS-443",    "listen": "",    "port": 443,    "protocol": "vless",    "expiryTime": 0,    "total": 0,    "settings": {      "clients": [        {          "id": "...",          "email": "user1"        }      ],      "decryption": "none",      "fallbacks": []    },    "streamSettings": {      "network": "tcp",      "security": "reality",      "realitySettings": {        "show": false,        "dest": "..."      }    },    "sniffing": {      "enabled": true,      "destOverride": [        "http",        "tls"      ]    }  }'
{  "success": true,  "msg": "string",  "obj": null}

Delete an inbound by ID. Also removes its associated client stats rows.

POST
/panel/api/inbounds/del/{id}

Authorization

headerAuthorizationBearer <token>

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

Path Parameters

id*integer

Inbound ID.

Response Body

Successful response

application/json
  1. response
success?boolean
msg?string
obj?unknown
curl -X POST "https://example.com/panel/api/inbounds/del/0"
{  "success": true,  "msg": "string",  "obj": null}

Delete many inbounds in one call. Processes the list sequentially; failures are reported per id and the rest still proceed. Restarts xray at most once.

POST
/panel/api/inbounds/bulkDel

Authorization

headerAuthorizationBearer <token>

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

Request Body

application/json
  1. body

Response Body

Successful response

application/json
  1. response
success?boolean
msg?string
obj?unknown
curl -X POST "https://example.com/panel/api/inbounds/bulkDel" \  -H "Content-Type: application/json" \  -d '{    "ids": [      1,      2,      3    ]  }'
{  "success": true,  "obj": {    "deleted": 2,    "skipped": [      {        "id": 3,        "reason": "..."      }    ]  }}

Replace an inbound’s configuration. Body shape mirrors /add, but the inbound keeps its stored client list and enable flag: settings.clients and enable in the body are ignored. Manage clients through the /panel/api/clients endpoints and toggle the inbound with /setEnable.

POST
/panel/api/inbounds/update/{id}

Authorization

headerAuthorizationBearer <token>

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

Path Parameters

id*integer

Inbound ID.

Request Body

application/json
  1. body

Response Body

Successful response

application/json
  1. response
success?boolean
msg?string
obj?unknown
curl -X POST "https://example.com/panel/api/inbounds/update/0" \  -H "Content-Type: application/json" \  -d '{    "enable": true,    "remark": "VLESS-443",    "listen": "",    "port": 443,    "protocol": "vless",    "expiryTime": 0,    "total": 0,    "settings": {      "clients": [        {          "id": "...",          "email": "user1"        }      ],      "decryption": "none",      "fallbacks": []    },    "streamSettings": {      "network": "tcp",      "security": "reality",      "realitySettings": {        "show": false,        "dest": "..."      }    },    "sniffing": {      "enabled": true,      "destOverride": [        "http",        "tls"      ]    }  }'
{  "success": true,  "msg": "string",  "obj": null}
POST
/panel/api/inbounds/setEnable/{id}

Authorization

headerAuthorizationBearer <token>

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

Path Parameters

id*integer

Inbound ID.

Request Body

application/json
  1. body

Response Body

Successful response

application/json
  1. response
success?boolean
msg?string
obj?unknown
curl -X POST "https://example.com/panel/api/inbounds/setEnable/0" \  -H "Content-Type: application/json" \  -d '{    "enable": false  }'
{  "success": true,  "msg": "string",  "obj": null}

Zero out upload + download counters for a single inbound. Does not touch per-client counters.

POST
/panel/api/inbounds/{id}/resetTraffic

Authorization

headerAuthorizationBearer <token>

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

Path Parameters

id*integer

Inbound ID.

Response Body

Successful response

application/json
  1. response
success?boolean
msg?string
obj?unknown
curl -X POST "https://example.com/panel/api/inbounds/0/resetTraffic"
{  "success": true,  "msg": "string",  "obj": null}

Remove every client attached to a single inbound while keeping the inbound itself. Collects emails from settings.clients[] and feeds them into the optimized bulk-delete path (runtime user removal + traffic-row cleanup + SyncInbound). Destructive and cannot be undone.

POST
/panel/api/inbounds/{id}/delAllClients

Authorization

headerAuthorizationBearer <token>

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

Path Parameters

id*integer

Inbound ID.

Response Body

Successful response

application/json
  1. response
success?boolean
msg?string
obj?unknown
curl -X POST "https://example.com/panel/api/inbounds/0/delAllClients"
{  "success": true,  "obj": {    "deleted": 12  }}

Reset upload + download counters on every inbound. Destructive — accounting history is lost.

POST
/panel/api/inbounds/resetAllTraffics

Authorization

headerAuthorizationBearer <token>

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

Response Body

Successful response

application/json
  1. response
success?boolean
msg?string
obj?unknown
curl -X POST "https://example.com/panel/api/inbounds/resetAllTraffics"
{  "success": true,  "msg": "string",  "obj": null}

Bulk-import an inbound from a JSON blob (e.g. one exported via the UI). The body uses form encoding with a single "data" field.

POST
/panel/api/inbounds/import

Authorization

headerAuthorizationBearer <token>

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

Request Body

application/x-www-form-urlencoded
  1. body
data*string

JSON-encoded inbound payload.

Response Body

Successful response

application/json
  1. response
success?boolean
msg?string
obj?unknown
curl -X POST "https://example.com/panel/api/inbounds/import" \  -H "Content-Type: application/x-www-form-urlencoded" \  -d 'data=string'
{  "success": true,  "msg": "string",  "obj": null}

Receive a master panel's aggregated per-client usage, keyed by the master's GUID. Stored in a side table used only for the UI display overlay and local quota enforcement — never folded into the local counters that masters poll, so delta accounting stays intact. Called panel-to-panel by the node traffic sync job.

POST
/panel/api/inbounds/pushClientTraffics

Authorization

headerAuthorizationBearer <token>

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

Request Body

application/json
  1. body
masterGuid*string

Stable GUID of the pushing master panel.

traffics*array<>

Client traffic rows; only email/up/down are read.

Response Body

Successful response

application/json
  1. response
success?boolean
msg?string
obj?unknown
curl -X POST "https://example.com/panel/api/inbounds/pushClientTraffics" \  -H "Content-Type: application/json" \  -d '{    "masterGuid": "9f6c2d-…",    "traffics": [      {        "email": "alice",        "up": 1048576,        "down": 2097152      }    ]  }'
{  "success": true}
GET
/panel/api/inbounds/{id}/fallbacks

Authorization

headerAuthorizationBearer <token>

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

Path Parameters

id*integer

Master inbound ID.

Response Body

Successful response

application/json
  1. response
success?boolean
msg?string
obj?unknown
curl -X GET "https://example.com/panel/api/inbounds/0/fallbacks"
{  "success": true,  "obj": [    {      "id": 1,      "masterId": 10,      "childId": 11,      "name": "",      "alpn": "",      "path": "/vlws",      "dest": "",      "xver": 2,      "sortOrder": 0    }  ]}

Replace the entire fallback list for a master inbound. Body is JSON. Triggers an Xray restart.

POST
/panel/api/inbounds/{id}/fallbacks

Authorization

headerAuthorizationBearer <token>

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

Path Parameters

id*integer

Master inbound ID.

Request Body

application/json
  1. body
fallbacks*array<>

Array of {childId, name, alpn, path, dest, xver, sortOrder} entries. Leave dest empty to auto-resolve from the child inbound's listen+port; set it (e.g. "8443", "127.0.0.1:8443", "/dev/shm/x.sock") to override.

Response Body

Successful response

application/json
  1. response
success?boolean
msg?string
obj?unknown
curl -X POST "https://example.com/panel/api/inbounds/0/fallbacks" \  -H "Content-Type: application/json" \  -d '{    "fallbacks": [      {        "childId": 11,        "path": "/vlws",        "xver": 2      },      {        "childId": 12,        "alpn": "h2",        "dest": "8443"      }    ]  }'
{  "success": true,  "msg": "Inbound updated"}

توکن‌های API

مدیریت توکن‌های Bearer برای احراز هویت برنامه‌نویسی‌شده (ربات‌ها، پنل‌های مرکزی که از طرف این نود عمل می‌کنند، CI). هر توکن یک نام یکتا و یک پرچم فعال‌سازی دارد — برای لغو بدون حذف، آن را غیرفعال کنید و برای لغو دائمی، آن را حذف کنید. توکن‌ها به صورت هش SHA-256 ذخیره می‌شوند و متن خام تنها یک‌بار، در پاسخ ایجاد، بازگردانده می‌شود — پس از آن قابل بازیابی نیست، بنابراین همان موقع آن را کپی کنید. برای هر درخواست /panel/api/* یکی را به صورت <code>Authorization: Bearer &lt;token&gt;</code> ارسال کنید — این توکن یک اعتبارنامهٔ مدیر کامل است.

کلاینت‌ها

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