Create or Update Device

POST

api

ext-v1

device

curl -X POST https://admin.telemetron.ai/api/ext-v1/device \
  -H "Content-Type: application/json" \
  -H "x-api-key: your-api-key" \
  -d '{
    "identifier": "sensor-001",
    "type": "sensor",
    "properties": {
      "location": "Building A",
      "firmware": "v2.1.0",
      "model": "TM-500"
    }
  }'

const response = await fetch("https://admin.telemetron.ai/api/ext-v1/device", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "x-api-key": "your-api-key",
  },
  body: JSON.stringify({
    identifier: "sensor-001",
    type: "sensor",
    properties: {
      location: "Building A",
      firmware: "v2.1.0",
      model: "TM-500",
    },
  }),
});

const data = await response.json();
console.log(data);

import requests

response = requests.post(
    "https://admin.telemetron.ai/api/ext-v1/device",
    headers={
        "Content-Type": "application/json",
        "x-api-key": "your-api-key",
    },
    json={
        "identifier": "sensor-001",
        "type": "sensor",
        "properties": {
            "location": "Building A",
            "firmware": "v2.1.0",
            "model": "TM-500",
        },
    },
)

print(response.json())

{
  "success": true,
  "message": "Device created successfully",
  "deviceId": "dev_abc123",
  "identifier": "sensor-001",
  "type": "sensor"
}

{
  "success": true,
  "message": "Device updated successfully",
  "deviceId": "dev_abc123",
  "identifier": "sensor-001",
  "type": "sensor"
}

{
  "error": "identifier is required and must be a non-empty string"
}

{
  "error": "type is required for new devices and must be a non-empty string"
}

{
  "error": "Missing API key"
}

{
  "error": "Invalid API key"
}

{
  "error": "Invalid JSON payload"
}

Overview

This endpoint allows you to create a new device or update an existing one using its unique identifier. When a device with the given identifier already exists, the provided fields will be updated. When no device exists with that identifier, a new device is created.

New devices require both identifier and type.
Existing devices can be updated by providing identifier along with any fields to change (type, properties).

Authentication

x-api-key

string

required

Your organization’s API key

Request Body

identifier

string

required

A unique identifier for the device. Must be a non-empty string.

type

string

The device type (e.g., "sensor", "gateway", "controller"). Required when creating a new device. Optional when updating an existing device.

properties

object

Optional metadata object containing additional device properties.

Response

success

boolean

Indicates whether the operation was successful.

message

string

A human-readable message describing the result.

deviceId

string

The unique ID of the created or updated device.

identifier

string

The identifier of the device.

type

string | null

The device type.

Examples

Create a New Device

curl -X POST https://admin.telemetron.ai/api/ext-v1/device \
  -H "Content-Type: application/json" \
  -H "x-api-key: your-api-key" \
  -d '{
    "identifier": "sensor-001",
    "type": "sensor",
    "properties": {
      "location": "Building A",
      "firmware": "v2.1.0",
      "model": "TM-500"
    }
  }'

const response = await fetch("https://admin.telemetron.ai/api/ext-v1/device", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "x-api-key": "your-api-key",
  },
  body: JSON.stringify({
    identifier: "sensor-001",
    type: "sensor",
    properties: {
      location: "Building A",
      firmware: "v2.1.0",
      model: "TM-500",
    },
  }),
});

const data = await response.json();
console.log(data);

import requests

response = requests.post(
    "https://admin.telemetron.ai/api/ext-v1/device",
    headers={
        "Content-Type": "application/json",
        "x-api-key": "your-api-key",
    },
    json={
        "identifier": "sensor-001",
        "type": "sensor",
        "properties": {
            "location": "Building A",
            "firmware": "v2.1.0",
            "model": "TM-500",
        },
    },
)

print(response.json())

curl -X POST https://admin.telemetron.ai/api/ext-v1/device \
  -H "Content-Type: application/json" \
  -H "x-api-key: your-api-key" \
  -d '{
    "identifier": "sensor-001",
    "type": "sensor",
    "properties": {
      "location": "Building A",
      "firmware": "v2.1.0",
      "model": "TM-500"
    }
  }'

const response = await fetch("https://admin.telemetron.ai/api/ext-v1/device", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "x-api-key": "your-api-key",
  },
  body: JSON.stringify({
    identifier: "sensor-001",
    type: "sensor",
    properties: {
      location: "Building A",
      firmware: "v2.1.0",
      model: "TM-500",
    },
  }),
});

const data = await response.json();
console.log(data);

import requests

response = requests.post(
    "https://admin.telemetron.ai/api/ext-v1/device",
    headers={
        "Content-Type": "application/json",
        "x-api-key": "your-api-key",
    },
    json={
        "identifier": "sensor-001",
        "type": "sensor",
        "properties": {
            "location": "Building A",
            "firmware": "v2.1.0",
            "model": "TM-500",
        },
    },
)

print(response.json())

Update an Existing Device

curl -X POST https://admin.telemetron.ai/api/ext-v1/device \
  -H "Content-Type: application/json" \
  -H "x-api-key: your-api-key" \
  -d '{
    "identifier": "sensor-001",
    "properties": {
      "location": "Building B",
      "firmware": "v2.2.0"
    }
  }'

