NetAlertX

https://docs.netalertx.com
Admin
NetAlertX is an open-source, continuous network monitoring and asset discovery tool that tracks...
Tokens:133,882
Snippets:1,747
Trust Score:7
Update:2 months ago
Show doc for...
Tokens:
Raw
### Complete Data Examples

Source: https://docs.netalertx.com/PLUGINS_DEV_DATA_CONTRACT

Valid examples showing both the 9-column base format and the 13-column format with all helpers.

```text
device|null|2023-01-02 15:56:30|status|null|null|null|null|null|h1|h2|h3|h4
```

```text
device|null|2023-01-02 15:56:30|status|null|null|null|null|null
```

--------------------------------

### Volume Path Configuration Example

Source: https://docs.netalertx.com/SYNOLOGY_GUIDE

Example of how to map the local Synology volume path to the container data directory.

```yaml
volumes:
      - /volume1/app_storage/netalertx:/data
```

--------------------------------

### List Sessions via cURL

Source: https://docs.netalertx.com/API_SESSIONS

Example request to list sessions using the GET method.

```bash
curl -X GET "http://<server_ip>:<GRAPHQL_PORT>/sessions/list?mac=AA:BB:CC:DD:EE:FF&start_date=2025-08-01&end_date=2025-08-21" \
  -H "Authorization: Bearer <API_TOKEN>" \
  -H "Accept: application/json"
```

--------------------------------

### Install NetAlertX on Ubuntu 24

Source: https://docs.netalertx.com/HW_INSTALL

Downloads and executes the Ubuntu 24 installation script using curl or wget.

```bash
curl -o install.sh https://raw.githubusercontent.com/jokob-sk/NetAlertX/main/install/ubuntu24/install.sh && sudo chmod +x install.sh && sudo ./install.sh
```

```bash
wget https://raw.githubusercontent.com/jokob-sk/NetAlertX/main/install/ubuntu24/install.sh -O install.sh && sudo chmod +x install.sh && sudo ./install.sh
```

--------------------------------

### Install NetAlertX on Debian 12

Source: https://docs.netalertx.com/HW_INSTALL

Downloads and executes the Debian 12 installation script using curl or wget.

```bash
curl -o install.debian12.sh https://raw.githubusercontent.com/jokob-sk/NetAlertX/main/install/debian12/install.debian12.sh && sudo chmod +x install.debian12.sh && sudo ./install.debian12.sh
```

```bash
wget https://raw.githubusercontent.com/jokob-sk/NetAlertX/main/install/debian12/install.debian12.sh -O install.debian12.sh && sudo chmod +x install.debian12.sh && sudo ./install.debian12.sh
```

--------------------------------

### Retrieve Device Details Response

Source: https://docs.netalertx.com/API_DEVICE

Example JSON response structure for a successful GET request to /device/<mac>.

```json
{
  "devMac": "AA:BB:CC:DD:EE:FF",
  "devName": "Net - Huawei",
  "devOwner": "Admin",
  "devType": "Router",
  "devVendor": "Huawei",
  "devStatus": "On-line",
  "devSessions": 12,
  "devEvents": 5,
  "devDownAlerts": 1,
  "devPresenceHours": 32,
  "devChildrenDynamic": [...],
  "devChildrenNicsDynamic": [...],
  ...
}
```

--------------------------------

### Device Sessions via cURL

Source: https://docs.netalertx.com/API_SESSIONS

Example request to retrieve sessions for a specific device using the GET method.

```bash
curl -X GET "http://<server_ip>:<GRAPHQL_PORT>/sessions/AA:BB:CC:DD:EE:FF?period=7%20days" \
  -H "Authorization: Bearer <API_TOKEN>" \
  -H "Accept: application/json"
```

--------------------------------

### Installing Test Dependencies

Source: https://docs.netalertx.com/API_TESTS?q=

Install the pytest framework within the container environment.

```bash
pip install pytest
```

--------------------------------

### Valid Data Examples

Source: https://docs.netalertx.com/PLUGINS_DEV_DATA_CONTRACT

Examples of correctly formatted 9-column and 13-column data payloads.

