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

تنظیمات Xray

قالب پیکربندی Xray، مدیریت outboundها، یکپارچه‌سازی Warp/Nord و آزمایش پیکربندی. همه‌ی نقاط پایانی زیر /panel/api/xray قرار دارند.

Return the Xray config template (JSON string), available inbound tags, client reverse tags, and the configured outbound test URL in one response.

POST
/panel/api/xray/

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/xray/"
{  "success": true,  "obj": {    "xraySetting": "{...raw xray config...}",    "inboundTags": "[\"in-443-tcp\"]",    "clientReverseTags": "[]",    "outboundTestUrl": "https://www.google.com/generate_204"  }}

Return the built-in default Xray config shipped with the panel (identical to /panel/api/setting/getDefaultJsonConfig).

GET
/panel/api/xray/getDefaultJsonConfig

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/xray/getDefaultJsonConfig"
{  "success": true,  "msg": "string",  "obj": null}

Return traffic statistics for every outbound. Each outbound shows up/down/total counters.

GET
/panel/api/xray/getOutboundsTraffic

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/xray/getOutboundsTraffic"
{  "success": true,  "msg": "string",  "obj": null}

Return the most recent Xray process stdout/stderr output. Useful to check for startup errors or runtime warnings.

GET
/panel/api/xray/getXrayResult

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/xray/getXrayResult"
{  "success": true,  "msg": "string",  "obj": null}

Save the Xray JSON config template and optionally the outbound test URL. Both are sent as form fields.

POST
/panel/api/xray/update

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
xraySetting*string

Full Xray JSON config template.

outboundTestUrl?string

URL used for outbound reachability tests. Defaults to https://www.google.com/generate_204.

Response Body

Successful response

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

Manage Cloudflare Warp integration. The action parameter selects the operation.

POST
/panel/api/xray/warp/{action}

Authorization

headerAuthorizationBearer <token>

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

Path Parameters

action*string

data — return Warp stats. del — delete Warp data. config — return current config. reg — register (sends keys). regMasque — register a separate device enrolled for MASQUE and return its warp key pair, addresses and endpoint. changeIp — rotate the endpoint. license — set a Warp+ key. interval — set automatic rotation in hours.

Request Body

application/x-www-form-urlencoded
  1. body
privateKey?string

Required when action=reg.

publicKey?string

Required when action=reg.

license?string

Required when action=license.

interval?integer

Non-negative hours between automatic rotations. Required when action=interval; 0 disables rotation.

Response Body

Successful response

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

Manage NordVPN integration. The action parameter selects the operation.

POST
/panel/api/xray/nord/{action}

Authorization

headerAuthorizationBearer <token>

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

Path Parameters

action*string

countries — list available countries. servers — list servers in a country (sends countryId). reg — get NordVPN credentials (sends token). setKey — store NordVPN API key (sends key). data — return current NordVPN connection data. del — delete NordVPN data.

Request Body

application/x-www-form-urlencoded
  1. body
countryId?string

Required when action=servers.

token?string

Required when action=reg.

key?string

Required when action=setKey.

Response Body

Successful response

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

Reset traffic counters for a specific outbound by tag.

POST
/panel/api/xray/resetOutboundsTraffic

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
tag*string

Outbound tag to reset (e.g. "proxy", "direct").

Response Body

Successful response

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

Test an outbound configuration. Sends the outbound JSON (required), optionally all outbounds (to resolve sockopt.dialerProxy dependencies), and a mode flag.

POST
/panel/api/xray/testOutbound

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
outbound*string

JSON-encoded single outbound to test (required).

allOutbounds?string

JSON array of all outbounds — used to resolve dialerProxy chains.

mode?string

"tcp" for a fast dial-only probe (parallel-safe), "real" for a real-delay probe whose delay is the full request time including tunnel establishment. Default/empty uses a full HTTP probe reporting the warm per-request round-trip. Both HTTP variants run through a temp xray instance.

Response Body

Successful response

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

Test a batch of outbounds (max 50) through one shared temp xray instance. Returns an array of results in input order, each with the outbound tag, delay, HTTP status and a connect/TLS/TTFB timing breakdown.

POST
/panel/api/xray/testOutbounds

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
outbounds*string

JSON array of outbound configs to test (required).

allOutbounds?string

JSON array of all outbounds — used to resolve dialerProxy chains.

mode?string

"tcp" for fast dial-only probes (UDP-transport outbounds are still probed over HTTP), "real" for real-delay probes whose delay is the full request time including tunnel establishment. Default/empty routes an HTTP request through each outbound and reports the warm per-request round-trip.

Response Body

Successful response

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

Live state of routing balancers in the running core (RoutingService.GetBalancerInfo): current override and the targets the strategy prefers. Returns a map keyed by balancer tag.

POST
/panel/api/xray/balancerStatus

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
tags*string

Comma-separated balancer tags to query (e.g. "b1,b2").

Response Body

Successful response

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

Force a balancer in the running core to always pick one outbound (RoutingService.OverrideBalancerTarget). Applied live without a restart and kept across config saves; cleared when Xray restarts or the target outbound is removed.

POST
/panel/api/xray/balancerOverride

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
tag*string

Balancer tag (required).

target?string

Outbound tag to force; it must exist in the running config. Empty clears the override and returns control to the strategy.

Response Body

Successful response

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

Ask the running core which outbound its router would pick for a synthetic connection (RoutingService.TestRoute). No traffic is sent.

POST
/panel/api/xray/routeTest

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
domain*string

Target domain. Either domain or ip is required.