const response = await fetch("https://admin.telemetron.ai/api/ext-v1/device", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "x-api-key": "your-api-key",
  },
  body: JSON.stringify({
    identifier: "sensor-001",
    properties: {
      location: "Building B",
      firmware: "v2.2.0",
    },
  }),
});

const data = await response.json();
console.log(data);

import requests

response = requests.post(
    "https://admin.telemetron.ai/api/ext-v1/device",
    headers={
        "Content-Type": "application/json",
        "x-api-key": "your-api-key",
    },
    json={
        "identifier": "sensor-001",
        "properties": {
            "location": "Building B",
            "firmware": "v2.2.0",
        },
    },
)

print(response.json())

curl -X POST https://admin.telemetron.ai/api/ext-v1/device \
  -H "Content-Type: application/json" \
  -H "x-api-key: your-api-key" \
  -d '{
    "identifier": "sensor-001",
    "properties": {
      "location": "Building B",
      "firmware": "v2.2.0"
    }
  }'

const response = await fetch("https://admin.telemetron.ai/api/ext-v1/device", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "x-api-key": "your-api-key",
  },
  body: JSON.stringify({
    identifier: "sensor-001",
    properties: {
      location: "Building B",
      firmware: "v2.2.0",
    },
  }),
});

const data = await response.json();
console.log(data);

import requests

response = requests.post(
    "https://admin.telemetron.ai/api/ext-v1/device",
    headers={
        "Content-Type": "application/json",
        "x-api-key": "your-api-key",
    },
    json={
        "identifier": "sensor-001",
        "properties": {
            "location": "Building B",
            "firmware": "v2.2.0",
        },
    },
)

print(response.json())

Response

{
  "success": true,
  "message": "Device created successfully",
  "deviceId": "dev_abc123",
  "identifier": "sensor-001",
  "type": "sensor"
}

{
  "success": true,
  "message": "Device updated successfully",
  "deviceId": "dev_abc123",
  "identifier": "sensor-001",
  "type": "sensor"
}

{
  "error": "identifier is required and must be a non-empty string"
}

{
  "error": "type is required for new devices and must be a non-empty string"
}

{
  "success": true,
  "message": "Device created successfully",
  "deviceId": "dev_abc123",
  "identifier": "sensor-001",
  "type": "sensor"
}

{
  "success": true,
  "message": "Device updated successfully",
  "deviceId": "dev_abc123",
  "identifier": "sensor-001",
  "type": "sensor"
}

{
  "error": "identifier is required and must be a non-empty string"
}

{
  "error": "type is required for new devices and must be a non-empty string"
}

{
  "error": "Missing API key"
}

{
  "error": "Invalid API key"
}

{
  "error": "Invalid JSON payload"
}

Status Codes

Code	Description
200	Device successfully created or updated
400	Validation error (missing or invalid fields, invalid JSON)
401	Authentication error (missing or invalid API key)
500	Internal server error

Bulk Update Device MetadataBulk-update the deviceMetadata (properties) for multiple devices in a single request, identified by their serial/identifier

curl -X POST https://admin.telemetron.ai/api/ext-v1/device \
  -H "Content-Type: application/json" \
  -H "x-api-key: your-api-key" \
  -d '{
    "identifier": "sensor-001",
    "type": "sensor",
    "properties": {
      "location": "Building A",
      "firmware": "v2.1.0",
      "model": "TM-500"
    }
  }'

const response = await fetch("https://admin.telemetron.ai/api/ext-v1/device", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "x-api-key": "your-api-key",
  },
  body: JSON.stringify({
    identifier: "sensor-001",
    type: "sensor",
    properties: {
      location: "Building A",
      firmware: "v2.1.0",
      model: "TM-500",
    },
  }),
});

const data = await response.json();
console.log(data);

import requests

response = requests.post(
    "https://admin.telemetron.ai/api/ext-v1/device",
    headers={
        "Content-Type": "application/json",
        "x-api-key": "your-api-key",
    },
    json={
        "identifier": "sensor-001",
        "type": "sensor",
        "properties": {
            "location": "Building A",
            "firmware": "v2.1.0",
            "model": "TM-500",
        },
    },
)

print(response.json())

{
  "success": true,
  "message": "Device created successfully",
  "deviceId": "dev_abc123",
  "identifier": "sensor-001",
  "type": "sensor"
}

{
  "success": true,
  "message": "Device updated successfully",
  "deviceId": "dev_abc123",
  "identifier": "sensor-001",
  "type": "sensor"
}

{
  "error": "identifier is required and must be a non-empty string"
}

{
  "error": "type is required for new devices and must be a non-empty string"
}

{
  "error": "Missing API key"
}

{
  "error": "Invalid API key"
}

{
  "error": "Invalid JSON payload"
}

​Overview

​Authentication

​Request Body

​Response

​Examples

​Create a New Device

​Update an Existing Device

​Response

​Status Codes

Overview

Authentication

Request Body

Response

Examples

Create a New Device

Update an Existing Device

Response

Status Codes