```text
https://example.com|null|2023-01-02 15:56:30|200|null|null|null|null|null
printer-hp-1|192.168.1.50|2023-01-02 15:56:30|online|50%|null|null|Last seen in office|aa:11:22:33:44:55
gateway.local|null|2023-01-02 15:56:30|active|v2.1.5|null|null|Firmware version|null
```

```text
service-api|192.168.1.100:8080|2023-01-02 15:56:30|200|45ms|true|null|Responding normally|aa:bb:cc:dd:ee:ff|extra1|extra2|extra3|extra4
host-web-1|10.0.0.20|2023-01-02 15:56:30|active|256GB|online|ok|Production server|null|cpu:80|mem:92|disk:45|alerts:0
```

--------------------------------

### GET /settings/<key>

Source: https://docs.netalertx.com/API_SETTINGS

Retrieve the value of a specific setting by its key.

```APIDOC
## GET /settings/<key>

### Description
Retrieve the value of a specific setting such as API_TOKEN or TIMEZONE.

### Method
GET

### Endpoint
/settings/<key>

### Parameters
#### Path Parameters
- **key** (string) - Required - The setting key to retrieve.

### Request Example
curl 'http://<server_ip>:<GRAPHQL_PORT>/settings/API_TOKEN' \
  -H 'Authorization: Bearer <API_TOKEN>' \
  -H 'Accept: application/json'

### Response
#### Success Response (200)
- **success** (boolean) - Indicates if the request was successful.
- **value** (string|null) - The value of the requested setting.

#### Response Example
{
  "success": true,
  "value": "my-secret-token"
}
```

--------------------------------

### Create database and configuration directories

Source: https://docs.netalertx.com/DEV_ENV_SETUP

Commands to set up the necessary directory structure for application data.

```bash
mkdir /volume/docker_appdata/netalertx
```

```bash
mkdir /volume/docker_appdata/netalertx/db
```

```bash
mkdir /volume/docker_appdata/netalertx/config
```

--------------------------------

### Get Event Totals cURL Request

Source: https://docs.netalertx.com/API_EVENTS?q=

Example cURL command to get event totals for a 7-day period.

```bash
curl "http://<server_ip>:<GRAPHQL_PORT>/sessions/totals?period=7 days" \
  -H "Authorization: Bearer <API_TOKEN>"
```

--------------------------------

### Initialize Plugin Folder

Source: https://docs.netalertx.com/PLUGINS_DEV_QUICK_START

Commands to create a new plugin directory from the existing template.

```bash
cd /workspaces/NetAlertX/front/plugins
cp -r __template my_plugin
cd my_plugin
```

--------------------------------

### Get Events cURL Request

Source: https://docs.netalertx.com/API_EVENTS?q=

Example cURL command to retrieve events for a specific device.

```bash
curl "http://<server_ip>:<GRAPHQL_PORT>/events?mac=00:11:22:33:44:55" \
  -H "Authorization: Bearer <API_TOKEN>"
```

--------------------------------

### Prepare Host Directories

Source: https://docs.netalertx.com/DOCKER_PORTAINER?q=

Create the necessary data, database, and log directories on the Docker host before deployment.

```bash
mkdir -p /local_data_dir/netalertx/config
mkdir -p /local_data_dir/netalertx/db
mkdir -p /local_data_dir/netalertx/log

```

--------------------------------

### Calendar View via cURL

Source: https://docs.netalertx.com/API_SESSIONS

Example request to retrieve calendar session data using the GET method.

```bash
curl -X GET "http://<server_ip>:<GRAPHQL_PORT>/sessions/calendar?start=2025-08-01&end=2025-08-21" \
  -H "Authorization: Bearer <API_TOKEN>" \
  -H "Accept: application/json"
```

--------------------------------

### Run the development container

Source: https://docs.netalertx.com/DEV_ENV_SETUP

Command to start the application using the specified environment file.

```bash
cd /development/NetAlertX &&  sudo docker-compose --env-file ../.env_dev
```

--------------------------------

### Download the source code

Source: https://docs.netalertx.com/DEV_ENV_SETUP

Commands to create a development directory and clone the repository.

