Assets & Devices

This page explains how to work with Assets and Devices via REST API:

  • How we conceptually use assets vs devices

  • How to list, create, update, delete assets & devices

  • How to assign them to customers

  • How to link devices to assets (relations)

Prerequisites:

For all examples below:

  • Replace <BASE_URL> with the correct environment URL.

  • Replace <JWT_TOKEN> with a valid token in the header: X-Authorization: Bearer <JWT_TOKEN>


1. Assets vs Devices (Conceptual)

Asset

  • Represents logical or physical objects that are not sending telemetry directly.

  • Examples (adapt to our setup):

    • Buildings, sites, floors, rooms

    • Generators, tanks, solar panels

Device

  • Represents an IoT endpoint that sends/receives data:

    • Meters, sensors, controllers, gateways.

  • Devices are typically the source of telemetry.

Typical pattern in our usage (recommended):

  • Use Assets for:

    • Sites / locations / equipment “containers”

    • Business-level entities we show in dashboards (e.g. “Site A – Generator 1”)

  • Use Devices for:

    • Physical devices that connect via MQTT/HTTP/CoAP or gateway integrations

  • Connect them via relations (e.g. Asset “Generator 1” → Device “Energy Meter 1”).


2. Common Conventions

  • All examples assume:


X-Authorization: Bearer <JWT_TOKEN>
Content-Type: application/json

  • IDs look like:

"id": { "id": "1b4b9e70-1234-11ef-8c55-0123456789ab", "entityType": "ASSET" }

  • “List” endpoints usually return a page structure:

{ "data": [ /* array of assets/devices */ ], "totalPages": 3, "totalElements": 57, "hasNext": true }


We will focus on the most commonly used endpoints.


3. Assets

3.1 Get Asset by ID

Endpoint

  • GET /api/asset/{assetId}

Example

curl -X GET "<BASE_URL>/api/asset/<ASSET_ID>" \ -H "X-Authorization: Bearer <JWT_TOKEN>"

Response (simplified)

{ "id": { "id": "1b4b9e70-1234-11ef-8c55-0123456789ab", "entityType": "ASSET" }, "tenantId": { "id": "..." }, "customerId": { "id": "..." }, "name": "Site A – Generator 1", "type": "GENERATOR", "label": "GEN-01", "additionalInfo": {"description": "Main generator at Site A"}, "assetProfileId": { "id": "..." } }


3.2 List Assets for a Customer

Endpoint

  • GET /api/customer/{customerId}/assets{?pageSize,page,type,textSearch,sortProperty,sortOrder}

Example

curl -X GET "<BASE_URL>/api/customer/<CUSTOMER_ID>/assets?pageSize=50&page=0" \ -H "X-Authorization: Bearer <JWT_TOKEN>"

Useful when:

  • You are a customer user and want “my” assets (using your own customerId).


3.3 Create an Asset

Endpoint

  • POST /api/asset{?entityGroupId,entityGroupIds}

Body (minimal example)

{ "name": "Site A – Generator 1", "type": "GENERATOR", "label": "GEN-01" }

Example

curl -X POST "<BASE_URL>/api/asset" \ -H "Content-Type: application/json" \ -H "X-Authorization: Bearer <JWT_TOKEN>" \ -d '{ "name": "Site A – Generator 1", "type": "GENERATOR", "label": "GEN-01" }'

Notes

  • type should follow our internal naming convention (e.g. SITE, GENERATOR, TANK).

  • Optionally include:

    • assetProfileId – to link to a specific asset profile.

    • additionalInfo – for custom metadata.


3.4 Update an Asset

To update, send **POST /api/asset** with the asset’s id included in the body.

Example

curl -X POST "<BASE_URL>/api/asset" \ -H "Content-Type: application/json" \ -H "X-Authorization: Bearer <JWT_TOKEN>" \ -d '{ "id": { "id": "<ASSET_ID>", "entityType": "ASSET" }, "name": "Site A – Generator 1 (Updated)", "type": "GENERATOR", "label": "GEN-01", "additionalInfo": { "description": "Updated description" } }'

The api will detect that an id is present and treat this as an update.


3.5 Delete an Asset

Endpoint

  • DELETE /api/asset/{assetId}

Example

curl -X DELETE "<BASE_URL>/api/asset/<ASSET_ID>" \ -H "X-Authorization: Bearer <JWT_TOKEN>"

Be careful: this is permanent and may affect dashboards, alarms, and relations.


3.6 Assign Asset to a new Customer

Overview

Assets can be assigned to customers to make them visible to users under that customer account. Tenant Administrators always retain visibility and access regardless of assignment.


Assign Asset to a Customer

Endpoint

POST /api/asset{?entityGroupId,entityGroupIds}

Description

Assigns or reassigns an asset to a specific customer. The customerId is provided in the request body rather than in the URL.

Request Body Example

{ "id": {"entityType": "ASSET", "id": "..." }, "customerId": { "entityType": "CUSTOMER", "id": "..." } }

CURL Example

