# 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
{ "error": "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.

* [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

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.