Device Management

Create, update, delete, and list devices from your application.

Access via app.device.

API

create()

Register a new device and receive its credentials.

JavaScript

await app.device.create(params)

Python

await app.device.create(params)

Parameter	Type	Description
ident	string	Unique device identifier
schema	object	Defines the telemetry metrics — each key is a metric name with type, unit, and unit_symbol
config	object	Initial device configuration

Returns the created device object (including credentials for the Device SDK)

Naming rules

Device identifiers can only contain letters, numbers, hyphens, and underscores (A-Z, a-z, 0-9, -, _).

JavaScript

const device = await app.device.create({
  ident: "sensor_01",
  schema: {
    temperature: { type: "number", unit: "Celsius", unit_symbol: "°C" },
    humidity: { type: "number", unit: "Percent", unit_symbol: "%" },
    status: { type: "string", unit: "Status", unit_symbol: "" },
  },
  config: {
    reportInterval: 5000,
    location: "warehouse-A",
  },
});

// device.creds contains the api_key and secret
// for initializing the Device SDK
console.log("Device created:", device.ident);

Python

device = await app.device.create({
    "ident": "sensor_01",
    "schema": {
        "temperature": {"type": "number", "unit": "Celsius", "unit_symbol": "°C"},
        "humidity": {"type": "number", "unit": "Percent", "unit_symbol": "%"},
        "status": {"type": "string", "unit": "Status", "unit_symbol": ""},
    },
    "config": {
        "reportInterval": 5000,
        "location": "warehouse-A",
    },
})

# device["creds"] contains the api_key and secret
# for initializing the Device SDK
print("Device created:", device["ident"])

Example response:

{
  "id": "69ca39e4ed4d9fe786145b48",
  "ident": "sensor_01",
  "schema": {
    "temperature": { "type": "number", "unit": "Celsius", "unit_symbol": "°C" },
    "humidity": { "type": "number", "unit": "Percent", "unit_symbol": "%" },
    "status": { "type": "string", "unit": "Status", "unit_symbol": "" }
  },
  "config": {
    "reportInterval": 5000,
    "location": "warehouse-A"
  },
  "creds": {
    "api_key": "eyJ0eXAiOiJKV1Qi...",
    "secret": "SUAO6FXS2MMQMZ6U..."
  }
}

Store your credentials

The creds field is only returned on create() and is not saved on the backend. Store creds.api_key and creds.secret securely — you'll need them to initialize the Device SDK and they cannot be retrieved again.

Device limit

The number of devices you can create depends on your plan.

update()

Update a device's identifier, schema, or configuration.

JavaScript

await app.device.update(params)

Python

await app.device.update(params)

Parameter	Type	Description
id	string	The device ID (from the device object)
ident	string	(optional) New device identifier
schema	object	(optional) Updated schema
config	object	(optional) Updated configuration

Returns the updated device object

JavaScript

const updated = await app.device.update({
  id: device.id,
  config: {
    reportInterval: 10000,
    location: "warehouse-B",
  },
});

Python

updated = await app.device.update({
    "id": device["id"],
    "config": {
        "reportInterval": 10000,
        "location": "warehouse-B",
    },
})

Example response:

{
  "id": "69ca39e4ed4d9fe786145b48",
  "ident": "sensor_01",
  "schema": {
    "temperature": { "type": "number", "unit": "Celsius", "unit_symbol": "°C" },
    "humidity": { "type": "number", "unit": "Percent", "unit_symbol": "%" }
  },
  "config": { "reportInterval": 10000, "location": "warehouse-B" }
}

delete()

Permanently remove a device and its credentials.

JavaScript

await app.device.delete(ident)

Python

await app.device.delete(ident)

Parameter	Type	Description
ident	string	The device identifier to delete

Returns true if deleted successfully

JavaScript

const deleted = await app.device.delete("sensor_01");
console.log(deleted ? "Deleted" : "Failed");

Python

deleted = await app.device.delete("sensor_01")
print("Deleted" if deleted else "Failed")

list()

Retrieve all devices in your organization.

JavaScript

await app.device.list()

Python

await app.device.list()

Returns an array of all device objects

JavaScript

const devices = await app.device.list();

devices.forEach((device) => {
  console.log(`${device.ident} — ${JSON.stringify(device.schema)}`);
});

Python

devices = await app.device.list()

for device in devices:
    print(f"{device['ident']} — {device['schema']}")

Example response:

[
  {
    "id": "69ca39e4ed4d9fe786145b48",
    "ident": "sensor_01",
    "schema": {
      "temperature": { "type": "number", "unit": "Celsius", "unit_symbol": "°C" },
      "humidity": { "type": "number", "unit": "Percent", "unit_symbol": "%" }
    },
    "config": { "reportInterval": 5000 }
  },
  {
    "id": "69ca3a12ed4d9fe786145b49",
    "ident": "sensor_02",
    "schema": {
      "pressure": { "type": "number", "unit": "Pascal", "unit_symbol": "Pa" }
    },
    "config": {}
  }
]

get()

Retrieve a single device by its identifier.

JavaScript

await app.device.get(params)

Python

await app.device.get(params)

Parameter	Type	Description
ident	string	The device identifier to look up

Returns the device object

JavaScript

const device = await app.device.get({ ident: "sensor_01" });
console.log("Schema:", device.schema);
console.log("Config:", device.config);

Python

device = await app.device.get({"ident": "sensor_01"})
print("Schema:", device["schema"])
print("Config:", device["config"])

Example response:

{
  "id": "69ca39e4ed4d9fe786145b48",
  "ident": "sensor_01",
  "schema": {
    "temperature": { "type": "number", "unit": "Celsius", "unit_symbol": "°C" },
    "humidity": { "type": "number", "unit": "Percent", "unit_symbol": "%" }
  },
  "config": { "reportInterval": 5000, "location": "warehouse-A" }
}

Schema Structure

Each metric in the schema is an object with three fields:

Field	Type	Description
type	string	The data type: "number", "string", "boolean", or "json"
unit	string	Human-readable unit name (e.g., "Celsius", "Percent")
unit_symbol	string	Unit symbol for display (e.g., "°C", "%")

Supported Types

Type	Description
"number"	Integer or floating-point values
"string"	Text values
"boolean"	true / false
"json"	Objects and arrays

Device Caching

The SDK maintains a local cache of devices that is populated on connect(). The cache has a 2-hour TTL and is automatically updated when you call create(), update(), or delete(). This means list() and get() are fast for repeated calls.