curl -X POST "<BASE_URL>/api/asset" \ -H "Content-Type: application/json" \ -H "X-Authorization: Bearer <JWT_TOKEN>" \ -d '{ "id": { "entityType": "ASSET", "id": "..." }, "customerId": { "entityType": "CUSTOMER", "id": "..." } }'

Optional Query Parameters

  • entityGroupId — (UUID) Assign the asset to a specific entity group.

  • entityGroupIds — (Comma-separated UUIDs) Assign to multiple groups.

Response Example

{ "id": { "entityType": "ASSET", "id": "..." }, "createdTime": 1763561138539, "tenantId": { "entityType": "TENANT", "id": "..." }, "customerId": { "entityType": "CUSTOMER", "id": "..." }, "name": "Empire State Building", "type": "Building", "label": "NY Building", "assetProfileId": { "entityType": "ASSET_PROFILE", "id": "..." }, "ownerId": { "entityType": "TENANT", "id": "..." } }

Notes

  • Once assigned, the asset becomes visible and manageable by users under that customer.

  • Tenant administrators continue to have full access.

  • The ownerId remains the tenant even after assignment.


4. Devices

4.1 Get Device by ID

Endpoint

  • GET /api/device/{deviceId}

Example

curl -X GET "<BASE_URL>/api/device/<DEVICE_ID>" \ -H "X-Authorization: Bearer <JWT_TOKEN>"

Response (simplified)

{ "id": { "id": "...", "entityType": "DEVICE" }, "tenantId": { "id": "..." }, "customerId": { "id": "..." }, "name": "GEN-01 Energy Meter", "type": "ENERGY_METER", "label": "EM-GEN-01", "deviceProfileId": { "id": "..." }, "additionalInfo": { } }


4.2 List Devices for a Customer

Endpoint

  • GET /api/customer/{customerId}/devices{?pageSize,page,type,textSearch,sortProperty,sortOrder}

Example

curl -X GET "<BASE_URL>/api/customer/<CUSTOMER_ID>/devices?pageSize=50&page=0" \ -H "X-Authorization: Bearer <JWT_TOKEN>"


4.3 Create a Device

Endpoint

  • POST /api/device

Body (minimal example)

{ "name": "GEN-01 Energy Meter", "type": "ENERGY_METER", "label": "EM-GEN-01" }

Example

curl -X POST "<BASE_URL>/api/device" \ -H "Content-Type: application/json" \ -H "X-Authorization: Bearer <JWT_TOKEN>" \ -d '{ "name": "GEN-01 Energy Meter", "type": "ENERGY_METER", "label": "EM-GEN-01" }'

Notes

  • type is used to select the device profile (depending on TB configuration).

  • In our environment, we typically align type with the configured device profile name (e.g. "10_IOTPRO-Generator ", "2_IOTPRO-Temperature " ) – adjust as needed.


4.4 Update a Device

Same as with assets: send POST /api/device with id included.

curl -X POST "<BASE_URL>/api/device" \ -H "Content-Type: application/json" \ -H "X-Authorization: Bearer <JWT_TOKEN>" \ -d '{ "id": { "id": "<DEVICE_ID>", "entityType": "DEVICE" }, "name": "GEN-01 Energy Meter (Updated)", "type": "ENERGY_METER", "label": "EM-GEN-01", "additionalInfo": {"panel": "Main LV Room"} }'


4.5 Delete a Device

Endpoint

  • DELETE /api/device/{deviceId}

Example

curl -X DELETE "<BASE_URL>/api/device/<DEVICE_ID>" \ -H "X-Authorization: Bearer <JWT_TOKEN>"


4.6 Device Credentials

Device credentials (tokens, etc.) are managed via additional endpoints (e.g. GET /api/device/credentials/{deviceId}, POST /api/device/credentials).

These are typically used when:

  • You provision devices that connect directly using an access token.

  • You rotate credentials or migrate devices.


5. Linking Devices to Assets (Relations)

Assets and devices themselves do not have built-in parent/child fields. Instead, we use relations to link them.

5.1 Example Relation: Asset “Contains” Device

We typically model:

  • Originator: Asset (e.g. “Generator 1”)

  • Endpoint: Device (e.g. “Generator 1 – Energy Meter”)

  • Type: "Contains"

Endpoint

  • POST /api/relation

Body (example)

{ "from": { "id": "<ASSET_ID>", "entityType": "ASSET" }, "to": { "id": "<DEVICE_ID>", "entityType": "DEVICE" }, "type": "Contains", "typeGroup": "COMMON" }

Example

curl -X POST "<BASE_URL>/api/relation" \ -H "Content-Type: application/json" \ -H "X-Authorization: Bearer <JWT_TOKEN>" \ -d '{ "from": {"id": "<ASSET_ID>","entityType": "ASSET"}, "to": {"id": "<DEVICE_ID>","entityType": "DEVICE"}, "type": "Contains","typeGroup": "COMMON"   }'

Notes

  • Once a relationship is created incoming data from the device will also start to be saved on the asset.