Events

Events are entities created by your Docksters devices — they allow you to track what happened to a specific device or the data points connected to a device.

Properties

  • Name
    deviceName
    Type
    string
    Description

    Unique identifier for the device that the event is connected to.

  • Name
    displayName
    Type
    string
    Description

    The display name for the device that the event is connected to.

  • Name
    sensorName
    Type
    string
    Description

    Unique identifier for the data point that created an event.

  • Name
    sensorType
    Type
    string
    Description

    Timestamp of when this event was created.

  • Name
    sensorValue
    Type
    any
    Description

    The data point value that is linked to this event, which triggered a threshold.

  • Name
    eventStatus
    Type
    string
    Description

    The status that this is linked to this event. This can be: INFO, WARNING, ERROR or CRITICAL.

  • Name
    eventCategory
    Type
    string
    Description

    The category this event belongs to. This can be: Sensors (when a threshold was hit) or Availability (when we lost contact with a device).

  • Name
    eventMessage
    Type
    string
    Description

    The event message, explained why this event was created.

  • Name
    receivedUTC
    Type
    timestamp
    Description

    Timestamp of when this event was created.

GET/events/list

List events

This endpoint allows you to retrieve a list of all the events generated by your Docksters devices.

Request

GET
/events/list
curl -G https://api.docksters.io/events/list \
  -H "Authorization: Bearer {token}"

Response

{
  "status": "success",
  "data": [
    {
      "sensorName": "Temperature",
      "eventStatus": "WARNING",
      "sensorValue": 16.5,
      "eventCategory": "Sensors",
      "displayName": "Open-plan Development Office",
      "deviceName": "device_4_devoffice",
      "receivedUTC": "2023-02-19T08:12:15.000Z",
      "sensorType": "tempC",
      "eventMessage": "Temperature - Temperature Low - Warning - 16.5 °C"
    },
    {
      "sensorName": "Humidity",
      "eventStatus": "WARNING",
      "sensorValue": 38,
      "eventCategory": "Sensors",
      "displayName": "Reception",
      "deviceName": "device_3_reception",
      "receivedUTC": "2023-02-19T08:07:54.000Z",
      "sensorType": "relativeHumidity",
      "eventMessage": "Humidity - Humidity Low - Warning - 38% RH"
    },
    {
      "sensorName": "Temperature",
      "eventStatus": "WARNING",
      "sensorValue": 17.2,
      "eventCategory": "Sensors",
      "displayName": "Hallway",
      "deviceName": "device_1_hallway",
      "receivedUTC": "2023-02-19T08:05:38.000Z",
      "sensorType": "tempC",
      "eventMessage": "Temperature - Temperature Low - Warning - 17.2 °C"
    }
  ]
}
POST/devices/events

List events by device

This endpoint allows you to retrieve a list of all the events generated by a specific Docksters device.

Required attributes

  • Name
    deviceName
    Type
    string
    Description

    The name of the device that you want to list events for.

Request

POST
/devices/events
curl -G https://api.docksters.io/devices/events \
  -H "Authorization: Bearer {token}"
  -d '{"deviceName": "device_1_hallway"}'

Response

{
  "status": "success",
  "data": [
    {
      "sensorName": "Temperature",
      "eventStatus": "WARNING",
      "sensorValue": 15.5,
      "eventCategory": "Sensors",
      "displayName": "Hallway",
      "deviceName": "device_1_hallway",
      "receivedUTC": "2023-02-19T08:11:54.000Z",
      "sensorType": "tempC",
      "eventMessage": "Temperature - Temperature Low - Warning - 15.5 °C"
    },
    {
      "sensorName": "Humidity",
      "eventStatus": "SUCCESS",
      "sensorValue": 44,
      "eventCategory": "Sensors",
      "displayName": "Hallway",
      "deviceName": "device_1_hallway",
      "receivedUTC": "2023-02-19T08:03:54.000Z",
      "sensorType": "relativeHumidity",
      "eventMessage": "Humidity - Returned to a Success status - 44% RH"
    }
  ]
}