Nodes

Add, monitor and manage Xray nodes.

20 endpoints

POST `/api/node`

Add Node

Add a new node to the database and optionally add it as a host.

Sudo admin only

Request body application/json · NodeCreate

Field	Type	Required	Description
`name`	`string`	yes
`address`	`string`	yes
`port`	`integer`	no	Default: `62050`.
`api_port`	`integer`	no	Default: `62051`.
`usage_coefficient`	`number`	no	Default: `1.0`.
`agent_enabled`	`boolean`	no	Default: `true`.
`ip_limit_enabled`	`boolean`	no	Default: `true`.
`add_as_new_host`	`boolean`	no	Default: `true`.
`core_id`	`string`	no	Default: `"main"`.

json

{
  "add_as_new_host": true,
  "address": "192.168.1.1",
  "api_port": 62051,
  "name": "DE node",
  "port": 62050,
  "usage_coefficient": 1
}

Response 200 Successful Response · NodeResponse

Response fields

Field	Type	Description
`name`	`string`
`address`	`string`
`port`	`integer`
`api_port`	`integer`
`usage_coefficient`	`number`
`agent_enabled`	`boolean`
`ip_limit_enabled`	`boolean`
`id`	`integer`
`xray_version`	`string`
`status`	`connected` / `connecting` / `error` / `disabled`
`message`	`string`
`core_id`	`string`

json

{
  "name": "string",
  "address": "string",
  "port": 62050,
  "api_port": 62051,
  "usage_coefficient": 1.0,
  "agent_enabled": true,
  "ip_limit_enabled": true,
  "id": 0,
  "xray_version": "string",
  "status": "connected",
  "message": "string",
  "core_id": "main"
}

Errors: 401 Unauthorized, 403 Forbidden, 409 Conflict

bash

curl -X POST 'https://YOUR-PANEL/api/node' \
  -H 'Authorization: Bearer $TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{"add_as_new_host": true, "address": "192.168.1.1", "api_port": 62051, "name": "DE node", "port": 62050, "usage_coefficient": 1}'

GET `/api/node-install/{job_id}`

Install Status

Progress and log of a node installation started over SSH. Pass offset to get only the new log lines.

Sudo admin only

Parameters

Name	In	Type	Required	Description
`job_id`	path	`string`	yes
`offset`	query	`integer`	no

Response 200 Successful Response

Errors: 401 Unauthorized, 403 Forbidden

bash

curl -X GET 'https://YOUR-PANEL/api/node-install/<job_id>' \
  -H 'Authorization: Bearer $TOKEN'

GET `/api/node/settings`

Get Node Settings

Retrieve the current node settings, including TLS certificate.

Sudo admin only

Response 200 Successful Response · NodeSettings

Response fields

Field	Type	Description
`min_node_version`	`string`
`certificate`	`string`

json

{
  "min_node_version": "v0.2.0",
  "certificate": "string"
}

Errors: 401 Unauthorized, 403 Forbidden

bash

curl -X GET 'https://YOUR-PANEL/api/node/settings' \
  -H 'Authorization: Bearer $TOKEN'

GET `/api/node/{node_id}`

Get Node

Retrieve details of a specific node by its ID.

Sudo admin only

Parameters

Name	In	Type	Required	Description
`node_id`	path	`integer`	yes

Response 200 Successful Response · NodeResponse

Response fields

Field	Type	Description
`name`	`string`
`address`	`string`
`port`	`integer`
`api_port`	`integer`
`usage_coefficient`	`number`
`agent_enabled`	`boolean`
`ip_limit_enabled`	`boolean`
`id`	`integer`
`xray_version`	`string`
`status`	`connected` / `connecting` / `error` / `disabled`
`message`	`string`
`core_id`	`string`

json

{
  "name": "string",
  "address": "string",
  "port": 62050,
  "api_port": 62051,
  "usage_coefficient": 1.0,
  "agent_enabled": true,
  "ip_limit_enabled": true,
  "id": 0,
  "xray_version": "string",
  "status": "connected",
  "message": "string",
  "core_id": "main"
}

Errors: 401 Unauthorized, 403 Forbidden

bash

curl -X GET 'https://YOUR-PANEL/api/node/<node_id>' \
  -H 'Authorization: Bearer $TOKEN'

PUT `/api/node/{node_id}`

Modify Node

Update a node's details. Only accessible to sudo admins.

Sudo admin only

