API.md

Important

⚠ This is a public archive and the active project has been renamed to NetAlertX and moved: jokob.sk/NetAlertX

• To differentiate from the upstream stale project
• To differentiate from other active forks
• To indicate this is not a Raspberry Pi-specific tool anymore

API endpoints

PiAlert comes with a simple API. These API endpoints are static files, that are periodically updated based on your settings.

When are the endpoints updated

The endpoints are updated when objects in the API endpoints are changed.

Location of the endpoints

In the container, these files are located under the /home/pi/pialert/front/api/ folder and thus on the <pialert_url>/api/<File name> url.

Available endpoints

You can access the following files:

File name	Description
notification_text.txt	The plain text version of the last notification.
notification_text.html	The full HTML of the last email notification.
notification_json_final.json	The json version of the last notification (e.g. used for webhooks - sample JSON).
table_devices.json	The current (at the time of the last update as mentioned above on this page) state of all of the available Devices detected by the app.
table_pholus_scan.json	The latest state of the pholus (A multicast DNS and DNS Service Discovery Security Assessment Tool) scan results.
table_plugins_events.json	The list of the unprocessed (pending) notification events (plugins_events DB table).
table_plugins_history.json	The list of notification events history.
table_plugins_objects.json	The content of the plugins_objects table. Find more info on the Plugin system here
language_strings.json	The content of the language_strings table, which in turn is loaded from the plugins config.json definitions.
table_custom_endpoint.json	A custom endpoint generated by the SQL query specified by the API_CUSTOM_SQL setting.
table_settings.json	The content of the settings table.
app_state.json	Contains the current application state.

Current/latest state of the aforementioned files depends on your settings.

JSON Data format

The endpoints starting with the table_ prefix contain most, if not all, data contained in the corresponding database table. The common format for those is:

{
  "data": [
        {
          "db_column_name": "data",
          "db_column_name2": "data2"      
        }, 
        {
          "db_column_name": "data3",
          "db_column_name2": "data4" 
        }
    ]
}

Example JSON of the table_devices.json endpoint with two Devices (database rows):

{
  "data": [
        {
          "dev_MAC": "Internet",
          "dev_Name": "Net - Huawei",
          "dev_DeviceType": "Router",
          "dev_Vendor": null,
          "dev_Group": "Always on",
          "dev_FirstConnection": "2021-01-01 00:00:00",
          "dev_LastConnection": "2021-01-28 22:22:11",
          "dev_LastIP": "192.168.1.24",
          "dev_StaticIP": 0,
          "dev_PresentLastScan": 1,
          "dev_LastNotification": "2023-01-28 22:22:28.998715",
          "dev_NewDevice": 0,
          "dev_Network_Node_MAC_ADDR": "",
          "dev_Network_Node_port": "",
          "dev_Icon": "globe"
        }, 
        {
          "dev_MAC": "a4:8f:ff:aa:ba:1f",
          "dev_Name": "Net - USG",
          "dev_DeviceType": "Firewall",
          "dev_Vendor": "Ubiquiti Inc",
          "dev_Group": "",
          "dev_FirstConnection": "2021-02-12 22:05:00",
          "dev_LastConnection": "2021-07-17 15:40:00",
          "dev_LastIP": "192.168.1.1",
          "dev_StaticIP": 1,
          "dev_PresentLastScan": 1,
          "dev_LastNotification": "2021-07-17 15:40:10.667717",
          "dev_NewDevice": 0,
          "dev_Network_Node_MAC_ADDR": "Internet",
          "dev_Network_Node_port": 1,
          "dev_Icon": "shield-halved"
      }
    ]
}