Overview

The existing Amazon GREF Email Bot (SES-based) is used by installers on-site to verify that devices are checking in correctly before leaving a site. However, the email-based workflow introduces delays, retries, and occasional non-responses, which impacts installation efficiency.

This document proposes a set of REST APIs that directly query GREF’s backend infrastructure services (e.g., AWS Timestream) to provide the same information currently delivered via the email bot - in a faster, more reliable, and programmatic manner.

These APIs and their responses are designed to mimic the structure and content of existing email reports so that installer workflows and UI consumers can transition smoothly.

These APIs will be integrated into Atria as a new applet. Once the proposed Atria applet consumes these endpoints, the existing email bot can be safely deprecated.

Goals

Replace SES-based email bot with synchronous APIs
Preserve existing installer-facing information and semantics
Provide consistent device health calculations
Support both device-level and site-level verification flows

Common Concepts

Device Health Status

Derived from the most recent telemetry timestamp:

Status	Condition

Status	Condition
Healthy	Last update within 30 minutes
Warning	Last update between 30–90 minutes
Critical	Last update older than 90 minutes

Time Window

Unless specified otherwise, recent telemetry refers to the last 60 minutes of data.

API 1: Device Information Report

Provides detailed metadata and recent telemetry for a single device. This API replaces the "Device Information Report" email.

Endpoint

GET /devices/{deviceId}/report

Path Parameters

Name	Type	Required	Description

Name	Type	Required	Description
deviceId	string	Yes	Last 5 digits of device EUI (e.g., `07587`)

Query Parameters

Name	Type	Required	Default	Description

Name	Type	Required	Default	Description
lookbackMinutes	number	No	60	Telemetry lookback window
numDataPoints	number	No	5	No. of telemetry data points

Example API Call

GET /devices/00800000D0007587/report?siteId=sea24&lookbackMinutes=90

Response (200 OK)

{
  "generatedAt": "2025-12-03T23:43:25Z",
  "deviceHealth": {
    "status": "Healthy",
    "lastUpdatedMinutesAgo": 2
  },
  "request": {
    "siteId": "sea24",
    "requestedDeviceId": "07587",
    "fullDeviceId": "00800000D0007587"
  },
  "deviceInfo": {
    "deviceId": "00800000D0007587",
    "deviceType": "WirelessGateway",
    "deviceMake": "MultiTech",
    "deviceModel": "MTCAP3-LNA7D-A23UEA-LUM.R1",
    "serialNumber": "23425166",
    "assetTag": "G00160010",
    "site": "warehouse us",
    "sensorLocation": "Warehouse US",
    "floor": "P1",
    "rfRegion": "US915",
    "stage": "iad-prod",
    "healthStatus": "connected",
    "healthLastUpdatedTimestamp": 1764794346675
  },
  "recentTelemetry": [
    {
      "devEui": "0004a30b0129a6fd",
      "gatewayEui": "00800000d0007587",
      "gatewayRssi": -45.0,
      "timestamp": "2025-12-03T23:41:22Z",
      "battery": 3.32,
      "meterValue": 1.0,
      "pulseCount": 1.0,
      "usGallon": null
    }
  ]
}

Notes

Fields such as meterValue, pulseCount, and usGallon are device-type dependent and may be null.
API supports both pulse counter and Subeca devices with a unified schema.
The API evaluates both lookbackMinutes and numDataPoints, and returns telemetry using the option that results in the maximum data.

API 2: Site Report

Provides a summarized view of all devices at a site, replacing the "Site Report" email.

Endpoint

GET /sites/{siteId}/report

Path Parameters

Name	Type	Required	Description

Name	Type	Required	Description
siteId	string	Yes	Site identifier (e.g., `sea24`)

Query Parameters

Name	Type	Required	Default	Description

Name	Type	Required	Default	Description
lookbackMinutes	number	No	60	Telemetry lookback window
numDataPoints	number	No	5	No. of telemetry data points

Example API Call

GET /sites/sea24/report?lookbackMinutes=90

Response (200 OK)

