GraphQL API Endpoint

GraphQL queries are read-optimized for speed. Data may be slightly out of date until the file system cache refreshes. The GraphQL endpoints allow you to access the following objects:

• Devices
• Settings
• Language Strings (LangStrings)

Endpoints

• GET /graphql Returns a simple status message (useful for browser or debugging).

• POST /graphql Execute GraphQL queries against the devicesSchema.

---

Devices Query

Sample Query

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

Query Parameters

Parameter	Description
page	Page number of results to fetch.
limit	Number of results per page.
sort	Sorting options (field = field name, order = asc or desc).
search	Term to filter devices.
status	Filter devices by status: my_devices, connected, favorites, new, down, archived, offline.
filters	Additional filters (array of { filterColumn, filterValue }).

---

curl 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"
      }
    }
  }'

---

Sample Response

{
  "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"
        }
      ],
      "count": 1
    }
  }
}

---

Settings Query

The settings query provides access to NetAlertX configuration stored in the settings table.

Sample Query

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

Schema Fields

Field	Type	Description
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.

---

curl 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 } }"
  }'

---

Sample Response

{
  "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
        },
        {
          "setKey": "NETWORK_DEVICE_TYPES",
          "setName": "Network Device Types",
          "setDescription": "Types of devices considered as network infrastructure.",
          "setType": "list",
          "setOptions": "[\"Router\",\"Switch\",\"AP\"]",
          "setGroup": "Network",
          "setValue": "[\"Router\",\"Switch\"]",
          "setEvents": null,
          "setOverriddenByEnv": true
        }
      ],
      "count": 2
    }
  }
}

---

LangStrings Query

The LangStrings query provides access to localized strings. Supports filtering by langCode and langStringKey. If the requested string is missing or empty, you can optionally fallback to en_us.

Sample Query

query GetLangStrings {
  langStrings(langCode: "de_de", langStringKey: "settings_other_scanners") {
    langStrings {
      langCode
      langStringKey
      langStringText
    }
    count
  }
}

Query Parameters

Parameter	Type	Description
langCode	String	Optional language code (e.g., en_us, de_de). If omitted, all languages are returned.
langStringKey	String	Optional string key to retrieve a specific entry.
fallback_to_en	Boolean	Optional (default true). If true, empty or missing strings fallback to en_us.

curl Example

curl 'http://host:GRAPHQL_PORT/graphql' \
  -X POST \
  -H 'Authorization: Bearer API_TOKEN' \
  -H 'Content-Type: application/json' \
  --data '{
    "query": "query GetLangStrings { langStrings(langCode: \"de_de\", langStringKey: \"settings_other_scanners\") { langStrings { langCode langStringKey langStringText } count } }"
  }'

Sample Response

{
  "data": {
    "langStrings": {
      "count": 1,
      "langStrings": [
        {
          "langCode": "de_de",
          "langStringKey": "settings_other_scanners",
          "langStringText": "Other, non-device scanner plugins that are currently enabled."  // falls back to en_us if empty
        }
      ]
    }
  }
}

---

Notes

• Device, settings, and LangStrings queries can be combined in one request since GraphQL supports batching.
• The fallback_to_en feature ensures UI always has a value even if a translation is missing.
• Data is cached in memory per JSON file; changes to language or plugin files will only refresh after the cache detects a file modification.
• The setOverriddenByEnv flag helps identify setting values that are locked at container runtime.
• The schema is read-only — updates must be performed through other APIs or configuration management. See the other API endpoints for details.