```bash
mkdir /development
```

```bash
cd /development && git clone https://github.com/netalertx/NetAlertX.git
```

--------------------------------

### Get Unread Notifications Response

Source: https://docs.netalertx.com/API_MESSAGING_IN_APP?q=

Retrieve a list of unread notifications containing timestamp, GUID, read status, level, and content.

```json
[
  {
    "timestamp": "2025-10-10T12:34:56",
    "guid": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
    "read": 0,
    "level": "alert",
    "content": "This is a test notification"
  }
]
```

--------------------------------

### GET /devices/latest

Source: https://docs.netalertx.com/API_DEVICES?q=

Get the most recently connected device.

```APIDOC
## GET /devices/latest

### Description
Get the most recently connected device.

### Method
GET

### Endpoint
/devices/latest

### Response
#### Success Response (200)
- **device** (array) - Array containing the latest device object

#### Response Example
[
  { "devName": "Latest Device", "devMac": "AA:BB:CC:DD:EE:FF", "devLastIP": "192.168.1.100", "devFirstConnection": "2025-12-07 10:30:00" }
]
```

--------------------------------

### Prepare host directories

Source: https://docs.netalertx.com/DOCKER_PORTAINER

Create the necessary data directories on the Docker host before deployment.

```bash
mkdir -p /local_data_dir/netalertx/config
mkdir -p /local_data_dir/netalertx/db
mkdir -p /local_data_dir/netalertx/log
```

--------------------------------

### GET /events/last

Source: https://docs.netalertx.com/API_EVENTS?q=

Get the 10 most recent events.

```APIDOC
## GET /events/last

### Description
Get the 10 most recent events.

### Method
GET

### Endpoint
/events/last

### Response
#### Success Response (200)
- **success** (boolean) - Status of the operation
- **count** (int) - Number of events returned
- **events** (array) - List of event objects
```

--------------------------------

### Generic MCP Client Implementation

Source: https://docs.netalertx.com/API_MCP

Python example using the MCP SDK to connect to the NetAlertX server, list tools, and execute a tool call.

```python
import asyncio
import json
from mcp import ClientSession, StdioServerParameters
from mcp.client.stdio import stdio_client

async def main():
    # Connect to NetAlertX MCP server
    server_params = StdioServerParameters(
        command="curl",
        args=[
            "-N", "-H", "Authorization: Bearer <API_TOKEN>",
            "http://your-server:<GRAPHQL_PORT>/mcp/sse"
        ]
    )

    async with stdio_client(server_params) as (read, write):
        async with ClientSession(read, write) as session:
            # Initialize connection
            await session.initialize()

            # List available tools
            tools = await session.list_tools()
            print(f"Available tools: {[t.name for t in tools.tools]}")

            # Call a tool
            result = await session.call_tool("search_devices", {"query": "router"})
            print(f"Search result: {result}")

if __name__ == "__main__":
    asyncio.run(main())
```

--------------------------------

### DELETE /messaging/in-app/delete/<guid>

Source: https://docs.netalertx.com/API_MESSAGING_IN_APP

Removes a single notification by its GUID.

```APIDOC
## DELETE /messaging/in-app/delete/<guid>

### Description
Remove a single notification by its GUID.

### Method
DELETE

### Endpoint
/messaging/in-app/delete/<guid>

### Parameters
#### Path Parameters
- **guid** (string) - Required - The unique identifier of the notification

### Response
#### Success Response (200)
- **success** (boolean) - Indicates if the operation was successful

#### Error Response
- **success** (boolean) - False
- **error** (string) - Error message
```

--------------------------------

### GET /devices/network/topology

Source: https://docs.netalertx.com/API_DEVICES?q=

Get network topology showing device relationships.

```APIDOC
## GET /devices/network/topology

### Description
Get network topology showing device relationships.

### Method
GET

### Endpoint
/devices/network/topology

### Response
#### Success Response (200)
- **nodes** (array) - List of device nodes
- **links** (array) - List of connections between nodes

#### Response Example
{
  "nodes": [{ "id": "AA:AA:AA:AA:AA:AA", "name": "Router", "vendor": "VendorA" }],
  "links": [{ "source": "AA:AA:AA:AA:AA:AA", "target": "BB:BB:BB:BB:BB:BB", "port": "eth1" }]
}
```

