mirror of
https://github.com/jokob-sk/NetAlertX.git
synced 2025-12-30 02:18:16 -05:00
103 lines
3.8 KiB
Markdown
Executable File
103 lines
3.8 KiB
Markdown
Executable File
# 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:
|
||
|
||
```graphql
|
||
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:
|
||
|
||
```http
|
||
Authorization: Bearer <API_TOKEN>
|
||
```
|
||
|
||
If the token is missing or invalid, the server will return:
|
||
|
||
```json
|
||
{
|
||
"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](API_DEVICE.md) – Manage individual devices
|
||
* [Devices Collection](API_DEVICES.md) – Bulk operations on multiple devices
|
||
* [Events](API_EVENTS.md) – Device event logging and management
|
||
* [Sessions](API_SESSIONS.md) – Connection sessions and history
|
||
* [Settings](API_SETTINGS.md) – Settings
|
||
* Messaging:
|
||
* [In app messaging](API_MESSAGING_IN_APP.md) - In-app messaging
|
||
* [Metrics](API_METRICS.md) – Prometheus metrics and per-device status
|
||
* [Network Tools](API_NETTOOLS.md) – Utilities like Wake-on-LAN, traceroute, nslookup, nmap, and internet info
|
||
* [Online History](API_ONLINEHISTORY.md) – Online/offline device records
|
||
* [GraphQL](API_GRAPHQL.md) – Advanced queries and filtering for Devices, Settings and Language Strings
|
||
* [Sync](API_SYNC.md) – Synchronization between multiple NetAlertX instances
|
||
* [Logs](API_LOGS.md) – Purging of logs and adding to the event execution queue for user triggered events
|
||
* [DB query](API_DBQUERY.md) (⚠ 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](API_MCP.md) for complete documentation, tool specifications, and integration examples.**
|
||
|
||
See [Testing](API_TESTS.md) 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.
|