Parameters

Name	In	Type	Required	Description
`node_id`	path	`integer`	yes

Request body application/json · NodeModify

Field	Type	Required
`name`	`string`	no
`address`	`string`	no
`port`	`integer`	no
`api_port`	`integer`	no
`usage_coefficient`	`number`	no
`agent_enabled`	`boolean`	no
`ip_limit_enabled`	`boolean`	no
`status`	`NodeStatus`	no
`core_id`	`string`	no

json

{
  "address": "192.168.1.1",
  "api_port": 62051,
  "name": "DE node",
  "port": 62050,
  "status": "disabled",
  "usage_coefficient": 1.0
}

Response 200 Successful Response · NodeResponse

Response fields

Field	Type	Description
`name`	`string`
`address`	`string`
`port`	`integer`
`api_port`	`integer`
`usage_coefficient`	`number`
`agent_enabled`	`boolean`
`ip_limit_enabled`	`boolean`
`id`	`integer`
`xray_version`	`string`
`status`	`connected` / `connecting` / `error` / `disabled`
`message`	`string`
`core_id`	`string`

json

{
  "name": "string",
  "address": "string",
  "port": 62050,
  "api_port": 62051,
  "usage_coefficient": 1.0,
  "agent_enabled": true,
  "ip_limit_enabled": true,
  "id": 0,
  "xray_version": "string",
  "status": "connected",
  "message": "string",
  "core_id": "main"
}

Errors: 401 Unauthorized, 403 Forbidden

bash

curl -X PUT 'https://YOUR-PANEL/api/node/<node_id>' \
  -H 'Authorization: Bearer $TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{"address": "192.168.1.1", "api_port": 62051, "name": "DE node", "port": 62050, "status": "disabled", "usage_coefficient": 1.0}'

DELETE `/api/node/{node_id}`

Remove Node

Delete a node and remove it from xray in the background.

Sudo admin only

Parameters

Name	In	Type	Required	Description
`node_id`	path	`integer`	yes

Response 200 Successful Response

Errors: 401 Unauthorized, 403 Forbidden

bash

curl -X DELETE 'https://YOUR-PANEL/api/node/<node_id>' \
  -H 'Authorization: Bearer $TOKEN'

PUT `/api/node/{node_id}/extra`

Put Node Extra

Save the node's extra settings (SSH access, VPS details, flags). Secrets are stored encrypted and are never returned.

Sudo admin only

Parameters

Name	In	Type	Required	Description
`node_id`	path	`integer`	yes

Request body application/json · NodeExtraIn

Field	Type	Required	Description
`flag`	`string`	no
`transport`	`string`	no
`ssh`	`SSHIn`	no
`forget_ssh`	`boolean`	no	Default: `false`.

json

{
  "flag": "",
  "transport": "string",
  "ssh": {
    "host": "",
    "port": 22,
    "username": "root",
    "auth": "password",
    "password": "",
    "private_key": "",
    "passphrase": "",
    "key_id": ""
  },
  "forget_ssh": false
}

Response 200 Successful Response

Errors: 401 Unauthorized, 403 Forbidden

bash

curl -X PUT 'https://YOUR-PANEL/api/node/<node_id>/extra' \
  -H 'Authorization: Bearer $TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{"flag": "", "transport": "string", "ssh": {"host": "", "port": 22, "username": "root", "auth": "password", "password": "", "private_key": "", "passphrase": "", "key_id": ""}, "forget_ssh": false}'

POST `/api/node/{node_id}/install`

Install Node

install Marzban-node and/or the agent on the VPS over SSH (runs in the background)

Sudo admin only

Parameters

Name	In	Type	Required	Description
`node_id`	path	`integer`	yes

Request body application/json · InstallIn

Field	Type	Required	Description
`ssh`	`SSHIn`	no
`save`	`boolean`	no	Default: `false`.
`node`	`boolean`	no	Default: `true`.
`agent`	`boolean`	no	Default: `true`.

json

{
  "ssh": {
    "host": "",
    "port": 22,
    "username": "root",
    "auth": "password",
    "password": "",
    "private_key": "",
    "passphrase": "",
    "key_id": ""
  },
  "save": false,
  "node": true,
  "agent": true
}

Response 200 Successful Response

Errors: 401 Unauthorized, 403 Forbidden

bash

