Connected Workers Sensors

The Connected Workers Sensors API lets you register the sensors behind your Operations dashboards and push their readings over REST — the same path the built‑in MQTT bridge and scheduled polls use. Everything you send is persisted, evaluated against your alert rules, and rolled up into asset health identically to connector‑sourced data.

• Sensor — a device that reports readings. Identified by an externalDeviceId (your source‑system id). That same value is the sensorRef you use when pushing data.
• Reading — one timestamped measurement for a sensor (value for numbers, valueText for strings, plus an optional unit).
• Binding — an optional link from a sensor to a Connected Workers asset (cwAssetId). Binding is what makes a reading spatial — it flows into that asset's health rollup. Tag and location are derived from the asset.

Workspace 7
└── Sensor 42  (externalDeviceId: "pump-a-temp")  →  bound to asset row 1001
      └── Readings (append‑only, newest first):
            { ts: "2026‑07‑08T09:00:00Z", value: 71.4, unit: "°C" }
            { ts: "2026‑07‑08T09:01:00Z", value: 73.9, unit: "°C" }

Sensors register automatically on first data — you do not have to create a sensor before pushing readings for it. Use the create/update/delete endpoints when you want to manage them explicitly (name them, bind them to an asset, or remove them).

Base URL & auth

Every endpoint is scoped to a workspace and served under:

https://api.treedis.com/v2/api/workspaces/{workspaceId}/operations

All endpoints require authentication (OAuth2 Bearer token or X-API-Key), and the caller must have access to the workspace. Generate OAuth credentials in the Treedis admin under Settings → General → Advanced.

Endpoints

Sensors

List

GET /v2/api/workspaces/{workspaceId}/operations/sensors — every sensor with its binding state and cached last value.

curl "https://api.treedis.com/v2/api/workspaces/7/operations/sensors" \
  -H "Authorization: Bearer your-access-token"

Register

POST /v2/api/workspaces/{workspaceId}/operations/sensors

curl -X POST "https://api.treedis.com/v2/api/workspaces/7/operations/sensors" \
  -H "Authorization: Bearer your-access-token" \
  -H "Content-Type: application/json" \
  -d '{ "externalDeviceId": "pump-a-temp", "name": "Pump A — temperature", "cwAssetId": 1001 }'

{
  "success": true, "code": 200, "message": "Success",
  "data": {
    "sensor": {
      "id": 42, "externalDeviceId": "pump-a-temp", "name": "Pump A — temperature",
      "status": "unknown", "cwAssetId": 1001, "assetName": "Centrifugal Pump"
    }
  }
}

Registering an externalDeviceId that already exists returns 400.

Update

PATCH /v2/api/workspaces/{workspaceId}/operations/sensors/{sensorId} — send only the fields you want to change.

curl -X PATCH "https://api.treedis.com/v2/api/workspaces/7/operations/sensors/42" \
  -H "Authorization: Bearer your-access-token" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Pump A — inlet temp", "cwAssetId": null }'

Delete

DELETE /v2/api/workspaces/{workspaceId}/operations/sensors/{sensorId} — removes the sensor and its readings. Sensor‑targeted alert rules are removed too; already‑fired alerts keep their history.

curl -X DELETE "https://api.treedis.com/v2/api/workspaces/7/operations/sensors/42" \
  -H "Authorization: Bearer your-access-token"

Push readings (data)

POST /v2/api/workspaces/{workspaceId}/operations/sensors/readings is the REST counterpart of the MQTT bridge. It runs through the single ingest path, so readings are stored, unknown sensors auto‑register, thresholds evaluate and asset state rolls up exactly as for connector data.

curl -X POST "https://api.treedis.com/v2/api/workspaces/7/operations/sensors/readings" \
  -H "Authorization: Bearer your-access-token" \
  -H "Content-Type: application/json" \
  -d '{
    "sensors": [ { "ref": "pump-a-temp", "name": "Pump A — temperature", "unit": "°C" } ],
    "readings": [
      { "sensorRef": "pump-a-temp", "ts": "2026-07-08T09:00:00Z", "value": 71.4, "unit": "°C" },
      { "sensorRef": "pump-a-temp", "ts": "2026-07-08T09:01:00Z", "value": 73.9, "unit": "°C" }
    ]
  }'

The response summarises what the batch did:

{
  "success": true, "code": 200, "message": "Success",
  "data": {
    "readingsStored": 2, "sensorsRegistered": 0,
    "alertsOpened": 1, "alertsResolved": 0, "touchedAssetIds": [1001]
  }
}

Pushing is idempotent on (sensorRef, ts) — re‑sending the same timestamped points silently skips duplicates, so a client can safely retry a batch.

Reading data back

GET /v2/api/workspaces/{workspaceId}/operations/assets/{rowId}/readings returns the last 24 hours of readings for every sensor bound to an asset (add ?downsample=1 for bucketed avg/min/max series).

Errors

Errors use the standard envelope with success: false:

{ "success": false, "code": 400, "message": "A sensor with this externalDeviceId already exists" }

See the Connected Workers Sensors tag in the API Reference for the full request and response schemas, and the Alerts guide for defining threshold rules on these sensors.