Skip to content

Node Management APIs

List Nodes

http
GET /api/v2/nodes/

Returns a list of VPN servers associated with your organization.

Response Example:

json
{
  "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

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

Retrieve detailed information about a specific node.

Response Example:

json
{
  "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

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

Update specific fields of a node.

Request Body:

json
{
  "name": "New Name"
}

Response Example:

json
{
  "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

http
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:

json
{
  "force": false,
  "country_code": "JP"
}
ParameterTypeRequiredDescription
forcebooleanNoWhether to force redeployment even if the node status is not suitable for deployment or has reached its maximum redeploy count. Default: false
country_codestringNoSpecify 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:

json
{
  "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:
json
{
  "detail": "Can not find the server"
}
  1. Node has reached maximum redeploy count:
json
{
  "detail": "Server cann't redeploy now (max redeploy count reached)"
}
  1. Node status does not allow redeployment:
json
{
  "detail": "Server cann't redeploy on this status(18)"
}
  1. Invalid country code:
json
{
  "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:

FieldTypeDescription
idintegerUnique identifier for the node
namestringName of the node
organizationobjectOrganization that owns the node
countrystringCountry code where the node is located
country_displaystringDisplay name of the country
ipstringIP address of the node
hoststringHostname of the node
portintegerPort number for the node
instance_idstringCloud provider instance ID
instance_statusintegerStatus code of the instance
instance_status_displaystringHuman-readable instance status
bandwidthfloatAllocated bandwidth in Mbps
bandwidth_used_mfloatUsed bandwidth in Mbps
statusintegerStatus code of the node
status_displaystringHuman-readable node status
can_redeploybooleanWhether the node can be redeployed (true if redeploy_max_count > 0 and bandwidth_used_m < 1)
serverobjectServer information
infostringAdditional information about the node
expire_timestringExpiration time of the node
status_update_timestringLast time the status was updated