Length1 <= length
ip?string

Target IP. Either domain or ip is required.

port?integer

Target port (optional).

network?string

"tcp" (default) or "udp".

inboundTag?string

Simulate arrival on this inbound (optional).

protocol?string

Sniffed protocol such as http, tls, bittorrent (optional).

email?string

User attribution for user-based rules (optional).

Response Body

Successful response

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

List all outbound subscriptions (remote URLs that supply additional outbounds), newest first.

GET
/panel/api/xray/outbound-subs

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/xray/outbound-subs"
{  "success": true,  "msg": "string",  "obj": null}

Create an outbound subscription. The URL is fetched, parsed into outbounds with stable tags, and merged additively into the running Xray config.

POST
/panel/api/xray/outbound-subs

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
remark?string

Optional display label.

url*string

Subscription URL (required). Must be a public http(s) address; private/internal targets are blocked unless allowPrivate is true.

tagPrefix?string

Prefix for generated outbound tags. Defaults to the lowest free "sub-" prefix.

userAgent?string

Custom User-Agent sent when fetching this subscription. Defaults to "3x-ui-outbound-sub/1.0".

Default"3x-ui-outbound-sub/1.0"
updateInterval?integer

Seconds between auto-refreshes. Default 600.

Default600
enabled?boolean

Whether the subscription is active. Default true.

Defaulttrue
allowPrivate?boolean

Allow the URL to point at a private/internal/loopback address. Default false.

Defaultfalse
allowInsecure?boolean

Skip TLS certificate verification when fetching the subscription's URL. Default false.

Defaultfalse
prepend?boolean

Place this subscription's outbounds before the manual template outbounds. Default false.

Defaultfalse

Response Body

Successful response

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

Update an existing outbound subscription by id. Accepts the same form fields as create.

POST
/panel/api/xray/outbound-subs/{id}

Authorization

headerAuthorizationBearer <token>

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

Path Parameters

id*integer

Subscription id.

Request Body

application/x-www-form-urlencoded
  1. body
remark?string

Optional display label.

url*string

Subscription URL (required). Must be a public http(s) address; private/internal targets are blocked unless allowPrivate is true.

tagPrefix?string

Prefix for generated outbound tags. Defaults to the lowest free "sub-" prefix.

userAgent?string

Custom User-Agent sent when fetching this subscription. Defaults to "3x-ui-outbound-sub/1.0".

Default"3x-ui-outbound-sub/1.0"
updateInterval?integer

Seconds between auto-refreshes. Default 600.

Default600
enabled?boolean

Whether the subscription is active. Default true.

Defaulttrue
allowPrivate?boolean

Allow the URL to point at a private/internal/loopback address. Default false.

Defaultfalse
allowInsecure?boolean

Skip TLS certificate verification when fetching the subscription's URL. Default false.

Defaultfalse
prepend?boolean

Place this subscription's outbounds before the manual template outbounds. Default false.

Defaultfalse

Response Body

Successful response

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

Delete an outbound subscription by id.

DELETE
/panel/api/xray/outbound-subs/{id}

Authorization

headerAuthorizationBearer <token>

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

Path Parameters

id*integer

Subscription id.

Response Body

Successful response

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

Delete an outbound subscription by id (POST alias of DELETE for clients that cannot send DELETE).

POST
/panel/api/xray/outbound-subs/{id}/del

Authorization

headerAuthorizationBearer <token>

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

Path Parameters

id*integer

Subscription id.

Response Body

Successful response

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

Force an immediate re-fetch of the subscription and return the parsed outbounds. Signals Xray to reload.

POST
/panel/api/xray/outbound-subs/{id}/refresh

Authorization

headerAuthorizationBearer <token>

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

Path Parameters

id*integer

Subscription id.

Response Body

Successful response

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

Reorder a subscription one step up or down in priority (controls its position in the merged outbounds).

POST
/panel/api/xray/outbound-subs/{id}/move

Authorization

headerAuthorizationBearer <token>

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

Path Parameters

id*integer

Subscription id.

Request Body

application/x-www-form-urlencoded
  1. body
dir?string

"up" to raise priority, anything else to lower it.

Response Body

Successful response

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

Preview a subscription URL: fetch and parse it into outbounds without persisting anything.

POST
/panel/api/xray/outbound-subs/parse

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
url*string

Subscription URL to preview (required).

userAgent?string

Custom User-Agent sent while fetching the preview.

allowPrivate?boolean

Allow a private/internal/loopback URL. Default false.

allowInsecure?boolean

Skip TLS certificate verification. Default false.

Response Body

Successful response

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

تنظیمات

پیکربندی پنل و اطلاعات ورود کاربر. همه‌ی نقاط پایانی زیر /panel/api/setting قرار دارند و به یک نشست واردشده یا توکن Bearer نیاز دارند.

سرور اشتراک

یک سرور HTTP/HTTPS جداگانه که لینک‌های اشتراک پراکسی (استاندارد، JSON و Clash) را به کلاینت‌ها ارائه می‌دهد. این سرور روی پورت اختصاصی خودش (به‌صورت پیش‌فرض 2096) گوش می‌دهد و در بخش Settings ← Subscription پیکربندی می‌شود. پنل‌های جدید برای هر قالب پیشوند مسیر تصادفی تولید می‌کنند و همه‌ی مسیرها قابل پیکربندی می‌مانند. همه‌ی نقاط پایانی اشتراک، هدرهای پاسخ را برای خواندن اطلاعات ترافیک/انقضا توسط برنامه‌های کلاینت تنظیم می‌کنند.