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

سرور

وضعیت سیستم، دریافت لاگ، تولیدکننده‌های گواهی، مدیریت باینری Xray و پشتیبان‌گیری/بازیابی. همگی زیرمجموعهٔ /panel/api/server.

Real-time machine snapshot: CPU, memory, swap, disk, network IO, load averages, open connections, Xray state. Cached and refreshed every 2 seconds in the background.

GET
/panel/api/server/status

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/server/status"
{  "success": true,  "obj": {    "cpu": 12.5,    "mem": {      "current": 2147483648,      "total": 8589934592    },    "swap": {      "current": 0,      "total": 4294967296    },    "disk": {      "current": 53687091200,      "total": 268435456000    },    "netIO": {      "up": 1073741824,      "down": 2147483648    },    "xray": {      "state": "running",      "version": "v25.10.31"    },    "tcpCount": 42,    "load": {      "load1": 0.5,      "load5": 0.3,      "load15": 0.2    }  }}

Reports whether per-client IP limits can be enforced on this host. The panel uses it to gate the "IP Limit" field, since enforcement depends on Fail2ban being installed.

GET
/panel/api/server/fail2banStatus

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/server/fail2banStatus"
{  "success": true,  "obj": {    "enabled": true,    "installed": true,    "usable": true,    "windows": false  }}

Legacy: aggregated CPU history. Use /history/cpu/:bucket instead — same data with a uniform {t, v} shape.

GET
/panel/api/server/cpuHistory/{bucket}

Authorization

headerAuthorizationBearer <token>

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

Path Parameters

bucket*integer

Bucket size in seconds. Allowed: 2, 30, 60, 120, 180, 300.

Response Body

Successful response

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

Aggregated time-series for one metric. Returns an array of {t, v} samples covering the last ~6 hours.

GET
/panel/api/server/history/{metric}/{bucket}

Authorization

headerAuthorizationBearer <token>

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

Path Parameters

metric*string

cpu | mem | netUp | netDown | online | load1 | load5 | load15.

bucket*integer

Bucket size in seconds. Allowed: 2, 30, 60, 120, 180, 300.

Response Body

Successful response

application/json
  1. response
success?boolean
msg?string
obj?unknown
curl -X GET "https://example.com/panel/api/server/history/string/0"
{  "success": true,  "obj": [    {      "t": 1700000000,      "v": 12.5    },    {      "t": 1700000002,      "v": 13.1    }  ]}

Xray runtime metrics state — whether the xray config has a `metrics` block, which expvar keys are flowing, and the current snapshot values for each. Returns an empty state when metrics are not configured.

GET
/panel/api/server/xrayMetricsState

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

Time-series history for one Xray runtime metric over the last ~6 hours. Same {t, v} shape as /history/:metric/:bucket.

GET
/panel/api/server/xrayMetricsHistory/{metric}/{bucket}

Authorization

headerAuthorizationBearer <token>

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

Path Parameters

metric*string

xrAlloc | xrSys | xrHeapObjects | xrNumGC | xrPauseNs.

bucket*integer

Bucket size in seconds. Allowed: 2, 30, 60, 120, 180, 300.

Response Body

Successful response

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

Latest snapshot from the Xray observatory — per-outbound latency, health status, and last-probe time. Only populated when the Xray config has an observatory configured.

GET
/panel/api/server/xrayObservatory

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

Time-series of observatory probe results for one outbound tag. Same {t, v} shape as the other history endpoints.

GET
/panel/api/server/xrayObservatoryHistory/{tag}/{bucket}

Authorization

headerAuthorizationBearer <token>

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

Path Parameters

tag*string

Outbound tag from the observatory config.

bucket*integer

Bucket size in seconds. Allowed: 2, 30, 60, 120, 180, 300.

Response Body

Successful response

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

List Xray binary versions available for install on this host.

GET
/panel/api/server/getXrayVersion

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/server/getXrayVersion"
{  "success": true,  "obj": [    "v25.10.31",    "v25.9.15",    "v25.8.1"  ]}

Check whether a newer 3x-ui release is available on GitHub.

GET
/panel/api/server/getPanelUpdateInfo

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

Return the assembled Xray config that’s currently running on this host.

GET
/panel/api/server/getConfigJson

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

Stream a full database backup as an attachment: the SQLite .db file on SQLite panels, or a pg_dump custom-format archive (.dump) on PostgreSQL panels. Use as a manual backup.

GET
/panel/api/server/getDb

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