--------------------------------

### Example Metrics Output

Source: https://docs.netalertx.com/API_METRICS

Sample response format showing aggregate device counts and individual device status labels.

```text
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
...
```

--------------------------------

### Define .env_dev configuration

Source: https://docs.netalertx.com/DEV_ENV_SETUP

Example content for the .env_dev file with required environment variables.

```text
#--------------------------------
#NETALERTX
#--------------------------------
PORT=22222    # make sure this port is unique on your whole network
DEV_LOCATION=/development/NetAlertX
APP_DATA_LOCATION=/volume/docker_appdata
# Make sure your GRAPHQL_PORT setting has a port that is unique on your whole host network
APP_CONF_OVERRIDE={"GRAPHQL_PORT":"22223"}
# ALWAYS_FRESH_INSTALL=true # uncommenting this will always delete the content of /config and /db dirs on boot to simulate a fresh install
```

--------------------------------

### POST /messaging/in-app/read/<guid>

Source: https://docs.netalertx.com/API_MESSAGING_IN_APP

Marks a single notification as read using its GUID.

```APIDOC
## POST /messaging/in-app/read/<guid>

### Description
Mark a single notification as read using its GUID.

### Method
POST

### Endpoint
/messaging/in-app/read/<guid>

### Parameters
#### Path Parameters
- **guid** (string) - Required - The unique identifier of the notification

### Response
#### Success Response (200)
- **success** (boolean) - Indicates if the operation was successful

#### Error Response
- **success** (boolean) - False
- **error** (string) - Error message
```

--------------------------------

### Define Localization Keys

Source: https://docs.netalertx.com/SETTINGS_SYSTEM?q=

Example of adding localized name and description keys for a setting.

```json
"UI_DEV_SECTIONS_name": "Hide device sections",
"UI_DEV_SECTIONS_description": "Select which UI elements to hide on the Devices page."
```

--------------------------------

### GET /events/recent

Source: https://docs.netalertx.com/API_EVENTS?q=

Get events from the last 24 hours or the last N hours.

```APIDOC
## GET /events/recent

### Description
Get events from the last 24 hours or the last N hours.

### Method
GET

### Endpoint
/events/recent or /events/<hours>

### Response
#### Success Response (200)
- **success** (boolean) - Status of the operation
- **hours** (int) - Time window in hours
- **count** (int) - Number of events returned
- **events** (array) - List of event objects
```

--------------------------------

### Example table_devices.json Output

Source: https://docs.netalertx.com/API_OLD?q=

A sample response from the table_devices.json endpoint showing the structure of device records.

```json
{
  "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"
      }
    ]
}
```

--------------------------------

### Get Unread Notifications via cURL

Source: https://docs.netalertx.com/API_MESSAGING_IN_APP?q=

Execute a GET request to fetch all unread notifications.

```bash
curl -X GET "http://<server_ip>:<GRAPHQL_PORT>/messaging/in-app/unread" \
  -H "Authorization: Bearer <API_TOKEN>" \
  -H "Accept: application/json"
```

--------------------------------

### Initialize Docker Volume

Source: https://docs.netalertx.com/DOCKER_MAINTENANCE?q=

Starts and immediately stops the container to initialize the volume structure.

```bash
docker-compose up -d && docker-compose down
```

--------------------------------

### query GetSettings

Source: https://docs.netalertx.com/API_GRAPHQL

Retrieves a list of system settings and the total count of settings available in the configuration.

