INTRODUCTION

FEATURES

TUTORIALS

ADVANCED

API

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
• Device Info
• Tunnels
• Terminal
• Process List
• Screenshot

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:

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:

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:

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:

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
    },
    ...
  ]
}

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.