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