```APIDOC
## GraphQL Query: GetSettings

### Description
Fetches the configuration settings stored in the NetAlertX settings table.

### Query
```graphql
query GetSettings {
  settings {
    settings {
      setKey
      setName
      setDescription
      setType
      setOptions
      setGroup
      setValue
      setEvents
      setOverriddenByEnv
    }
    count
  }
}
```

### Fields
- **setKey** (String): Unique key identifier for the setting.
- **setName** (String): Human-readable name.
- **setDescription** (String): Description or documentation of the setting.
- **setType** (String): Data type (string, int, bool, json, etc.).
- **setOptions** (String): Available options (for dropdown/select-type settings).
- **setGroup** (String): Group/category the setting belongs to.
- **setValue** (String): Current value of the setting.
- **setEvents** (String): Events or triggers related to this setting.
- **setOverriddenByEnv** (Boolean): Whether the setting is overridden by an environment variable at runtime.

### Example Request
```bash
curl 'http://host:GRAPHQL_PORT/graphql' \
  -X POST \
  -H 'Authorization: Bearer API_TOKEN' \
  -H 'Content-Type: application/json' \
  --data '{"query": "query GetSettings { settings { settings { setKey setName setDescription setType setOptions setGroup setValue setEvents setOverriddenByEnv } count } }"}'
```

### Example Response
```json
{
  "data": {
    "settings": {
      "settings": [
        {
          "setKey": "UI_MY_DEVICES",
          "setName": "My Devices Filter",
          "setDescription": "Defines which statuses to include in the 'My Devices' view.",
          "setType": "list",
          "setOptions": "[\"online\",\"new\",\"down\",\"offline\",\"archived\"]",
          "setGroup": "UI",
          "setValue": "[\"online\",\"new\"]",
          "setEvents": null,
          "setOverriddenByEnv": false
        }
      ],
      "count": 1
    }
  }
}
```
```

--------------------------------

### Install NetAlertX on Proxmox

Source: https://docs.netalertx.com/HW_INSTALL

Downloads and executes the Proxmox installation script for Debian 13 or Ubuntu 24 containers.

```bash
wget https://raw.githubusercontent.com/jokob-sk/NetAlertX/main/install/proxmox/proxmox-install-netalertx.sh -O proxmox-install-netalertx.sh && chmod +x proxmox-install-netalertx.sh && ./proxmox-install-netalertx.sh
```

--------------------------------

### Implement Plugin Script

Source: https://docs.netalertx.com/PLUGINS_DEV_QUICK_START

Python boilerplate for data collection logic, including path setup and result logging.

```python
#!/usr/bin/env python3

import sys
import os
sys.path.insert(0, os.path.join(os.path.dirname(__file__), '../../server'))
sys.path.insert(0, os.path.join(os.path.dirname(__file__), '../plugins'))

from plugin_helper import Plugin_Objects, mylog
from helper import get_setting_value
from const import logPath

pluginName = "MYPLN"

LOG_PATH = logPath + "/plugins"
LOG_FILE = os.path.join(LOG_PATH, f"script.{pluginName}.log")
RESULT_FILE = os.path.join(LOG_PATH, f"last_result.{pluginName}.log")

# Initialize
plugin_objects = Plugin_Objects(RESULT_FILE)

try:
    # Your data collection logic here
    # For example, scan something and collect results

    # Add an object to results
    plugin_objects.add_object(
        objectPrimaryId="example_id",
        objectSecondaryId=None,
        DateTime="2023-01-02 15:56:30",
        watchedValue1="value1",
        watchedValue2=None,
        watchedValue3=None,
        watchedValue4=None,
        Extra="additional_data",
        ForeignKey=None
    )

    # Write results to the log file
    plugin_objects.write_result_file()

except Exception as e:
    mylog("none", f"Error: {e}")
    sys.exit(1)
```

--------------------------------

### Initialize and write plugin data using plugin_helper.py

Source: https://docs.netalertx.com/PLUGINS_DEV_DATA_CONTRACT

Use the Plugin_Objects class to handle data validation, sanitization, and file output automatically. Ensure the prefix matches the plugin's identifier.

```python
from plugin_helper import Plugin_Objects

# Initialize with your plugin's prefix
plugin_objects = Plugin_Objects("YOURPREFIX")

# Add objects
plugin_objects.add_object(
    objectPrimaryId="device_id",
    objectSecondaryId="192.168.1.1",
    DateTime="2023-01-02 15:56:30",
    watchedValue1="online",
    watchedValue2=None,
    watchedValue3=None,
    watchedValue4=None,
    Extra="Additional data",
    ForeignKey="aa:bb:cc:dd:ee:ff",
    helpVal1=None,
    helpVal2=None,
    helpVal3=None,
    helpVal4=None
)

# Write results (handles formatting, sanitization, and file creation)
plugin_objects.write_result_file()
```

