API Reference

The HTTP and MQTT endpoints of the IncludeApps platform, for custom devices (BYOD) and third-party applications. The authoritative contract is the backend code - this document is kept in step with it, but tell our team if you find a difference.

Conventions

• Base URL: https://app.include.co.id/api/v1
• Authentication: almost every route needs Authorization: Bearer <access_token> (except /auth/*, /health, /public/* and /device/*).
• Success response: { data, meta } - meta carries pagination (page/limit/total) where it applies.
• Error response: { error, message }.
• Scoping: almost all data carries a group_id (a Group inside your Organisation).

Auth

Method	Path	Purpose
POST	/auth/register	Register a user and a new organisation
POST	/auth/login	Sign in; returns an access and refresh token
POST	/auth/refresh	Renew the access token
POST	/auth/logout	Invalidate the refresh token
POST	/auth/forgot-password	Send a password-reset email
POST	/auth/reset-password	Reset the password with a token
GET	/auth/google	Sign in with Google (OAuth redirect)

Devices

Method	Path	Purpose
POST	/devices/claim	Claim a device by Device ID / token
POST	/devices/custom	Register a custom or BYOD device yourself
GET	/devices	List devices (filter by solution/status/zone)
GET	/devices/:id	Device detail
PATCH	/devices/:id	Change a device (name, zone, calibration)
DELETE	/devices/:id	Delete a device
POST	/devices/:id/command	Send an actuator command (publishes over MQTT)

Telemetry

Method	Path	Purpose
GET	/telemetry/:deviceId	Latest values
GET	/telemetry/:deviceId/history	History (startTime, endTime, limit)
POST	/telemetry/:deviceId/import	Import history (Pro+; imported history raises no alarms)

Real time: Server-Sent Events at /telemetry/stream (not WebSocket).

Alarms

Method	Path	Purpose
GET	/alarms	List alarms (filter by status/severity)
PATCH	/alarms/:id/acknowledge	Acknowledge
PATCH	/alarms/:id/resolve	Resolve
POST	/devices/:id/thresholds	Set thresholds (optimal/warning/critical) per parameter

Dashboards

Method	Path	Purpose
GET	/dashboards/:id	Detail (including the widget layout)
PATCH	/dashboards/:id	Save the layout / widgets

Rule chains

A per-Organisation automation graph that runs on every incoming telemetry frame - declarative nodes (filter/switch/transform) plus a sandboxed JavaScript scripting node for custom logic.

Method	Path	Purpose
GET	/rule-chains	List chains
POST	/rule-chains	Create a chain
PUT	/rule-chains/:id	Change the graph
POST	/rule-chains/test	Dry-run the graph over sample values

Device API (device token)

Used by IncludeBox firmware and by custom/BYOD devices - authenticated with a device token (not a user JWT), in a header or in the URL.

Method	Path	Purpose
POST	/device/telemetry	Publish telemetry (token in the X-Device-Token header)
POST	/{token}/telemetry	Publish telemetry with the token in the URL (ThingsBoard style - works straight from curl)
GET	/{token}/mqtt-config	Fetch the MQTT bootstrap configuration (host, port, topic)
GET	/device/ota	Poll for OTA commands

MQTT

An EMQX broker. Topic convention:

includeapps/{group_id}/{solution_slug}/{device_id}/{telemetry|command|status}

• The backend subscribes to includeapps/+/+/+/telemetry, validates the payload, stores it in TimescaleDB, evaluates alarms and rule chains, then broadcasts to every open dashboard - all within seconds.
• Authentication: deviceId as the MQTT username, the device token as the password.
• command carries actuator control and OTA commands.

Example telemetry payloads

Single-phase energy meter:

{
  "values": {
    "voltage": 220.5,
    "current": 2.1,
    "power": 462.3,
    "energy": 145.2,
    "frequency": 50.0,
    "power_factor": 0.95
  }
}

Three-phase energy meter:

{
  "values": {
    "voltage_r": 221.0,
    "voltage_s": 219.8,
    "voltage_t": 220.5,
    "current_r": 5.2,
    "current_s": 5.0,
    "current_t": 5.1,
    "total_power": 3350.0,
    "energy": 890.4,
    "frequency": 50.0,
    "power_factor": 0.92
  }
}

The accepted fields follow the device type (device_type_key) registered for that device - see Manage Devices in the app for the full parameter list per type.