3x-ui3x-ui

Nodes

Manage remote 3x-ui panels acting as nodes for a central panel. All endpoints under /panel/api/nodes.

List every configured node with its connection details, health, and last heartbeat patch.

GET
/panel/api/nodes/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/nodes/list"
{  "success": true,  "obj": [    {      "activeCount": 23,      "address": "node1.example.com",      "allowPrivateAddress": false,      "apiToken": "abcdef0123456789",      "basePath": "/",      "clientCount": 27,      "configDirty": false,      "configDirtyAt": 0,      "cpuPct": 23.5,      "createdAt": 1700000000,      "depletedCount": 1,      "disabledCount": 3,      "enable": true,      "guid": "",      "id": 1,      "inboundCount": 5,      "inboundSyncMode": "all",      "inboundTags": [        ""      ],      "lastError": "",      "lastHeartbeat": 1700000000,      "latencyMs": 42,      "memPct": 45.1,      "name": "de-fra-1",      "netDown": 2097152,      "netUp": 1048576,      "onlineCount": 3,      "outboundTag": "",      "panelVersion": "v3.x.x",      "parentGuid": "",      "pinnedCertSha256": "",      "port": 2053,      "remark": "",      "scheme": "https",      "status": "online",      "tlsVerifyMode": "verify",      "transitive": false,      "updatedAt": 1700000000,      "uptimeSecs": 86400,      "xrayError": "",      "xrayState": "",      "xrayVersion": "25.10.31"    }  ]}

This panel's node-auth CA certificate (public, PEM) to paste into a node's mTLS trust setting. Lazily mints the CA and the master client cert on first call. Pair with setting tlsVerifyMode=mtls on the node.

POST
/panel/api/nodes/mtls/ca

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/nodes/mtls/ca"
{  "success": true,  "obj": {    "caCert": "-----BEGIN CERTIFICATE-----\n...\n-----END CERTIFICATE-----\n"  }}

Set the CA certificate this panel trusts for incoming node-API client certificates (this panel acting as a node). Paste the managing panel's CA (from nodes/mtls/ca). An empty caCert disables it. A non-empty value must be a PEM certificate. Applied on the next panel restart.

POST
/panel/api/nodes/mtls/trustCA

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/nodes/mtls/trustCA" \  -H "Content-Type: application/json" \  -d '{    "caCert": "-----BEGIN CERTIFICATE-----\\n...\\n-----END CERTIFICATE-----\\n"  }'
{  "success": true,  "msg": "string",  "obj": null}

Fetch a single node by ID.

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

Authorization

AuthorizationBearer <token>

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

In: header

Path Parameters

id*integer

Node ID.

Response Body

application/json

curl -X GET "https://example.com/panel/api/nodes/get/0"
{  "success": true,  "msg": "string",  "obj": null}

Fetch a node's own web TLS certificate/key file paths (proxied to the node). Used by the inbound form's "Set Cert from Panel" so a node-assigned inbound gets paths that exist on the node, not the central panel.

GET
/panel/api/nodes/webCert/{id}

Authorization

AuthorizationBearer <token>

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

In: header

Path Parameters

id*integer

Node ID.

Response Body

application/json

curl -X GET "https://example.com/panel/api/nodes/webCert/0"
{  "success": true,  "obj": {    "webCertFile": "/root/cert/example.com/fullchain.pem",    "webKeyFile": "/root/cert/example.com/privkey.pem"  }}

Register a new remote node. Provide its URL, apiToken, and optional remark / allowPrivateAddress flag.

POST
/panel/api/nodes/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

curl -X POST "https://example.com/panel/api/nodes/add" \  -H "Content-Type: application/json" \  -d '{    "name": "de-fra-1",    "remark": "",    "scheme": "https",    "address": "node1.example.com",    "port": 2053,    "basePath": "/",    "apiToken": "abcdef...",    "enable": true,    "allowPrivateAddress": false  }'
{  "success": true,  "msg": "string",  "obj": null}

Replace a node’s connection details. Same body shape as /add.

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

Authorization

AuthorizationBearer <token>

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

In: header

Path Parameters

id*integer