--------------------------------

### Override Environment Variables via Command Line

Source: https://docs.netalertx.com/DOCKER_COMPOSE

Examples of overriding default configuration settings using environment variables during container startup.

```bash
PORT=8080 docker compose up
```

```bash
NETALERTX_NETWORK_MODE=host \
LISTEN_ADDR=0.0.0.0 \
PORT=20211 \
GRAPHQL_PORT=20212 \
NETALERTX_DEBUG=0 \
docker compose up
```

--------------------------------

### Configure Docker Volumes

Source: https://docs.netalertx.com/DOCKER_MAINTENANCE?q=

Example configuration for switching from a local bind mount to a Docker-managed volume in docker-compose.yml.

```yaml
...
    volumes:
      - type: volume
        source: netalertx_config
        target: /data/config
        read_only: false
...
    # Example custom local folder called /data/netalertx_config
    # - type: bind
    #   source: /data/netalertx_config
    #   target: /data/config
    #   read_only: false
...
```

--------------------------------

### GET /messaging/in-app/unread

Source: https://docs.netalertx.com/API_MESSAGING_IN_APP

Retrieves all unread notifications.

```APIDOC
## GET /messaging/in-app/unread

### Description
Retrieve all unread notifications.

### Method
GET

### Endpoint
/messaging/in-app/unread

### Response
#### Success Response (200)
- **timestamp** (string) - Notification timestamp
- **guid** (string) - Unique identifier for the notification
- **read** (integer) - Read status (0 for unread)
- **level** (string) - Notification level
- **content** (string) - Notification message
```

--------------------------------

### Define Device Discovery Plugin Configuration

Source: https://docs.netalertx.com/PLUGINS_DEV_DATASOURCES?q=

Example configuration for a device discovery plugin specifying its execution layer and data source mapping.

```json
{
  "code_name": "device_scanner",
  "unique_prefix": "DEVSCAN",
  "execution_order": "Layer_0",
  "data_source": "script",
  "mapped_to_table": "CurrentScan"
}
```

--------------------------------

### Example database mapping

Source: https://docs.netalertx.com/PLUGINS_DEV_CONFIG

Shows the mapping of a primary object identifier to a device MAC address.

```text
objectPrimaryId → devMAC
```

--------------------------------

### GET /devices

Source: https://docs.netalertx.com/API_DEVICES?q=

Retrieves all devices from the database.

```APIDOC
## GET /devices

### Description
Retrieves all devices from the database.

### Method
GET

### Endpoint
/devices

### Response
#### Success Response (200)
- **success** (boolean) - Status of the request
- **devices** (array) - List of device objects

#### Response Example
{
  "success": true,
  "devices": [
    {
      "devName": "Net - Huawei",
      "devMAC": "AA:BB:CC:DD:EE:FF",
      "devIP": "192.168.1.1",
      "devType": "Router",
      "devFavorite": 0,
      "devStatus": "online"
    }
  ]
}
```

--------------------------------

### settings Query

Source: https://docs.netalertx.com/API_GRAPHQL?q=

Retrieves the system configuration settings including keys, names, descriptions, types, and current values.