Stream a cross-engine migration file as an attachment: a .dump (SQL text) on SQLite, or a .db SQLite database built from the live data on PostgreSQL.

GET
/panel/api/server/getMigration

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

Generate a fresh UUID v4. Convenience helper for client IDs.

GET
/panel/api/server/getNewUUID

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?
curl -X GET "https://example.com/panel/api/server/getNewUUID"
{  "success": true,  "obj": {    "uuid": "550e8400-e29b-41d4-a716-446655440000"  }}

Return this panel's own web TLS certificate and key file paths. The central panel calls it on a node (via the node API token) so "Set Cert from Panel" fills a node-assigned inbound with paths that exist on the node.

GET
/panel/api/server/getWebCertFiles

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/server/getWebCertFiles"
{  "success": true,  "obj": {    "webCertFile": "/root/cert/example.com/fullchain.pem",    "webKeyFile": "/root/cert/example.com/privkey.pem"  }}

Read-only summaries (guid, parentGuid, name, address, status, versions) of the nodes this panel manages. A parent panel calls it on a node (via the node API token) to surface transitive sub-nodes in a chained topology. Counts are computed by the parent, not returned here.

GET
/panel/api/server/descendants

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/server/descendants"
{  "success": true,  "obj": [    {      "guid": "c3d4-...",      "parentGuid": "a1b2-...",      "name": "Node3",      "address": "10.0.0.3",      "status": "online"    }  ]}

Generate a new X25519 keypair for Reality.

GET
/panel/api/server/getNewX25519Cert

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/server/getNewX25519Cert"
{  "success": true,  "obj": {    "privateKey": "uN9qLfV3zH8w...",    "publicKey": "5v8xPqR2sM7k..."  }}

Generate a new ML-DSA-65 keypair. Returns {seed, verify}.

GET
/panel/api/server/getNewmldsa65

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?
curl -X GET "https://example.com/panel/api/server/getNewmldsa65"
{  "success": true,  "obj": {    "seed": "mldsa65-seed",    "verify": "mldsa65-verify"  }}

Generate a new ML-KEM-768 keypair. Returns {seed, client}.

GET
/panel/api/server/getNewmlkem768

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?
curl -X GET "https://example.com/panel/api/server/getNewmlkem768"
{  "success": true,  "obj": {    "client": "mlkem768-client",    "seed": "mlkem768-seed"  }}

Generate VLESS encryption auth options. Returns an auths array each with id, label, encryption, and decryption fields.

GET
/panel/api/server/getNewVlessEnc

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/server/getNewVlessEnc"
{  "success": true,  "obj": {    "auths": [      {        "id": 0,        "label": "Auth #0",        "encryption": "aes-256-gcm",        "decryption": ""      }    ]  }}

Stop the Xray binary. All proxies go offline immediately.

POST
/panel/api/server/stopXrayService

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

Reload Xray with the current config. Typically required after structural inbound or routing changes.

POST
/panel/api/server/restartXrayService

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

Download and install the specified Xray version. Pass "latest" for the newest release.

POST
/panel/api/server/installXray/{version}

Authorization

headerAuthorizationBearer <token>

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

Path Parameters

version*string

Xray tag (e.g. v25.10.31) or "latest".

Response Body

Successful response

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

Self-update the panel to the latest version. The server restarts on success. Bearer-token callers need admin or node-admin scope.

POST
/panel/api/server/updatePanel

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
dev?boolean

Override this run's channel. Omit to use the panel's configured channel.

Response Body

Successful response

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

Toggle the panel update channel between stable and the rolling per-commit dev release. Only effective on dev builds.

POST
/panel/api/server/setUpdateChannel

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
dev*boolean

true = dev channel, false = stable.

Response Body

Successful response

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

Refresh the default GeoIP / GeoSite data files. Use the /:fileName variant to update one file.

POST
/panel/api/server/updateGeofile

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

Refresh a single Geo file by filename (e.g. geoip.dat, geosite.dat).

POST
/panel/api/server/updateGeofile/{fileName}

Authorization

headerAuthorizationBearer <token>

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

Path Parameters

fileName*string

Filename of the data file to refresh.

Response Body

Successful response

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

Return the last N lines of the panel’s own log.

POST
/panel/api/server/logs/{count}

Authorization

headerAuthorizationBearer <token>

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

Path Parameters

count*integer

Number of trailing log lines.

Request Body

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

Minimum log level filter.

syslog?boolean

Read system logs instead of the panel log.

Response Body

Successful response

application/json
  1. response