Node 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/nodes/update/0" \  -H "Content-Type: application/json" \  -d '{    "name": "de-fra-1",    "remark": "",    "scheme": "https",    "address": "node1.example.com",    "port": 2053,    "basePath": "/",    "apiToken": "abcdef...",    "enable": true,    "allowPrivateAddress": false  }'
{  "success": true,  "msg": "string",  "obj": null}

Delete a node. Inbounds bound to it are not auto-migrated.

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

Authorization

AuthorizationBearer <token>

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

In: header

Path Parameters

id*integer

Node ID.

Response Body

application/json

curl -X POST "https://example.com/panel/api/nodes/del/0"
{  "success": true,  "msg": "string",  "obj": null}

Pause or resume traffic sync with this node.

POST
/panel/api/nodes/setEnable/{id}

Authorization

AuthorizationBearer <token>

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

In: header

Path Parameters

id*integer

Node 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/nodes/setEnable/0" \  -H "Content-Type: application/json" \  -d '{    "enable": true  }'
{  "success": true,  "msg": "string",  "obj": null}

Probe a node without saving it. Uses the body as connection details and returns the same heartbeat snapshot a registered node would have.

POST
/panel/api/nodes/test

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/nodes/test" \  -H "Content-Type: application/json" \  -d '{    "scheme": "https",    "address": "node1.example.com",    "port": 2053,    "basePath": "/",    "apiToken": "abcdef..."  }'
{  "success": true,  "obj": {    "cpuPct": 12.5,    "error": "",    "latencyMs": 42,    "memPct": 45.2,    "panelVersion": "v3.x.x",    "status": "online",    "uptimeSecs": 86400,    "xrayError": "",    "xrayState": "",    "xrayVersion": "25.10.31"  }}

Connect to the node over HTTPS without verifying its certificate and return the leaf certificate's SHA-256 (base64). Used by the Add/Edit Node dialog to fetch and pin a self-signed certificate. Uses the same body as /test.

POST
/panel/api/nodes/certFingerprint

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/nodes/certFingerprint" \  -H "Content-Type: application/json" \  -d '{    "scheme": "https",    "address": "node1.example.com",    "port": 2053,    "basePath": "/"  }'
{  "success": true,  "obj": "k3b1...base64-sha256...="}

Use unsaved node connection details to list the remote inbounds available for selective import.

POST
/panel/api/nodes/inbounds

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/nodes/inbounds" \  -H "Content-Type: application/json" \  -d '{    "name": "de-fra-1",    "scheme": "https",    "address": "node1.example.com",    "port": 2053,    "basePath": "/",    "apiToken": "abcdef..."  }'
{  "success": true,  "obj": [    {      "tag": "inbound-443",      "remark": "VLESS",      "protocol": "vless",      "port": 443    }  ]}

Probe an existing node, updating its cached health state.

POST
/panel/api/nodes/probe/{id}

Authorization

AuthorizationBearer <token>

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

In: header

Path Parameters

id*integer

Node ID.

Response Body

application/json

curl -X POST "https://example.com/panel/api/nodes/probe/0"
{  "success": true,  "msg": "string",  "obj": null}

Trigger the official panel self-updater on each given node (downloads the latest release and restarts). Only enabled, online nodes are updated; offline/disabled ones are reported as skipped. Set "dev": true to move the nodes to the rolling per-commit dev channel instead of the latest stable release. Returns a per-node result list.

POST
/panel/api/nodes/updatePanel

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/nodes/updatePanel" \  -H "Content-Type: application/json" \  -d '{    "ids": [      1,      2,      3    ],    "dev": false  }'
{  "success": true,  "obj": [    {      "id": 1,      "name": "de-1",      "ok": true    },    {      "id": 2,      "name": "fr-1",      "ok": false,      "error": "node is offline"    }  ]}

Aggregated metric history for a node — same shape as /server/history, scoped to one node.

GET
/panel/api/nodes/history/{id}/{metric}/{bucket}

Authorization

AuthorizationBearer <token>

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

In: header

Path Parameters

id*integer

Node ID.

metric*string

cpu | mem.

bucket*integer

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

Response Body

application/json

curl -X GET "https://example.com/panel/api/nodes/history/0/string/0"
{  "success": true,  "msg": "string",  "obj": null}