Skip to content

API endpoints

NetAlertX comes with a couple of API endpoints. All requests need to be authorized (executed in a logged in browser session) or you have to pass the value of the API_TOKEN settings as authorization bearer, for example:

curl 'http://host:GRAPHQL_PORT/graphql' \
  -X POST \
  -H 'Authorization: Bearer API_TOKEN' \
  -H 'Content-Type: application/json' \
  --data '{
    "query": "query GetDevices($options: PageQueryOptionsInput) { devices(options: $options) { devices { rowid devMac devName devOwner devType devVendor devLastConnection devStatus } count } }",
    "variables": {
      "options": {
        "page": 1,
        "limit": 10,
        "sort": [{ "field": "devName", "order": "asc" }],
        "search": "",
        "status": "connected"
      }
    }
  }'

API Endpoint: GraphQL

  • Endpoint URL: php/server/query_graphql.php
  • Host: same as front end (web ui)
  • Port: 20212 or as defined by the GRAPHQL_PORT setting

Example Query to Fetch Devices

First, let's define the GraphQL query to fetch devices with pagination and sorting options.

query GetDevices($options: PageQueryOptionsInput) {
  devices(options: $options) {
    devices {
      rowid
      devMac
      devName
      devOwner
      devType
      devVendor
      devLastConnection
      devStatus
    }
    count
  }
}

See also: Debugging GraphQL issues

curl Command

You can use the following curl command to execute the query. 

curl 'http://host:GRAPHQL_PORT/graphql'   -X POST   -H 'Authorization: Bearer API_TOKEN'  -H 'Content-Type: application/json'   --data '{
    "query": "query GetDevices($options: PageQueryOptionsInput) { devices(options: $options) { devices { rowid devMac devName devOwner devType devVendor devLastConnection devStatus } count } }",
    "variables": {
      "options": {
        "page": 1,
        "limit": 10,
        "sort": [{ "field": "devName", "order": "asc" }],
        "search": "",
        "status": "connected"
      }
    }
  }'

Explanation:

  1. GraphQL Query:
  2. The query parameter contains the GraphQL query as a string.

  3. The variables parameter contains the input variables for the query.

  4. Query Variables:

  5. page: Specifies the page number of results to fetch.
  6. limit: Specifies the number of results per page.
  7. sort: Specifies the sorting options, with field being the field to sort by and order being the sort order (asc for ascending or desc for descending).
  8. search: A search term to filter the devices.

  9. status: The status filter to apply (valid values are my_devices (determined by the UI_MY_DEVICES setting), connected, favorites, new, down, archived, offline).

  10. curl Command:

  11. The -X POST option specifies that we are making a POST request.
  12. The -H "Content-Type: application/json" option sets the content type of the request to JSON.
  13. The -d option provides the request payload, which includes the GraphQL query and variables.

Sample Response

The response will be in JSON format, similar to the following:

{
  "data": {
    "devices": {
      "devices": [
        {
          "rowid": 1,
          "devMac": "00:11:22:33:44:55",
          "devName": "Device 1",
          "devOwner": "Owner 1",
          "devType": "Type 1",
          "devVendor": "Vendor 1",
          "devLastConnection": "2025-01-01T00:00:00Z",
          "devStatus": "connected"
        },
        {
          "rowid": 2,
          "devMac": "66:77:88:99:AA:BB",
          "devName": "Device 2",
          "devOwner": "Owner 2",
          "devType": "Type 2",
          "devVendor": "Vendor 2",
          "devLastConnection": "2025-01-02T00:00:00Z",
          "devStatus": "connected"
        }
      ],
      "count": 2
    }
  }
}

API Endpoint: JSON files

This API endpoint retrieves static files, that are periodically updated.

  • Endpoint URL: php/server/query_json.php?file=<file name>
  • Host: same as front end (web ui)
  • Port: 20211 or as defined by the $PORT docker environment variable (same as the port for the web ui)

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 /app/api/ folder. You can access them via the /php/server/query_json.php?file=user_notifications.json endpoint.

Available endpoints

You can access the following files:

File name Description
notification_json_final.json The json version of the last notification (e.g. used for webhooks - sample JSON).
table_devices.json All of the available Devices detected by the app.
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.

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": [
        {
          "devMac": "Internet",
          "devName": "Net - Huawei",
          "devType": "Router",
          "devVendor": null,
          "devGroup": "Always on",
          "devFirstConnection": "2021-01-01 00:00:00",
          "devLastConnection": "2021-01-28 22:22:11",
          "devLastIP": "192.168.1.24",
          "devStaticIP": 0,
          "devPresentLastScan": 1,
          "devLastNotification": "2023-01-28 22:22:28.998715",
          "devIsNew": 0,
          "devParentMAC": "",
          "devParentPort": "",
          "devIcon": "globe"
        }, 
        {
          "devMac": "a4:8f:ff:aa:ba:1f",
          "devName": "Net - USG",
          "devType": "Firewall",
          "devVendor": "Ubiquiti Inc",
          "devGroup": "",
          "devFirstConnection": "2021-02-12 22:05:00",
          "devLastConnection": "2021-07-17 15:40:00",
          "devLastIP": "192.168.1.1",
          "devStaticIP": 1,
          "devPresentLastScan": 1,
          "devLastNotification": "2021-07-17 15:40:10.667717",
          "devIsNew": 0,
          "devParentMAC": "Internet",
          "devParentPort": 1,
          "devIcon": "shield-halved"
      }
    ]
}