```APIDOC
## GraphQL Query: settings

### Description
Retrieves the configuration settings stored in the NetAlertX settings table.

### Operation
query GetSettings { settings { settings { setKey setName setDescription setType setOptions setGroup setValue setEvents setOverriddenByEnv } count } }

### Fields
- **setKey** (String) - Unique key identifier for the setting.
- **setName** (String) - Human-readable name.
- **setDescription** (String) - Description or documentation of the setting.
- **setType** (String) - Data type (string, int, bool, json, etc.).
- **setOptions** (String) - Available options (for dropdown/select-type settings).
- **setGroup** (String) - Group/category the setting belongs to.
- **setValue** (String) - Current value of the setting.
- **setEvents** (String) - Events or triggers related to this setting.
- **setOverriddenByEnv** (Boolean) - Whether the setting is overridden by an environment variable at runtime.

### Request Example
curl 'http://host:GRAPHQL_PORT/graphql' \
  -X POST \
  -H 'Authorization: Bearer API_TOKEN' \
  -H 'Content-Type: application/json' \
  --data '{"query": "query GetSettings { settings { settings { setKey setName setDescription setType setOptions setGroup setValue setEvents setOverriddenByEnv } count } }"}'

### Response Example
{
  "data": {
    "settings": {
      "settings": [
        {
          "setKey": "UI_MY_DEVICES",
          "setName": "My Devices Filter",
          "setDescription": "Defines which statuses to include in the 'My Devices' view.",
          "setType": "list",
          "setOptions": "[\"online\",\"new\",\"down\",\"offline\",\"archived\"]",
          "setGroup": "UI",
          "setValue": "[\"online\",\"new\"]",
          "setEvents": null,
          "setOverriddenByEnv": false
        }
      ],
      "count": 1
    }
  }
}
```

--------------------------------

### GET /sessions/calendar

Source: https://docs.netalertx.com/API_SESSIONS

View sessions in calendar format.

```APIDOC
## GET /sessions/calendar

### Description
View sessions in calendar format.

### Method
GET

### Endpoint
/sessions/calendar

### Parameters
#### Query Parameters
- **start** (string) - Required - Start date (YYYY-MM-DD)
- **end** (string) - Required - End date (YYYY-MM-DD)

### Response
#### Success Response (200)
- **success** (boolean) - Status of the operation
- **sessions** (array) - List of calendar session objects

#### Response Example
{
  "success": true,
  "sessions": [
    {
      "resourceId": "AA:BB:CC:DD:EE:FF",
      "title": "",
      "start": "2025-08-01T10:00:00",
      "end": "2025-08-01T12:00:00",
      "color": "#00a659",
      "tooltip": "Connection: 2025-08-01 10:00\nDisconnection: 2025-08-01 12:00\nIP: 192.168.1.10",
      "className": "no-border"
    }
  ]
}
```

--------------------------------

### Template Syntax Example

Source: https://docs.netalertx.com/NOTIFICATION_TEMPLATES?q=

Basic usage of placeholders within a template string.

```text
{devName} ({eveMac}) connected at {eveDateTime}
```

--------------------------------

### GET /nettools/interfaces

Source: https://docs.netalertx.com/API_NETTOOLS?q=

Lists the available network interfaces.

```APIDOC
## GET /nettools/interfaces

### Description
Returns a list of network interfaces on the server.

### Method
GET

### Endpoint
/nettools/interfaces
```

--------------------------------

### POST /sessions/create

Source: https://docs.netalertx.com/API_SESSIONS

Create a new session for a device.

```APIDOC
## POST /sessions/create

### Description
Create a new session for a device.

### Method
POST

### Endpoint
/sessions/create

### Request Body
- **mac** (string) - Required - Device MAC address
- **ip** (string) - Required - Device IP address
- **start_time** (string) - Required - Start timestamp
- **end_time** (string) - Optional - End timestamp
- **event_type_conn** (string) - Optional - Connection event type
- **event_type_disc** (string) - Optional - Disconnection event type

### Request Example
{
  "mac": "AA:BB:CC:DD:EE:FF",
  "ip": "192.168.1.10",
  "start_time": "2025-08-01T10:00:00",
  "end_time": "2025-08-01T12:00:00",
  "event_type_conn": "Connected",
  "event_type_disc": "Disconnected"
}

### Response
#### Success Response (200)
- **success** (boolean) - Status of the operation
- **message** (string) - Confirmation message

#### Response Example
{
  "success": true,
  "message": "Session created for MAC AA:BB:CC:DD:EE:FF"
}
```

--------------------------------

### GET /nettools/speedtest

Source: https://docs.netalertx.com/API_NETTOOLS?q=

Initiates a network speed test.

```APIDOC
## GET /nettools/speedtest

### Description
Runs a network speed test.

### Method
GET

### Endpoint
/nettools/speedtest
```

--------------------------------

