Managing devices & variables

A device is a data source — a reefer tracker, a cold-room logger, a gateway. Each device owns variables, the individual time-series channels it reports (temperature, humidity, battery, position…). Both are managed through the Platform API (base URL https://api.surfact.com/api/v2.0/).

📘

Device, event and device group paths accept either the object id or a ~label, because those labels are unique account-wide. Variables are the exception: a variable label is unique only within its device, so a variable can be addressed by label only when nested under that device — /devices/{device_key}/variables/~{label}/. See Identifiers — Key vs. ID.

List your devices

curl -X GET 'https://api.surfact.com/api/v2.0/devices/' \
  -H 'X-Auth-Token: your_token_here'

Narrow the list with field filters, sorting and pagination — see Working with the API.

Update a device

PATCH changes only the fields you send. Re-point a reefer to a new route without touching anything else:

curl -X PATCH 'https://api.surfact.com/api/v2.0/devices/~reefer-no-4417/' \
  -H 'Content-Type: application/json' \
  -H 'X-Auth-Token: your_token_here' \
  -d '{ "properties": { "destination": "Bergen Cold Hub", "max-temp-threshold": "-15" } }'

The properties object holds free-form metadata — the hardware serial, a route's temperature limits, the device's location settings, and anything else you want to carry alongside the device.

❗️

Objects merge, arrays replace

properties is merged: the example above sets two keys and leaves every other property on the device untouched. tags is an array, so it is replaced wholesale — sending {"tags": ["pharma"]} on a device tagged ["reefer", "frozen"] leaves it tagged only ["pharma"]. To add a tag, send the full list you want the device to end up with.

Inspect a device's variables

Each device exposes its channels under /devices/{device_id}/variables/:

curl -X GET 'https://api.surfact.com/api/v2.0/devices/~reefer-no-4417/variables/' \
  -H 'X-Auth-Token: your_token_here'

To read the most recent reading of a single variable:

curl -X GET 'https://api.surfact.com/api/v2.0/variables/<variable_id>/' \
  -H 'X-Auth-Token: your_token_here'

/variables/ takes the variable id only. To reach the same variable by label, go through its device:

curl -X GET 'https://api.surfact.com/api/v2.0/devices/~reefer-no-4417/variables/~temperature/' \
  -H 'X-Auth-Token: your_token_here'

A ~label sent to the top-level path is rejected — GET /api/v2.0/variables/~temperature returns 400:

{ "code": 400001, "message": "Validation Error.", "detail": ["Label key is not allowed: `~temperature`"] }

That is because temperature is not unique across the account — every reefer in the fleet has a variable with that label — so the device is what makes the label unambiguous.

For the full time series behind a variable — raw dots, aggregates and multi-variable queries — see Working with Device Data.