flvx/skills/flvx-api/references/nodes.md

Node Management API

All node endpoints require admin privileges (role_id: 0).

POST /api/v1/node/list

List all nodes with status information.

Request:

{
  "page": 1,
  "pageSize": 20,
  "keyword": ""
}

Response:

{
  "code": 0,
  "data": {
    "list": [
      {
        "id": 1,
        "name": "HK-Node-1",
        "secret": "abc123...",
        "server_ip": "1.2.3.4",
        "server_ip_v4": "1.2.3.4",
        "server_ip_v6": "2001:db8::1",
        "port": "1000-65535",
        "interface_name": "eth0",
        "http": 1,
        "tls": 1,
        "socks": 1,
        "tcp_listen_addr": "[::]",
        "udp_listen_addr": "[::]",
        "status": 1,
        "is_remote": 0,
        "version": "2.1.5",
        "created_at": 1706659200000,
        "updated_at": 1706659200000
      }
    ],
    "total": 1
  }
}

Status Values:

• 0 = Offline
• 1 = Online

is_remote Values:

• 0 = Local node (managed by this panel)
• 1 = Remote node (federation from another panel)

POST /api/v1/node/create

Create a new node.

Request:

{
  "name": "US-Node-1",
  "serverIp": "5.6.7.8",
  "serverIpV4": "5.6.7.8",
  "serverIpV6": "2001:db8::2",
  "port": "1000-65535",
  "interfaceName": "eth0",
  "http": 1,
  "tls": 1,
  "socks": 1,
  "tcpListenAddr": "[::]",
  "udpListenAddr": "[::]",
  "isRemote": 0,
  "remoteUrl": "",
  "remoteToken": ""
}

Fields:

Field	Type	Required	Description
name	string	Yes	Node name
serverIp	string	Yes	Primary server IP (display)
serverIpV4	string	No	IPv4 address
serverIpV6	string	No	IPv6 address
port	string	No	Allowed port range (default: "1000-65535")
interfaceName	string	No	Network interface for traffic
http	number	No	Enable HTTP protocol (1/0)
tls	number	No	Enable TLS protocol (1/0)
socks	number	No	Enable SOCKS protocol (1/0)
tcpListenAddr	string	No	TCP listen address (default: "[::]")
udpListenAddr	string	No	UDP listen address (default: "[::]")
isRemote	number	No	Federation node (1/0)
remoteUrl	string	If isRemote=1	Remote panel URL
remoteToken	string	If isRemote=1	Federation token

Response:

{"code": 0, "msg": "success", "data": {"id": 2, "secret": "xyz789..."}}

POST /api/v1/node/install

Generate installation command for a node.

Request:

{"id": 2}

Response:

{
  "code": 0,
  "data": {
    "command": "curl -fsSL https://panel.example.com/install.sh | bash -s -- --secret xyz789... --server https://panel.example.com"
  }
}

POST /api/v1/node/update

Update node configuration.

Request: Same fields as create, with id field required.

{
  "id": 2,
  "name": "US-Node-1-Updated",
  "serverIp": "5.6.7.8",
  "http": 1,
  "tls": 1,
  "socks": 0
}

POST /api/v1/node/delete

Delete a node.

Request:

{"id": 2}

POST /api/v1/node/batch-delete

Delete multiple nodes.

Request:

{"ids": [2, 3, 4]}

POST /api/v1/node/check-status

Refresh and check status of all nodes.

Request: {}

Response:

{
  "code": 0,
  "data": {
    "updated": 5,
    "online": 4,
    "offline": 1
  }
}

POST /api/v1/node/update-order

Reorder nodes (for display purposes).

Request:

{
  "orders": [
    {"id": 1, "order": 0},
    {"id": 2, "order": 1}
  ]
}

POST /api/v1/node/releases

List available FLVX agent releases.

Request: {}

Response:

{
  "code": 0,
  "data": [
    {"version": "2.1.5", "published_at": 1706659200000},
    {"version": "2.1.4", "published_at": 1706572800000}
  ]
}

POST /api/v1/node/upgrade

Upgrade a single node agent.

Request:

{
  "id": 2,
  "version": "2.1.5"
}

POST /api/v1/node/batch-upgrade

Upgrade multiple node agents.

Request:

{
  "ids": [1, 2, 3],
  "version": "2.1.5"
}

POST /api/v1/node/rollback

Rollback node agent to previous version.

Request:

{"id": 2}

Example: Full Node Setup Workflow

# 1. Create node
RESPONSE=$(curl -s -X POST "${FLVX_BASE_URL}/api/v1/node/create" \
  -H "Authorization: ${TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{"name":"SG-Node-1","serverIp":"203.0.113.10"}')

NODE_ID=$(echo "$RESPONSE" | jq -r '.data.id')

# 2. Get install command
curl -s -X POST "${FLVX_BASE_URL}/api/v1/node/install" \
  -H "Authorization: ${TOKEN}" \
  -H "Content-Type: application/json" \
  -d "{\"id\":${NODE_ID}}"

# 3. Run install command on target server (manual step)

# 4. Verify node is online
curl -s -X POST "${FLVX_BASE_URL}/api/v1/node/list" \
  -H "Authorization: ${TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{}' | jq ".data.list[] | select(.id == $NODE_ID) | {name, status}"