### Run Container as Root to Fix Permissions

Source: https://docs.netalertx.com/FILE_PERMISSIONS

Execute the container as root to trigger the startup script to automatically correct volume ownership.

```bash
docker run -it --rm --name netalertx --user "0" \
  -v /local_data_dir:/data \
  --tmpfs /tmp:uid=20211,gid=20211,mode=1700 \
  ghcr.io/netalertx/netalertx:latest
```

--------------------------------

### GET /devices

Source: https://docs.netalertx.com/API_DEVICES?q=

Retrieves a list of all network devices.

```APIDOC
## GET /devices

### Description
Retrieves a list of all network devices.

### Method
GET

### Endpoint
http://<server_ip>:<GRAPHQL_PORT>/devices
```

--------------------------------

### Define plugin settings with plugin_type

Source: https://docs.netalertx.com/PLUGINS_DEV_DATASOURCES?q=

Example configuration for defining plugin settings using the plugin_type data source.

```json
{
  "settings": [
    {
      "function": "plugin_type",
      "type": {"dataType": "string", "elements": []},
      "default_value": "scanner",
      "options": ["scanner"],
      "data_source": "plugin_type",
      "value": "scanner",
      "localized": []
    }
  ]
}
```

--------------------------------

### GET /devices/by-status

Source: https://docs.netalertx.com/API_DEVICES?q=

Returns devices filtered by status.

```APIDOC
## GET /devices/by-status

### Description
Returns devices filtered by status.

### Method
GET

### Endpoint
/devices/by-status

### Parameters
#### Query Parameters
- **status** (string) - Optional - online, offline, down, archived, favorites, new, my

### Response
#### Success Response (200)
- **devices** (array) - List of device objects

#### Response Example
[
  { "id": "AA:BB:CC:DD:EE:FF", "title": "Net - Huawei", "favorite": 0 }
]
```

--------------------------------

### GET /devices/export

Source: https://docs.netalertx.com/API_DEVICES

Exports device data in CSV format.

```APIDOC
## GET /devices/export

### Description
Exports the current device list as a CSV file.

### Method
GET

### Endpoint
/devices/export

### Query Parameters
- **format** (string) - Required - The export format, e.g., 'csv'
```

--------------------------------

### Custom resolv.conf Configuration

Source: https://docs.netalertx.com/REVERSE_DNS

Define the nameserver and resolution options within the custom resolv.conf file.

```text
nameserver 192.168.178.11
options edns0 trust-ad
search example.com
```

--------------------------------

### cURL Request for Settings

Source: https://docs.netalertx.com/API_GRAPHQL

Example of executing the settings query using cURL with authentication headers.

```bash
curl 'http://host:GRAPHQL_PORT/graphql' \
  -X POST \
  -H 'Authorization: Bearer API_TOKEN' \
  -H 'Content-Type: application/json' \
  --data '{
    "query": "query GetSettings { settings { settings { setKey setName setDescription setType setOptions setGroup setValue setEvents setOverriddenByEnv } count } }"
  }'
```

--------------------------------

### GET /sessions/<mac>

Source: https://docs.netalertx.com/API_SESSIONS

Retrieve sessions for a specific device.

```APIDOC
## GET /sessions/<mac>

### Description
Retrieve sessions for a specific device.

### Method
GET

### Endpoint
/sessions/<mac>

### Parameters
#### Path Parameters
- **mac** (string) - Required - Device MAC address

#### Query Parameters
- **period** (string) - Optional - Period to retrieve sessions (e.g., 1 day, 7 days). Default: 1 day

### Response
#### Success Response (200)
- **success** (boolean) - Status of the operation
- **sessions** (array) - List of session objects

#### Response Example
{
  "success": true,
  "sessions": [
    {
      "sesMac": "AA:BB:CC:DD:EE:FF",
      "sesDateTimeConnection": "2025-08-01 10:00",
      "sesDateTimeDisconnection": "2025-08-01 12:00",
      "sesDuration": "2h 0m",
      "sesIp": "192.168.1.10",
      "sesAdditionalInfo": ""
    }
  ]
}
```
Tokens:
Raw