curl -X POST 'https://YOUR-PANEL/api/node/<node_id>/install' \
  -H 'Authorization: Bearer $TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{"ssh": {"host": "", "port": 22, "username": "root", "auth": "password", "password": "", "private_key": "", "passphrase": "", "key_id": ""}, "save": false, "node": true, "agent": true}'

POST `/api/node/{node_id}/install-xray`

Install Node Xray Version

Install a chosen Xray-core version on the node over SSH (the node downloads the XTLS release itself). The current binary is kept as xray.old and put back if the new one doesn't run, so a node is never left without a working core.

Sudo admin only

Parameters

Name	In	Type	Required	Description
`node_id`	path	`integer`	yes

Request body application/json · NodeXrayVersionIn

Field	Type	Required	Description
`version`	`string`	yes

json

{
  "version": "string"
}

Response 200 Successful Response

Errors: 401 Unauthorized, 403 Forbidden

bash

curl -X POST 'https://YOUR-PANEL/api/node/<node_id>/install-xray' \
  -H 'Authorization: Bearer $TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{"version": "string"}'

POST `/api/node/{node_id}/reconnect`

Reconnect Node

Connect again now: a hanging attempt is dropped, not waited for

Sudo admin only

Parameters

Name	In	Type	Required	Description
`node_id`	path	`integer`	yes

Response 200 Successful Response

Errors: 401 Unauthorized, 403 Forbidden

bash

curl -X POST 'https://YOUR-PANEL/api/node/<node_id>/reconnect' \
  -H 'Authorization: Bearer $TOKEN'

POST `/api/node/{node_id}/restart`

Restart Node Core

restart the node's Xray (connects first if it isn't connected)

Sudo admin only

Parameters

Name	In	Type	Required	Description
`node_id`	path	`integer`	yes

Response 200 Successful Response

Errors: 401 Unauthorized, 403 Forbidden

bash

curl -X POST 'https://YOUR-PANEL/api/node/<node_id>/restart' \
  -H 'Authorization: Bearer $TOKEN'

POST `/api/node/{node_id}/uninstall`

Uninstall Node

remove everything Alexen put on the node's server (containers, firewall rules, tunnels, files) over SSH; other panels on it stay untouched

Sudo admin only

Parameters

Name	In	Type	Required	Description
`node_id`	path	`integer`	yes

Response 200 Successful Response

Errors: 401 Unauthorized, 403 Forbidden

bash

curl -X POST 'https://YOUR-PANEL/api/node/<node_id>/uninstall' \
  -H 'Authorization: Bearer $TOKEN'

POST `/api/node/{node_id}/update-xray`

Update Node Xray

give the node the panel's Xray (same version) over SSH and restart it

Sudo admin only

Parameters

Name	In	Type	Required	Description
`node_id`	path	`integer`	yes

Response 200 Successful Response

Errors: 401 Unauthorized, 403 Forbidden

bash

curl -X POST 'https://YOUR-PANEL/api/node/<node_id>/update-xray' \
  -H 'Authorization: Bearer $TOKEN'

GET `/api/nodes`

Get Nodes

Retrieve a list of all nodes. Accessible only to sudo admins.

Sudo admin only

Response 200 Successful Response · NodeResponse[]

Response fields

Field	Type	Description
`name`	`string`
`address`	`string`
`port`	`integer`
`api_port`	`integer`
`usage_coefficient`	`number`
`agent_enabled`	`boolean`
`ip_limit_enabled`	`boolean`
`id`	`integer`
`xray_version`	`string`
`status`	`connected` / `connecting` / `error` / `disabled`
`message`	`string`
`core_id`	`string`

json

[
  {
    "name": "string",
    "address": "string",
    "port": 62050,
    "api_port": 62051,
    "usage_coefficient": 1.0,
    "agent_enabled": true,
    "ip_limit_enabled": true,
    "id": 0,
    "xray_version": "string",
    "status": "connected",
    "message": "string",
    "core_id": "main"
  }
]

Errors: 401 Unauthorized, 403 Forbidden

bash

curl -X GET 'https://YOUR-PANEL/api/nodes' \
  -H 'Authorization: Bearer $TOKEN'

GET `/api/nodes/extras`

Nodes Extras

Extra settings of all nodes (secrets are masked).

Sudo admin only

Response 200 Successful Response

Errors: 401 Unauthorized, 403 Forbidden

bash

curl -X GET 'https://YOUR-PANEL/api/nodes/extras' \
  -H 'Authorization: Bearer $TOKEN'