success?boolean
msg?string
obj?array<string>|null
curl -X POST "https://example.com/panel/api/server/logs/0" \  -H "Content-Type: application/x-www-form-urlencoded" \  -d ''
{  "success": true,  "obj": [    "2025/01/01 12:00:00 [INFO] Server started",    "2025/01/01 12:00:01 [INFO] Xray is running"  ]}

Return the last N lines of the Xray process log.

POST
/panel/api/server/xraylogs/{count}

Authorization

headerAuthorizationBearer <token>

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

Path Parameters

count*integer

Number of trailing log lines.

Request Body

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

Keyword filter — only lines containing this string.

showDirect?string

"true" to include direct (freedom) traffic lines.

showBlocked?string

"true" to include blocked (blackhole) traffic lines.

showProxy?string

"true" to include proxy traffic lines.

Response Body

Successful response

application/json
  1. response
success?boolean
msg?string
obj?array<>|null
curl -X POST "https://example.com/panel/api/server/xraylogs/0" \  -H "Content-Type: application/x-www-form-urlencoded" \  -d ''
{  "success": true,  "obj": [    {      "DateTime": "2025-01-01T12:00:00Z",      "Email": "alice@example.com",      "Event": 0,      "FromAddress": "192.0.2.10:54321",      "Inbound": "inbound-443",      "Outbound": "direct",      "ToAddress": "example.com:443"    }  ]}

Restore the panel DB from an uploaded backup (multipart form, field name "db"). SQLite panels accept a SQLite database (.db) or a SQLite migration dump (.dump); PostgreSQL panels accept a pg_dump archive (.dump), a SQLite database (.db), or a SQLite migration dump. The panel restarts after restore. Destructive.

POST
/panel/api/server/importDB

Authorization

headerAuthorizationBearer <token>

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

Request Body

multipart/form-data
  1. body
db*unknown

Database backup or migration file to upload.

keepHostSettings?boolean

Keep this machine's addresses, certificates and node identity. Default true.

Defaulttrue

Response Body

Successful response

application/json
  1. response
success?boolean
msg?string
obj?unknown
curl -X POST "https://example.com/panel/api/server/importDB" \  -F db="null"
{  "success": true,  "msg": "string",  "obj": null}

Generate a new ECH (Encrypted Client Hello) keypair and config list for the given SNI.

POST
/panel/api/server/getNewEchCert

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

Server Name Indication to generate the ECH config for.

Response Body

Successful response

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

Compute the hex SHA-256 of a certificate (DER) for pinning (pinnedPeerCertSha256). Provide either a server file path or inline PEM/DER content.

POST
/panel/api/server/getCertHash

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

Path to a certificate file on the server. Takes precedence over certContent.

Match.*\S.*
certContent?string

Inline PEM (or DER) certificate content, used when certFile is empty.

Response Body

Successful response

application/json
  1. response
success?boolean
msg?string
obj?unknown
curl -X POST "https://example.com/panel/api/server/getCertHash" \  -H "Content-Type: application/x-www-form-urlencoded" \  -d 'certFile=string'
{  "success": true,  "obj": [    "e8e2d3..."  ]}

Run `xray tls ping` against a remote server and return its live leaf-certificate SHA-256 hash(es) for pinning (pinnedPeerCertSha256).

POST
/panel/api/server/getRemoteCertHash

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

Remote server as domain or domain:port (default port 443), e.g. cloudflare-dns.com.

allowPrivate?boolean

Ping a private/internal/loopback server (LAN, Docker service name). Default false (SSRF guard blocks it and the error response sets obj.privateTarget=true).

Response Body

Successful response

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

Fetch the fully aggregated inbound_client_ips database table. Used by nodes to sync recently active IPs across the cluster.

GET
/panel/api/server/clientIps

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/server/clientIps"
{  "success": true,  "obj": [    {      "clientEmail": "",      "id": 0,      "ips": null    }  ]}

Submit a list of recently active IP timestamps. The panel merges them with the existing database to maintain a unified global IP-limit view.

POST
/panel/api/server/clientIps

Authorization

headerAuthorizationBearer <token>

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

Request Body

application/json
  1. body
[index: integer]?

Response Body

Successful response

application/json
  1. response
success?boolean
msg?string
obj?unknown
curl -X POST "https://example.com/panel/api/server/clientIps" \  -H "Content-Type: application/json" \  -d '[    {      "clientEmail": "string",      "ips": [        {          "ip": "string",          "timestamp": 0        }      ]    }  ]'
{  "success": true,  "msg": "string",  "obj": null}

کلاینت‌ها

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

تنظیمات

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