API Endpoint: Prometheus Exporter

  • Endpoint URL: /metrics
  • Host: (where NetAlertX exporter is running)
  • Port: as configured in the GRAPHQL_PORT setting (20212 by default)

Example Output of the /metrics Endpoint

Below is a representative snippet of the metrics you may find when querying the /metrics endpoint for netalertx. It includes both aggregate counters and device_status labels per device.

netalertx_connected_devices 31
netalertx_offline_devices 54
netalertx_down_devices 0
netalertx_new_devices 0
netalertx_archived_devices 31
netalertx_favorite_devices 2
netalertx_my_devices 54

netalertx_device_status{device="Net - Huawei", mac="Internet", ip="1111.111.111.111", vendor="None", first_connection="2021-01-01 00:00:00", last_connection="2025-08-04 17:57:00", dev_type="Router", device_status="Online"} 1
netalertx_device_status{device="Net - USG", mac="74:ac:74:ac:74:ac", ip="192.168.1.1", vendor="Ubiquiti Networks Inc.", first_connection="2022-02-12 22:05:00", last_connection="2025-06-07 08:16:49", dev_type="Firewall", device_status="Archived"} 1
netalertx_device_status{device="Raspberry Pi 4 LAN", mac="74:ac:74:ac:74:74", ip="192.168.1.9", vendor="Raspberry Pi Trading Ltd", first_connection="2022-02-12 22:05:00", last_connection="2025-08-04 17:57:00", dev_type="Singleboard Computer (SBC)", device_status="Online"} 1
...

Metrics Explanation

1. Aggregate Device Counts

Metric names prefixed with netalertx_ provide aggregated counts by device status:

  • netalertx_connected_devices: number of devices currently connected
  • netalertx_offline_devices: devices currently offline
  • netalertx_down_devices: down/unreachable devices
  • netalertx_new_devices: devices recently detected
  • netalertx_archived_devices: archived devices
  • netalertx_favorite_devices: user-marked favorite devices
  • netalertx_my_devices: devices associated with the current user context

These numeric values give a high-level overview of device distribution.

2. Per‑Device Status with Labels

Each individual device is represented by a netalertx_device_status metric, with descriptive labels:

  • device: friendly name of the device
  • mac: MAC address (or placeholder)
  • ip: last recorded IP address
  • vendor: manufacturer or "None" if unknown
  • first_connection: timestamp when the device was first observed
  • last_connection: most recent contact timestamp
  • dev_type: device category or type
  • device_status: current status (Online / Offline / Archived / Down / ...)

The metric value is always 1 (indicating presence or active state) and the combination of labels identifies the device.

How to Query with curl

To fetch the metrics from the NetAlertX exporter:

curl 'http://<server_ip>:<GRAPHQL_PORT>/metrics' \
  -H 'Authorization: Bearer <API_TOKEN>' \
  -H 'Accept: text/plain'

Replace:

  • <server_ip>: IP or hostname of the NetAlertX server
  • <GRAPHQL_PORT>: port specified in your GRAPHQL_PORT setting (default: 20212)
  • <API_TOKEN> your Bearer token from the API_TOKEN setting

Summary

  • Endpoint: /metrics provides both summary counters and per-device status entries.
  • Aggregate metrics help monitor overall device states.
  • Detailed metrics expose each device’s metadata via labels.
  • Use case: feed into Prometheus for scraping, monitoring, alerting, or charting dashboard views.

Prometheus Scraping Configuration

scrape_configs:
  - job_name: 'netalertx'
    metrics_path: /metrics
    scheme: http
    scrape_interval: 60s
    static_configs:
      - targets: ['<server_ip>:<GRAPHQL_PORT>']
    authorization:
      type: Bearer
      credentials: <API_TOKEN>

Grafana template

Grafana template sample: Download json

API Endpoint: /log files

This API endpoint retrieves files from the /app/log folder.

  • Endpoint URL: php/server/query_logs.php?file=<file name>
  • Host: same as front end (web ui)
  • Port: 20211 or as defined by the $PORT docker environment variable (same as the port for the web ui)
File Description
IP_changes.log Logs of IP address changes
app.log Main application log
app.php_errors.log PHP error log
app_front.log Frontend application log
app_nmap.log Logs of Nmap scan results
db_is_locked.log Logs when the database is locked
execution_queue.log Logs of execution queue activities
plugins/ Directory for temporary plugin-related files (not accessible)
report_output.html HTML report output
report_output.json JSON format report output
report_output.txt Text format report output
stderr.log Logs of standard error output
stdout.log Logs of standard output

API Endpoint: /config files

To retrieve files from the /app/config folder.

  • Endpoint URL: php/server/query_config.php?file=<file name>
  • Host: same as front end (web ui)
  • Port: 20211 or as defined by the $PORT docker environment variable (same as the port for the web ui)
File Description
devices.csv Devices csv file
app.conf Application config file