EasyXrayEasyXray

Xray Settings

Xray configuration template, outbound management, Warp/Nord/PIA integration, and config testing. All endpoints under /easyxray/api/v1/xray.

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

POST
/easyxray/api/v1/xray/

Authorization

headerAuthorizationBearer <token>

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/easyxray/api/v1/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 /easyxray/api/v1/setting/getDefaultJsonConfig).

GET
/easyxray/api/v1/xray/getDefaultJsonConfig

Authorization

headerAuthorizationBearer <token>

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

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

GET
/easyxray/api/v1/xray/getOutboundsTraffic

Authorization

headerAuthorizationBearer <token>

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/easyxray/api/v1/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
/easyxray/api/v1/xray/getXrayResult

Authorization

headerAuthorizationBearer <token>

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/easyxray/api/v1/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
/easyxray/api/v1/xray/update

Authorization

headerAuthorizationBearer <token>

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/easyxray/api/v1/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
/easyxray/api/v1/xray/warp/{action}

Authorization

headerAuthorizationBearer <token>

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/easyxray/api/v1/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
/easyxray/api/v1/xray/nord/{action}

Authorization

headerAuthorizationBearer <token>

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/easyxray/api/v1/xray/nord/string" \  -H "Content-Type: application/x-www-form-urlencoded" \  -d ''
{  "success": true,  "msg": "string",  "obj": null}

Manage PIA WireGuard integration. The action parameter selects the operation.

POST
/easyxray/api/v1/xray/pia/{action}

Authorization

headerAuthorizationBearer <token>

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

Path Parameters

action*string

countries — list available countries from the signed PIA server list. servers — list regions and WireGuard servers in a country (sends countryCode). reg — sign in with a PIA username and password (sends username, password). data — return the signed-in account hint. del — delete stored PIA credentials. addKey — register a WireGuard key with the selected server (sends hostname) and return fields to build the outbound.

Request Body

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

Required when action=reg.

password?string

Required when action=reg.

countryCode?string

Required when action=servers.

hostname?string

Required when action=addKey.

Response Body

Successful response

application/json
  1. response
success?boolean
msg?string
obj?unknown
curl -X POST "https://example.com/easyxray/api/v1/xray/pia/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
/easyxray/api/v1/xray/resetOutboundsTraffic

Authorization

headerAuthorizationBearer <token>

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/easyxray/api/v1/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
/easyxray/api/v1/xray/testOutbound

Authorization

headerAuthorizationBearer <token>

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/easyxray/api/v1/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
/easyxray/api/v1/xray/testOutbounds

Authorization

headerAuthorizationBearer <token>

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/easyxray/api/v1/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
/easyxray/api/v1/xray/balancerStatus

Authorization

headerAuthorizationBearer <token>

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/easyxray/api/v1/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
/easyxray/api/v1/xray/balancerOverride

Authorization

headerAuthorizationBearer <token>

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/easyxray/api/v1/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
/easyxray/api/v1/xray/routeTest

Authorization

headerAuthorizationBearer <token>

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/easyxray/api/v1/xray/routeTest" \  -H "Content-Type: application/x-www-form-urlencoded" \  -d 'domain=string'
{  "success": true,  "msg": "string",  "obj": null}

List the geo databases (.dat files) in the Xray asset folder, with the layout detected from their contents, size, modification time and category count. A database that fails to parse is still listed, with the reason in "error".

GET
/easyxray/api/v1/xray/geodata/files

Authorization

headerAuthorizationBearer <token>

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/easyxray/api/v1/xray/geodata/files"
{  "success": true,  "msg": "string",  "obj": null}

One page of a database's categories, each with its entry count and the attributes its domains carry (e.g. "ads", "cn").

GET
/easyxray/api/v1/xray/geodata/categories

Authorization

headerAuthorizationBearer <token>

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

Query Parameters

file*string

Database file name inside the asset folder, e.g. geosite.dat (required).

q?string

Case-insensitive substring filter on the category code.

offset?integer

Rows to skip. Defaults to 0.

limit?integer

Rows to return, capped at 500. Omit it to return every category — the index is small and the panel filters it client-side.

Response Body

Successful response

application/json
  1. response
success?boolean
msg?string
obj?unknown
curl -X GET "https://example.com/easyxray/api/v1/xray/geodata/categories?file=string"
{  "success": true,  "msg": "string",  "obj": null}

One page of the rules inside a category — domain rules typed as domain/full/keyword/regexp for geosite databases, CIDRs for geoip ones.

GET
/easyxray/api/v1/xray/geodata/entries

Authorization

headerAuthorizationBearer <token>

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

Query Parameters

file*string

Database file name inside the asset folder (required).

code*string

Category code, case-insensitive, e.g. google (required).

q?string

Case-insensitive substring filter on the rule value.

offset?integer

Rows to skip. Defaults to 0.

limit?integer

Rows to return, capped at 500. Defaults to the cap.

Response Body

Successful response

application/json
  1. response
success?boolean
msg?string
obj?unknown
curl -X GET "https://example.com/easyxray/api/v1/xray/geodata/entries?file=string&code=string"
{  "success": true,  "msg": "string",  "obj": null}

Check routing tokens against the databases on disk and return only the ones that do not resolve. Plain domains and CIDRs are ignored. Each issue carries a reason: syntax, fileMissing or categoryMissing.

POST
/easyxray/api/v1/xray/geodata/validate

Authorization

headerAuthorizationBearer <token>

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

Request Body

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

Comma-separated routing tokens, e.g. "geosite:google,geosite:blabla". Max 500 per request.

kind?string

"ip" to parse the tokens as IP rules (geoip:, ext-ip:, leading !). Anything else parses them as domain rules (geosite:, ext-site:).

Response Body

Successful response

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

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

GET
/easyxray/api/v1/xray/outbound-subs

Authorization

headerAuthorizationBearer <token>

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/easyxray/api/v1/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
/easyxray/api/v1/xray/outbound-subs

Authorization

headerAuthorizationBearer <token>

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 "easyxray-outbound-sub/1.0".

Default"easyxray-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/easyxray/api/v1/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
/easyxray/api/v1/xray/outbound-subs/{id}

Authorization

headerAuthorizationBearer <token>

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 "easyxray-outbound-sub/1.0".

Default"easyxray-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/easyxray/api/v1/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
/easyxray/api/v1/xray/outbound-subs/{id}

Authorization

headerAuthorizationBearer <token>

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/easyxray/api/v1/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
/easyxray/api/v1/xray/outbound-subs/{id}/del

Authorization

headerAuthorizationBearer <token>

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/easyxray/api/v1/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
/easyxray/api/v1/xray/outbound-subs/{id}/refresh

Authorization

headerAuthorizationBearer <token>

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/easyxray/api/v1/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
/easyxray/api/v1/xray/outbound-subs/{id}/move

Authorization

headerAuthorizationBearer <token>

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/easyxray/api/v1/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
/easyxray/api/v1/xray/outbound-subs/parse

Authorization

headerAuthorizationBearer <token>

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/easyxray/api/v1/xray/outbound-subs/parse" \  -H "Content-Type: application/x-www-form-urlencoded" \  -d 'url=string'
{  "success": true,  "msg": "string",  "obj": null}