Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/Taykl12/Classify/llms.txt

Use this file to discover all available pages before exploring further.

The ESP32 Device API provides three endpoints that the ESP32-C3 SuperMini firmware communicates with directly. Two endpoints receive periodic heartbeats and button-press events from the hardware. A separate pair of admin endpoints allows privileged users to inspect device status and reset the press counter. These routes use a dedicated X-Device-Token header for device authentication — they do not use the standard Bearer token.
Device routes authenticate with the X-Device-Token header. The expected token value is set in server/.env as ESP32_DEVICE_TOKEN. In development environments the default token is dev-esp32-token. Make sure the value flashed into the firmware matches the value in your .env file exactly.

​
Device authentication

All /api/device/esp32/* endpoints require the following header: 
X-Device-Token: <ESP32_DEVICE_TOKEN>
Requests that omit this header or supply an incorrect token are rejected.

​
GET /api/device/esp32/heartbeat

Records a heartbeat timestamp from the device. The firmware sends this request every 8 seconds to signal that the device is alive. Exponential backoff up to 30 seconds is applied when the request fails.

​
Request

GET /api/device/esp32/heartbeat
X-Device-Token: <ESP32_DEVICE_TOKEN>

​
Response

{ "ok": true }

​
POST /api/device/esp32/heartbeat

Functionally identical to the GET variant above. Both methods record the same heartbeat timestamp. The firmware may use either depending on the implementation revision.

​
Request

POST /api/device/esp32/heartbeat
X-Device-Token: <ESP32_DEVICE_TOKEN>

​
Response

{ "ok": true }

​
POST /api/device/esp32/button

Records a button press event. The ESP32-C3 firmware sends this request when the BOOT button (GPIO 9) is released. Each successful call increments the cumulative press counter and returns the current device status.

​
Request

POST /api/device/esp32/button
X-Device-Token: <ESP32_DEVICE_TOKEN>
This endpoint requires no request body.

​
Response

Returns HTTP 200 with ok: true merged with the current ESP32 status object.

​
Response fields

​
ok
boolean
required
Always true when the button press was recorded successfully.
​
connected
boolean
required
true when a heartbeat has been received within the last 15 seconds.
​
pressCount
number
required
Cumulative number of button presses recorded since the last admin reset.
​
lastSeenAt
string | null
required
ISO 8601 datetime string of the most recent heartbeat received from the device, or null if no heartbeat has been recorded yet.

​
Example response

{
  "ok": true,
  "connected": true,
  "pressCount": 42,
  "lastSeenAt": "2024-07-16T14:32:10.000Z"
}

​
Code examples

curl --request POST \
  --url https://your-app.com/api/device/esp32/heartbeat \
  --header "X-Device-Token: dev-esp32-token"

​
Firmware behavior reference

The ESP32-C3 SuperMini firmware is designed to operate as follows:
BehaviorDetails
Heartbeat intervalEvery 8 seconds under normal conditions
Heartbeat backoffExponential backoff up to 30 seconds on consecutive failures
Button triggerBOOT button (GPIO 9) — fires on button release
Heartbeat pathGET /api/device/esp32/heartbeat
Button pathPOST /api/device/esp32/button
Authentication headerX-Device-Token matching ESP32_DEVICE_TOKEN env var

​
Admin endpoints

The following endpoints allow administrators to monitor and manage device state. They require standard Bearer token authentication (not X-Device-Token).

​
GET /api/admin/esp32/status

Returns the current ESP32 status without modifying any data. 
GET /api/admin/esp32/status
Authorization: Bearer <admin-token>

​
Response fields

​
connected
boolean
required
true when a heartbeat has been received within the last 15 seconds.
​
pressCount
number
required
Cumulative button press count since the last reset.
​
lastSeenAt
string | null
required
ISO 8601 datetime of the most recent heartbeat, or null if none recorded.

​
Example response

{
  "connected": false,
  "pressCount": 42,
  "lastSeenAt": "2024-07-16T14:32:10.000Z"
}

​
POST /api/admin/esp32/reset

Resets the cumulative pressCount to 0 and returns the updated device status. The lastSeenAt timestamp and connected state are not affected. 
POST /api/admin/esp32/reset
Authorization: Bearer <admin-token>

​
Example response

{
  "connected": false,
  "pressCount": 0,
  "lastSeenAt": "2024-07-16T14:32:10.000Z"
}

​
Admin code examples

curl --request GET \
  --url https://your-app.com/api/admin/esp32/status \
  --header "Authorization: Bearer <admin-token>"

​
Error responses

StatusMeaning
401Missing or invalid X-Device-Token (device routes) or Bearer token (admin routes).
500Unexpected server error while recording the event or reading status.

Build docs developers (and LLMs) love

Get started for freeTalk to us