Node Management APIs

List Nodes

GET /api/v2/nodes/

Returns a list of VPN servers associated with your organization.

Response Example:

{
  "success": true,
  "data": {
    "count": 2,
    "results": [
      {
        "id": 28,
        "country": "us",
        "country_display": "us",
        "name": "Basic-",
        "ip": "1.1.1.1",
        "host": "test.vpn.bingo",
        "port": 443,
        "instance_id": null,
        "instance_status": -1,
        "bandwidth": 0.0,
        "bandwidth_used_m": 0.0,
        "status": 9,
        "status_display": "Deployment Successful",
        "can_redeploy": true,
        "info": null,
        "expire_time": "2025-02-13 10:36:59",
        "status_update_time": "2025-02-13 10:27:00",
        "update_time": "2025-02-13 10:27:00",
        "create_time": "2025-02-13 10:27:00"
      }
    ]
  },
  "error": null
}

Get Node Details

GET /api/v2/nodes/{node_id}/

Retrieve detailed information about a specific node.

Response Example:

{
  "success": true,
  "data": {
    "id": 28,
    "country": "us",
    "country_display": "us",
    "name": "Basic-",
    "ip": "1.1.1.1",
    "host": "test.vpn.bingo",
    "port": 443,
    "instance_id": null,
    "instance_status": -1,
    "bandwidth": 0.0,
    "bandwidth_used_m": 0.0,
    "status": 9,
    "status_display": "Deployment Successful",
    "can_redeploy": true,
    "info": null,
    "expire_time": "2025-02-13 10:36:59",
    "status_update_time": "2025-02-13 10:27:00",
    "update_time": "2025-02-13 10:27:00",
    "create_time": "2025-02-13 10:27:00"
  },
  "error": null
}

Update Node

PATCH /api/v2/nodes/{node_id}/

Update specific fields of a node.

Request Body:

{
  "name": "New Name"
}

Response Example:

{
  "success": true,
  "data": {
    "id": 28,
    "country": "us",
    "country_display": "us",
    "name": "New Name",
    "ip": "1.1.1.1",
    "host": "test.vpn.bingo",
    "port": 443,
    "instance_id": null,
    "instance_status": -1,
    "bandwidth": 0.0,
    "bandwidth_used_m": 0.0,
    "status": 9,
    "status_display": "Deployment Successful",
    "can_redeploy": true,
    "info": null,
    "expire_time": "2025-02-13 10:36:59",
    "status_update_time": "2025-02-13 10:27:00",
    "update_time": "2025-02-13 10:27:00",
    "create_time": "2025-02-13 10:27:00"
  },
  "error": null
}

Redeploy Node

POST /api/v2/nodes/{node_id}/redeploy/

Redeploy a node by creating a new node instance and setting the original node to "Pending Release" status.

Request Body:

{
  "force": false,
  "country_code": "JP"
}

Parameter	Type	Required	Description
force	boolean	No	Whether to force redeployment even if the node status is not suitable for deployment or has reached its maximum redeploy count. Default: false
country_code	string	No	Specify the country code for the new node (e.g., "US", "JP", "DE"). If not provided, the country of the original node will be used.

Response Example:

{
  "original_node": {
    "id": 28,
    "status": 20,
    "status_display": "Pending Release"
  },
  "new_node": {
    "id": 29,
    "country": "JP",
    "country_display": "jp",
    "status": -10,
    "status_display": "Preparing"
  }
}

Error Responses:

1. Node does not exist:

{
  "detail": "Can not find the server"
}

2. Node has reached maximum redeploy count:

{
  "detail": "Server cann't redeploy now (max redeploy count reached)"
}

3. Node status does not allow redeployment:

{
  "detail": "Server cann't redeploy on this status(18)"
}

4. Invalid country code:

{
  "country_code": ["Invalid country code: XX. Valid country codes include: US, JP, DE, GB, FR, ..."]
}

Notes:

1. By default, only nodes with the following statuses can be redeployed:

   • Deployment Successful (9)
   • Awaiting Heartbeat (10)
   • Heartbeat Abnormal (18)
   • Ready (19)

2. The redeployment process creates a new node with the same configuration (except IP and port) and sets the original node to "Pending Release" status.

3. The new node will have redeploy_max_count set to 0, meaning it cannot be redeployed again without using the force parameter.

4. The can_redeploy field indicates whether the node can be redeployed. A value of true means the node can be redeployed, false means it cannot.

Node Fields:

Field	Type	Description
id	integer	Unique identifier for the node
name	string	Name of the node
organization	object	Organization that owns the node
country	string	Country code where the node is located
country_display	string	Display name of the country
ip	string	IP address of the node
host	string	Hostname of the node
port	integer	Port number for the node
instance_id	string	Cloud provider instance ID
instance_status	integer	Status code of the instance
instance_status_display	string	Human-readable instance status
bandwidth	float	Allocated bandwidth in Mbps
bandwidth_used_m	float	Used bandwidth in Mbps
status	integer	Status code of the node
status_display	string	Human-readable node status
can_redeploy	boolean	Whether the node can be redeployed (true if redeploy_max_count > 0 and bandwidth_used_m < 1)
server	object	Server information
info	string	Additional information about the node
expire_time	string	Expiration time of the node
status_update_time	string	Last time the status was updated