Skip to content

API Documentation

This API provides programmatic access to devices, events, sessions, metrics, network tools, and sync in NetAlertX. It is implemented as a REST and GraphQL server. All requests require authentication via API Token (API_TOKEN setting) unless explicitly noted. For example, to authorize a GraphQL request, you need to use a Authorization: Bearer API_TOKEN header as per example below:

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

The API server runs on 0.0.0.0:<graphql_port> with CORS enabled for all main endpoints.

Authentication

All endpoints require an API token provided in the HTTP headers:

Authorization: Bearer <API_TOKEN>

If the token is missing or invalid, the server will return:

{
  "success": false,
  "message": "ERROR: Not authorized",
  "error": "Forbidden"
}

HTTP Status: 403 Forbidden

Base URL

http://<server>:<GRAPHQL_PORT>/

Endpoints

Tip

When retrieving devices or settings try using the GraphQL API endpoint first as it is read-optimized.

Standard REST Endpoints

  • Device API Endpoints – Manage individual devices
  • Devices Collection – Bulk operations on multiple devices
  • Events – Device event logging and management
  • Sessions – Connection sessions and history
  • Settings – Settings
  • Messaging:
  • Metrics – Prometheus metrics and per-device status
  • Network Tools – Utilities like Wake-on-LAN, traceroute, nslookup, nmap, and internet info
  • Online History – Online/offline device records
  • GraphQL – Advanced queries and filtering for Devices, Settings and Language Strings
  • Sync – Synchronization between multiple NetAlertX instances
  • Logs – Purging of logs and adding to the event execution queue for user triggered events
  • DB query (⚠ Internal) - Low level database access - use other endpoints if possible

MCP Server Bridge

NetAlertX includes an MCP (Model Context Protocol) Server Bridge that provides AI assistants access to NetAlertX functionality through standardized tools. MCP endpoints are available at /mcp/sse/* paths and mirror the functionality of standard REST endpoints:

  • /mcp/sse - Server-Sent Events endpoint for MCP client connections
  • /mcp/sse/openapi.json - OpenAPI specification for available MCP tools
  • /mcp/sse/device/*, /mcp/sse/devices/*, /mcp/sse/nettools/*, /mcp/sse/events/* - MCP-enabled versions of REST endpoints

MCP endpoints require the same Bearer token authentication as REST endpoints.

📖 See MCP Server Bridge API for complete documentation, tool specifications, and integration examples.

See Testing for example requests and usage.

Notes

  • All endpoints enforce Bearer token authentication.
  • Errors return JSON with success: False and an error message.
  • GraphQL is available for advanced queries, while REST endpoints cover structured use cases.
  • Endpoints run on 0.0.0.0:<GRAPHQL_PORT> with CORS enabled.
  • Use consistent API tokens and node/plugin names when interacting with /sync to ensure data integrity.