PiTunnel

API Endpoints

PiTunnel APIs are accessed as RESTful endpoints. The following examples use cURL, but can be easily converted to Python, PHP or any other programming language.

The following endpoints are suported:


Devices

Gets a list of all registered devices, as well as their online/offline status.

curl https://api.pitunnel.com/devices \
-u <api_key>:
# The colon stops curl from asking for a password.

Example Response:

{"devices":
  [
    {"id": "5eea15ac2e2d34acd56ee736484be8f4b77c7e",
     "hostname": "ubuntu",
     "serial": "DBAC82CE",
     "display_name": "TestPi",
     "os": "Linux",
     "os_version": "Ubuntu 18.04 bionic",
     "hardware": "Pi3 Model B",
     "online": true
    },
    {"id": "4eed04a3262678de6cea038e1d617004ff73381",
     "hostname": "raspberrypi",
     "serial": "10000000389253E6",
     "display_name": "TestPi2",
     "os": "Linux",
     "os_version": "debian 11.2",
     "hardware": "Pi4 Model B",
     "online": true
    }
  ]
}

Response Parameters:
NameTypeDescription
devicesListList of registered devices.
idStringUnique identifier for the device.
hostnameStringHostname of the device.
serialStringSerial number of the device.
osStringOperating System, usually "Linux".
os_versionStringOperating System version, e.g. "Debian 9.4", "Ubuntu 18.04 bionic"
hardwareStringThe type of device, decoded from the device's revision number.
onlineBooleanTrue if the device is currently online, otherwise False.

Device Info

Connects to an online device and returns information about it. Does not work for offline devices.

curl https://api.pitunnel.com/device_info \
-u <api_key>: \
-d device_id=<device_id>
# The colon stops curl from asking for a password.
# <device_id> comes from a previous /devices call

Example Response:

{"device_info": 
  {"disk_usage": [15570452480, 9602961408, 5270650880, 64.6],
   "cpu_usage": 9.7,
   "mem_used_percent": 32.1,
   "mem_total": 972361728,
   "mem_available": 660647936,
   "cpu_temp": 54.768,
   "gpu_temp": 55.3,
   "mac_address": "B827EB2A7FC1",
   "hostname": "raspberry"
  }
}

Response Parameters:
NameTypeDescription
disk_usageListA 4 element list, 3 Integers and a Float: Total Bytes, Used Bytes, Available Bytes, Percentage Free.
cpu_usageFloatPercentage CPU usage.
mem_used_percentFloatMemory usage as a percentage of total memory.
mem_totalIntegerTotal memory in bytes.
mem_availableIntegerAvailable memory in bytes.
cpu_tempFloatCPU Temperature in Celcius.
gpu_tempFloatGPU Temperature in Celcius (not available for all devices).
mac_addressStringMAC address of the primary network interface.
hostnameStringHostname of the device, e.g. "raspberry"

Tunnels

Gets a list of active tunnels for a device.

curl https://api.pitunnel.com/tunnels \
-u <api_key>: \
-d device_id=<device_id>
# The colon stops curl from asking for a password.
# <device_id> comes from a previous /devices call

Example Response:

{"tunnels": 
  [
    {"destination": "192.168.1.50:8000",
     "available_at": "pitunnel.com:10507"
     "name": ""
    },
    {"destination": "192.168.1.51:8000",
     "available_at": "pitunnel.com:10508",
     "name": ""
    }
  ]
}

Response Parameters:
NameTypeDescription
tunnelsListList of current active tunnels for the device.
destinationStringDestination IP/Hostname & Port of the tunnel on the device.
available_atStringPublic address on PiTunnel.com. Either a hostname & IP, or HTTPS subdomain.
nameStringName of the tunnel, if it has been given a name.

Terminal

Gets the URL of the remote terminal web interface for a device, if the device is currently online.

curl https://api.pitunnel.com/terminal \
-u <api_key>: \
-d device_id=<device_id>
# The colon stops curl from asking for a password.
# <device_id> comes from a previous /devices call

Example Response:

{"terminal_url": "https://terminal.pitunnel.com/KP4a5fdPisrceLPh2E"}

Response Parameters:
NameTypeDescription
terminal_urlListURL to the remote terminal web interface for this device.

Process List

Connects to an online device and gets a list of currently running processes, as well as memory and cpu usage for each. Similar to the top command on Linux.

curl https://api.pitunnel.com/process_list \
-u <api_key>: \
-d device_id=<device_id>
# The colon stops curl from asking for a password.
# <device_id> comes from a previous /devices call

Example Response:
{"process_list":
  [
    {"memory_percent": 2.552307776556175,
     "pid": 867,
     "name": "lxpanel",
     "cpu_percent": 0.2
    },
    {"memory_percent": 1.1470430888863614,
     "pid": 121,
     "name": "systemd-journald",
     "cpu_percent": 0.1
    },
    ...
  ]
}

Response Parameters:
NameTypeDescription
process_listListList of processes for this device. Excludes processes in the PiTunnel service process tree.
memory_percentFloatThe percentage of total memory being used by this process.
pidIntegerProcess ID.
nameStringProcess name.
cpu_percentFloatThe percentage of CPU being used by this process.

Screenshot

Connects to an online device and gets a screenshot. Some devices & os versions may not allow a screenshot to be taken if no monitor is connected.

curl https://api.pitunnel.com/screenshot \
-u <api_key>: \
-d device_id=<device_id> \
> ~/Desktop/out.png
# The colon stops curl from asking for a password.
# <device_id> comes from a previous /devices call
# The output is being piped to a file, but might
# not always be a png. Look at the content type of the
# response.

Response

The response will be an image file of either PNG or JPEG format depending on the kind of user session being captured. Use the "Content-Type" header within the HTTP response to get the image type.