{
  "generatedAt": "2025-12-09T19:49:35Z",
  "siteId": "sea24",
  "summary": {
    "totalDevices": 3,
    "healthy": 3,
    "warning": 0,
    "critical": 0
  },
  "devices": [
    {
      "deviceId": "00800000D0007587",
      "floor": "P1",
      "location": "Engineer_Room",
      "healthStatus": "Healthy",
      "lastUpdatedMinutesAgo": 7,
      "gatewayRssi": -43.0,
      "battery": 3.32
    },
    {
      "deviceId": "0004A30B0126B291",
      "floor": "Garage",
      "location": "Electrical_Room",
      "healthStatus": "Healthy",
      "lastUpdatedMinutesAgo": 10,
      "gatewayRssi": -73.0,
      "battery": 3.32
    }
  ]
}

Note

The API evaluates both lookbackMinutes and numDataPoints, and returns telemetry using the option that results in the maximum data.

Error Responses

Status	Meaning

Status	Meaning
400	Invalid request parameters
404	Device or site not found
409	Device not associated with site
500	Backend data source failure

Appendix 1: Mapping to Email Bot

Email Section	API Field

Email Section	API Field
Device Health Status	`deviceHealth`
Device Information	`deviceInfo`
Recent Telemetry Data	`recentTelemetry`
Site Summary	`summary`
Device Details Table	`devices[]`

Appendix 2: Email Samples (Current State)

Sample 1: Device Information Report

Subject: Device info - 00800000D0007587

🔧 Device Information Report

Generated: 2025-12-03 23:43:25 UTC

Device Health Status

Healthy (Last updated 2 minutes ago)

📋 Request Details

Site ID:	warehouse us
Requested Device ID:	00800000D0007587
Full Device ID:	00800000D0007587

🖥️ Device Information

Devicetype:	WirelessGateway
Site:	warehouse us
Assettag:	G00160010
Healthlastupdatedtimestamp:	1764794346675
Devicemake:	MultiTech
Serialnumber:	23425166
Stage:	iad-prod
Devicemodel:	MTCAP3-LNA7D-A23UEA-LUM.R1
Sensorlocation:	Warehouse US
Floor:	P1
Healthstatus:	connected
Deviceid:	00800000D0007587
Rfregion:	US915

📊 Recent Telemetry Data (Last 60 minutes)

Deveui	Gatewayeui	Gatewayrssi	Time	Battery	Metervalue	Metervalue2	Metervalue3	Pulsecount	Pulsecount2	Pulsecount3	Usgallon

Deveui	Gatewayeui	Gatewayrssi	Time	Battery	Metervalue	Pulsecount	Usgallon
0004a30b0129a6fd	00800000d0007587	-45.0	2025-12-03 23:41:22	3.32	1.0	1.0	None
0004a30b012dbeeb	00800000d0007587	-39.0	2025-12-03 23:32:28	3.31	567.0	567.0	None
0004a30b0129a6fd	00800000d0007587	-44.0	2025-12-03 23:26:21	3.32	1.0	1.0	None

Legend:

🟢 Healthy: Device updated within 30 minutes

🟡 Warning: Device updated 30-90 minutes ago

🔴 Critical: Device updated more than 90 minutes ago

This is an automated response to your device information request. If you need additional information, please contact support.

Sample 2: Site Report

Subject: Site Report for sea24 (Email 1 of 3)

🏢 Site Report: sea24

Generated: 2025-12-09 19:49:35 UTC

📊 Summary

Total Devices: 3 | Healthy: 3 | Warning: 0 | Critical: 0

🔧 Device Details

Device ID	Floor	Location	Health Status	Gateway Rssi	Battery

Device ID	Floor	Location	Health Status	Gateway Rssi	Battery
00800000D0007587	P1	Engineer_Room	Healthy (Last updated 7 minutes ago)	-43.0	3.32
0004A30B0126B291	Garage	Electrical_Room	Healthy (Last updated 10 minutes ago)	-73.0	3.32
00800000D0007586	Garage	Electrical_Room	Healthy (Last updated 10 minutes ago)	-73.0	3.32

Proposal - Device & Site APIs (GREF Email Bot Replacement)

Overview

Goals

Common Concepts

Device Health Status

Time Window

API 1: Device Information Report

Endpoint

Path Parameters

Query Parameters

Example API Call

Response (200 OK)

Notes

API 2: Site Report

Endpoint

Path Parameters

Query Parameters

Example API Call

Response (200 OK)

Note

Error Responses

Appendix 1: Mapping to Email Bot

Appendix 2: Email Samples (Current State)

Sample 1: Device Information Report

🔧 Device Information Report

Device Health Status

Sample 2: Site Report

🏢 Site Report: sea24

📊 Summary

🔧 Device Details