# LitmusEdge 4.0.x API Documentation/System/Events - LE, LEM, LUNS API Docs

## Get Events

**POST** `{{edgeUrl}}/events/query`

# Get Events

Returns a page of historical device events with optional filters by severity, event ID, time window, and free-text. This is the only GraphQL endpoint in `System`.

## Endpoint

```http
POST {{edgeUrl}}/events/query
Content-Type: application/json
```

## Authentication

HTTP Basic Auth. **Username** is your API token, **password** is empty. Tokens are managed under `System > Access Control > Tokens`.

## Request body (GraphQL)

```graphql
query events($filter: HistoryFilter, $offset: Int!, $count: Int!) {
  severityList
  events(filter: $filter, offset: $offset, count: $count) {
    events {
      component eventId severity msg
      time { utc local }
      attrs { name value }
    }
    total
  }
}
```

### Variables

| Field                   | Type    | Required | Description                                                                |
|-------------------------|---------|----------|----------------------------------------------------------------------------|
| `offset` / `count`      | integer | Yes      | Paging.                                                                    |
| `filter.severity`       | string  | No       | `"info"`, `"warn"`, or `"alert"`.                                          |
| `filter.eventId`        | object  | No       | Inclusion / exclusion list for specific event IDs.                         |
| `filter.fromTimestamp` / `toTimestamp` | integer | No | Unix epoch milliseconds.                                          |

```json
{
  "offset": 0,
  "count": 10,
  "filter": {
    "eventId": {},
    "fromTimestamp": 1673213725331,
    "toTimestamp": 1704749725331
  }
}
```

## Response

`200 OK` -- `application/json`

| Field                       | Type    | Description                                                       |
|-----------------------------|---------|-------------------------------------------------------------------|
| `data.severityList`         | string[]| Legal severity values (`INFO`, `WARN`, `ALERT`).                  |
| `data.events.total`         | integer | Total matching events (across all pages).                          |
| `data.events.events[]`      | object[]| One entry per event.                                              |
| `events[].component`        | string  | Originating service.                                              |
| `events[].eventId`          | string  | Stable event identifier.                                           |
| `events[].severity`         | string  | One of `INFO`, `WARN`, `ALERT`.                                    |
| `events[].msg`              | string  | Free-form message.                                                |
| `events[].time.utc/local`   | string  | ISO 8601 timestamps.                                              |
| `events[].attrs`            | object[]| Event-specific `{name, value}` attributes.                         |

## Errors

| HTTP status         | When it happens                                                                |
|---------------------|--------------------------------------------------------------------------------|
| `400 Bad Request`   | Missing or malformed query/body parameter.                                     |
| `401 Unauthorized`  | Missing or invalid credentials.                                                |
| `403 Forbidden`     | Token lacks permission for this operation.                                     |
| `404 Not Found`     | Target entity does not exist.                                                  |
| `5xx`               | Service is unreachable, restarting, or internally errored. Inspect device logs under `System > Support`. |

> **TLS note**: edge devices use a self-signed certificate by default. Either install the device CA in your client trust store or disable certificate verification when calling this endpoint directly.


### Request Body

**GraphQL Query**

```graphql
query events($filter: HistoryFilter, $offset: Int!, $count: Int!) {
  severityList
  events(filter: $filter, offset: $offset, count: $count) {
    events {
      component
      eventId
      severity
      msg
      time {
        utc
        local
      }
      attrs {
        name
        value
      }
    }
    total
  }
}
```

**Variables**

```json
{
  "offset": 0,
  "count": 10,
  "filter": {
    "eventId": {},
    "fromTimestamp": 1673213725331,
    "toTimestamp": 1704749725331
  }
}
```

### Response

**Status**: 200 OK

```json
{
    "data": {
        "severityList": [
            "INFO",
            "WARN",
            "ALERT"
        ],
        "events": {
            "events": [],
            "total": 0
        }
    }
}
```

---

## Events Management Stats

**GET** `{{edgeUrl}}/events/mgmt/stats`

# Events Management Stats

Returns the on-disk size of the event log in bytes.

## Endpoint

```http
GET {{edgeUrl}}/events/mgmt/stats
```
## Authentication

HTTP Basic Auth. **Username** is your API token, **password** is empty. Tokens are managed under `System > Access Control > Tokens`.

## Response

```json
{ "size": 36864 }
```

## Errors

| HTTP status         | When it happens                                                                |
|---------------------|--------------------------------------------------------------------------------|
| `400 Bad Request`   | Missing or malformed query/body parameter.                                     |
| `401 Unauthorized`  | Missing or invalid credentials.                                                |
| `403 Forbidden`     | Token lacks permission for this operation.                                     |
| `404 Not Found`     | Target entity does not exist.                                                  |
| `5xx`               | Service is unreachable, restarting, or internally errored. Inspect device logs under `System > Support`. |

> **TLS note**: edge devices use a self-signed certificate by default. Either install the device CA in your client trust store or disable certificate verification when calling this endpoint directly.


### Response

**Status**: 200 OK

```json
{
    "size": 36864
}
```

---

## Zerotouch Reports

**GET** `{{edgeUrl}}/dm/zerotouch/reports`

# Zerotouch Reports

Returns the Zerotouch (zero-touch onboarding) reports recorded on the device. Useful for auditing initial provisioning.

## Endpoint

```http
GET {{edgeUrl}}/dm/zerotouch/reports
```
## Authentication

HTTP Basic Auth. **Username** is your API token, **password** is empty. Tokens are managed under `System > Access Control > Tokens`.

## Response

`200 OK` -- `application/json`. Empty array on devices that were not Zerotouch-provisioned.

## Errors

| HTTP status         | When it happens                                                                |
|---------------------|--------------------------------------------------------------------------------|
| `400 Bad Request`   | Missing or malformed query/body parameter.                                     |
| `401 Unauthorized`  | Missing or invalid credentials.                                                |
| `403 Forbidden`     | Token lacks permission for this operation.                                     |
| `404 Not Found`     | Target entity does not exist.                                                  |
| `5xx`               | Service is unreachable, restarting, or internally errored. Inspect device logs under `System > Support`. |

> **TLS note**: edge devices use a self-signed certificate by default. Either install the device CA in your client trust store or disable certificate verification when calling this endpoint directly.


---