GET `/api/nodes/system`

Nodes System

CPU, memory, disk, uptime and network speed of the master and every node

Sudo admin only

Response 200 Successful Response

Errors: 401 Unauthorized, 403 Forbidden

bash

curl -X GET 'https://YOUR-PANEL/api/nodes/system' \
  -H 'Authorization: Bearer $TOKEN'

GET `/api/nodes/usage`

Get Usage

Retrieve usage statistics for nodes within a specified date range.

Sudo admin only

Parameters

Name	In	Type	Required	Description
`start`	query	`string`	no
`end`	query	`string`	no

Response 200 Successful Response · NodesUsageResponse

Response fields

Field	Type	Description
`usages`	`NodeUsageResponse[]`

json

{
  "usages": [
    {
      "node_id": 0,
      "node_name": "string",
      "uplink": 0,
      "downlink": 0
    }
  ]
}

Errors: 401 Unauthorized, 403 Forbidden

bash

curl -X GET 'https://YOUR-PANEL/api/nodes/usage' \
  -H 'Authorization: Bearer $TOKEN'

GET `/api/ssh-keys`

List Ssh Keys

saved SSH keys (names + public keys only; private keys are never returned)

Sudo admin only

Response 200 Successful Response

Errors: 401 Unauthorized, 403 Forbidden

bash

curl -X GET 'https://YOUR-PANEL/api/ssh-keys' \
  -H 'Authorization: Bearer $TOKEN'

POST `/api/ssh-keys`

Add Ssh Key

Save an SSH key in the key library (name, private key, optional passphrase). The private key is stored encrypted and never returned.

Sudo admin only

Request body application/json · SSHKeyIn

Field	Type	Required	Description
`name`	`string`	no
`private_key`	`string`	no
`passphrase`	`string`	no
`generate`	`boolean`	no	Default: `false`.

json

{
  "name": "",
  "private_key": "",
  "passphrase": "",
  "generate": false
}

Response 200 Successful Response

Errors: 401 Unauthorized, 403 Forbidden

bash

curl -X POST 'https://YOUR-PANEL/api/ssh-keys' \
  -H 'Authorization: Bearer $TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{"name": "", "private_key": "", "passphrase": "", "generate": false}'

DELETE `/api/ssh-keys/{key_id}`

Delete Ssh Key

Delete a saved SSH key.

Sudo admin only

Parameters

Name	In	Type	Required	Description
`key_id`	path	`string`	yes

Response 200 Successful Response

Errors: 401 Unauthorized, 403 Forbidden

bash

curl -X DELETE 'https://YOUR-PANEL/api/ssh-keys/<key_id>' \
  -H 'Authorization: Bearer $TOKEN'

Nodes ​

POST /api/node ​

GET /api/node-install/{job_id} ​

GET /api/node/settings ​

GET /api/node/{node_id} ​

PUT /api/node/{node_id} ​

DELETE /api/node/{node_id} ​

PUT /api/node/{node_id}/extra ​

POST /api/node/{node_id}/install ​

POST /api/node/{node_id}/install-xray ​

POST /api/node/{node_id}/reconnect ​

POST /api/node/{node_id}/restart ​

POST /api/node/{node_id}/uninstall ​

POST /api/node/{node_id}/update-xray ​

GET /api/nodes ​

GET /api/nodes/extras ​

GET /api/nodes/system ​

GET /api/nodes/usage ​

GET /api/ssh-keys ​

POST /api/ssh-keys ​

DELETE /api/ssh-keys/{key_id} ​

Nodes

POST `/api/node`

GET `/api/node-install/{job_id}`

GET `/api/node/settings`

GET `/api/node/{node_id}`

PUT `/api/node/{node_id}`

DELETE `/api/node/{node_id}`

PUT `/api/node/{node_id}/extra`

POST `/api/node/{node_id}/install`

POST `/api/node/{node_id}/install-xray`

POST `/api/node/{node_id}/reconnect`

POST `/api/node/{node_id}/restart`

POST `/api/node/{node_id}/uninstall`

POST `/api/node/{node_id}/update-xray`

GET `/api/nodes`

GET `/api/nodes/extras`

GET `/api/nodes/system`

GET `/api/nodes/usage`

GET `/api/ssh-keys`

POST `/api/ssh-keys`

DELETE `/api/ssh-keys/{key_id}`