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

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/inbounds/list"
{  "success": true,  "obj": [    {      "clientStats": [        {          "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"        }      ],      "down": 0,      "enable": true,      "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",      "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

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/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

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/inbounds/options"
{  "success": true,  "obj": [    {      "id": 1,      "nodeId": null,      "port": 443,      "protocol": "vless",      "remark": "VLESS-443",      "ssMethod": "",      "tag": "in-443-tcp",      "tlsFlowCapable": true    }  ]}

Fetch a single inbound by numeric ID.

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

Authorization

AuthorizationBearer <token>

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

In: header

Path Parameters

id*integer

Inbound ID.

Response Body

application/json

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

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

application/json

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}
{  "success": false,  "msg": "Port 443 is already in use"}

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

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

Authorization

AuthorizationBearer <token>

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

In: header

Path Parameters

id*integer

Inbound ID.

Response Body

application/json

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

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/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. Heavy on inbounds with thousands of clients — prefer /setEnable for enable-only flips.

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

Authorization

AuthorizationBearer <token>

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

In: header

Path Parameters

id*integer

Inbound ID.

Response Body

application/json

curl -X POST "https://example.com/panel/api/inbounds/update/0"
{  "success": true,  "msg": "string",  "obj": null}
POST
/panel/api/inbounds/setEnable/{id}

Authorization

AuthorizationBearer <token>

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

In: header

Path Parameters

id*integer

Inbound ID.

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/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

AuthorizationBearer <token>

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

In: header

Path Parameters

id*integer

Inbound ID.

Response Body

application/json

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

AuthorizationBearer <token>

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

In: header

Path Parameters

id*integer

Inbound ID.

Response Body

application/json

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

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/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

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/inbounds/import"
{  "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

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/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

AuthorizationBearer <token>

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

In: header

Path Parameters

id*integer

Master inbound ID.

Response Body

application/json

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

AuthorizationBearer <token>

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

In: header

Path Parameters

id*integer

Master inbound ID.

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/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 قرار دارند.