Bulk Update Device Metadata

POST

api

ext-v1

device

bulk-metadata

curl -X POST https://admin.telemetron.ai/api/ext-v1/device/bulk-metadata \
  -H "x-api-key: tlm_xxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "devices": {
      "SN-A100": { "firmwareVersion": "3.2.1", "status": "active", "location": "Building A" },
      "SN-B200": { "firmwareVersion": "3.2.1", "status": "maintenance" },
      "SN-UNKNOWN": { "status": "active" }
    }
  }'

const response = await fetch("https://admin.telemetron.ai/api/ext-v1/device/bulk-metadata", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "x-api-key": "tlm_xxxxxxxxxxxx",
  },
  body: JSON.stringify({
    devices: {
      "SN-A100": { firmwareVersion: "3.2.1", status: "active", location: "Building A" },
      "SN-B200": { firmwareVersion: "3.2.1", status: "maintenance" },
      "SN-UNKNOWN": { status: "active" },
    },
  }),
});

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

import requests

response = requests.post(
    "https://admin.telemetron.ai/api/ext-v1/device/bulk-metadata",
    headers={
        "Content-Type": "application/json",
        "x-api-key": "tlm_xxxxxxxxxxxx",
    },
    json={
        "devices": {
            "SN-A100": {"firmwareVersion": "3.2.1", "status": "active", "location": "Building A"},
            "SN-B200": {"firmwareVersion": "3.2.1", "status": "maintenance"},
            "SN-UNKNOWN": {"status": "active"},
        }
    },
)

print(response.json())

{
  "success": true,
  "updated": 2,
  "notFound": 1,
  "results": [
    { "identifier": "SN-A100", "deviceId": "d1a2b3c4-...", "status": "updated" },
    { "identifier": "SN-B200", "deviceId": "e5f6a7b8-...", "status": "updated" },
    { "identifier": "SN-UNKNOWN", "deviceId": "", "status": "not_found" }
  ]
}

{
  "error": "devices is required and must be an object mapping identifiers to metadata"
}

{
  "error": "Missing API key"
}

{
  "error": "Internal server error"
}

Overview

This endpoint allows you to update the metadata (properties) for up to 1,000 devices in a single request. Devices are identified by their serial/identifier and scoped to your organization via API key.

This performs a full replacement of deviceMetadata for each device — it does not merge with existing metadata. To preserve existing properties, the caller must include them in the payload.

Only existing devices are updated; no devices are created. Unrecognized identifiers are reported as not_found.
All matching devices are updated in a single SQL statement for efficiency.
updatedAt is set to the current time for all updated devices.

Authentication

string

required

Your organization’s API key

Request Body

Record<string, Record<string, unknown>>

required

Object mapping device identifiers (serials) to their new metadata properties. Each value must be a JSON object.

Constraints

devices must contain at least 1 entry
Maximum 1,000 devices per request
Each metadata value must be a JSON object (not null, array, or primitive)
Identifier keys are trimmed of leading/trailing whitespace before matching

Response

200 OK — Success

boolean

Always true on a 200 response.

number

Count of devices that were found and updated.

number

Count of identifiers that matched no device in the organization.

BulkMetadataResponseItem[]

Per-identifier result in the same order as the input keys.

BulkMetadataResponseItem

Field	Type	Description
`identifier`	`string`	The trimmed device identifier
`deviceId`	`string`	The device’s UUID if found, empty string if not found
`status`	`"updated"` \| `"not_found"`	Whether the device was updated or didn’t exist

400 Bad Request

{ "error": "<message>" }

Possible messages:

Message	Cause
`"Invalid JSON payload"`	Body is not valid JSON
`"devices is required and must be an object mapping identifiers to metadata"`	Missing or wrong type
`"devices must contain at least one entry"`	Empty object
`"Too many devices. Maximum 1000 per request"`	Exceeds limit
`"Invalid metadata for device \"<identifier>\": must be a JSON object"`	A metadata value is `null`, array, or primitive

401 Unauthorized

{ "error": "Missing API key" }

{ "error": "Invalid API key" }

500 Internal Server Error

{ "error": "Internal server error" }

Examples

curl -X POST https://admin.telemetron.ai/api/ext-v1/device/bulk-metadata \
  -H "x-api-key: tlm_xxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "devices": {
      "SN-A100": { "firmwareVersion": "3.2.1", "status": "active", "location": "Building A" },
      "SN-B200": { "firmwareVersion": "3.2.1", "status": "maintenance" },
      "SN-UNKNOWN": { "status": "active" }
    }
  }'

const response = await fetch("https://admin.telemetron.ai/api/ext-v1/device/bulk-metadata", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "x-api-key": "tlm_xxxxxxxxxxxx",
  },
  body: JSON.stringify({
    devices: {
      "SN-A100": { firmwareVersion: "3.2.1", status: "active", location: "Building A" },
      "SN-B200": { firmwareVersion: "3.2.1", status: "maintenance" },
      "SN-UNKNOWN": { status: "active" },
    },
  }),
});

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

import requests

response = requests.post(
    "https://admin.telemetron.ai/api/ext-v1/device/bulk-metadata",
    headers={
        "Content-Type": "application/json",
        "x-api-key": "tlm_xxxxxxxxxxxx",
    },
    json={
        "devices": {
            "SN-A100": {"firmwareVersion": "3.2.1", "status": "active", "location": "Building A"},
            "SN-B200": {"firmwareVersion": "3.2.1", "status": "maintenance"},
            "SN-UNKNOWN": {"status": "active"},
        }
    },
)

print(response.json())

curl -X POST https://admin.telemetron.ai/api/ext-v1/device/bulk-metadata \
  -H "x-api-key: tlm_xxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "devices": {
      "SN-A100": { "firmwareVersion": "3.2.1", "status": "active", "location": "Building A" },
      "SN-B200": { "firmwareVersion": "3.2.1", "status": "maintenance" },
      "SN-UNKNOWN": { "status": "active" }
    }
  }'

const response = await fetch("https://admin.telemetron.ai/api/ext-v1/device/bulk-metadata", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "x-api-key": "tlm_xxxxxxxxxxxx",
  },
  body: JSON.stringify({
    devices: {
      "SN-A100": { firmwareVersion: "3.2.1", status: "active", location: "Building A" },
      "SN-B200": { firmwareVersion: "3.2.1", status: "maintenance" },
      "SN-UNKNOWN": { status: "active" },
    },
  }),
});

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

import requests

response = requests.post(
    "https://admin.telemetron.ai/api/ext-v1/device/bulk-metadata",
    headers={
        "Content-Type": "application/json",
        "x-api-key": "tlm_xxxxxxxxxxxx",
    },
    json={
        "devices": {
            "SN-A100": {"firmwareVersion": "3.2.1", "status": "active", "location": "Building A"},
            "SN-B200": {"firmwareVersion": "3.2.1", "status": "maintenance"},
            "SN-UNKNOWN": {"status": "active"},
        }
    },
)

print(response.json())

{
  "success": true,
  "updated": 2,
  "notFound": 1,
  "results": [
    { "identifier": "SN-A100", "deviceId": "d1a2b3c4-...", "status": "updated" },
    { "identifier": "SN-B200", "deviceId": "e5f6a7b8-...", "status": "updated" },
    { "identifier": "SN-UNKNOWN", "deviceId": "", "status": "not_found" }
  ]
}

{
  "error": "devices is required and must be an object mapping identifiers to metadata"
}

{
  "error": "Missing API key"
}

{
  "error": "Internal server error"
}

Status Codes

Code	Description
200	Devices successfully updated
400	Validation error (missing or invalid fields, invalid JSON, too many devices)
401	Authentication error (missing or invalid API key)
500	Internal server error

curl -X POST https://admin.telemetron.ai/api/ext-v1/device/bulk-metadata \
  -H "x-api-key: tlm_xxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "devices": {
      "SN-A100": { "firmwareVersion": "3.2.1", "status": "active", "location": "Building A" },
      "SN-B200": { "firmwareVersion": "3.2.1", "status": "maintenance" },
      "SN-UNKNOWN": { "status": "active" }
    }
  }'

const response = await fetch("https://admin.telemetron.ai/api/ext-v1/device/bulk-metadata", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "x-api-key": "tlm_xxxxxxxxxxxx",
  },
  body: JSON.stringify({
    devices: {
      "SN-A100": { firmwareVersion: "3.2.1", status: "active", location: "Building A" },
      "SN-B200": { firmwareVersion: "3.2.1", status: "maintenance" },
      "SN-UNKNOWN": { status: "active" },
    },
  }),
});

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

import requests

response = requests.post(
    "https://admin.telemetron.ai/api/ext-v1/device/bulk-metadata",
    headers={
        "Content-Type": "application/json",
        "x-api-key": "tlm_xxxxxxxxxxxx",
    },
    json={
        "devices": {
            "SN-A100": {"firmwareVersion": "3.2.1", "status": "active", "location": "Building A"},
            "SN-B200": {"firmwareVersion": "3.2.1", "status": "maintenance"},
            "SN-UNKNOWN": {"status": "active"},
        }
    },
)

print(response.json())

{
  "success": true,
  "updated": 2,
  "notFound": 1,
  "results": [
    { "identifier": "SN-A100", "deviceId": "d1a2b3c4-...", "status": "updated" },
    { "identifier": "SN-B200", "deviceId": "e5f6a7b8-...", "status": "updated" },
    { "identifier": "SN-UNKNOWN", "deviceId": "", "status": "not_found" }
  ]
}

{
  "error": "devices is required and must be an object mapping identifiers to metadata"
}

{
  "error": "Missing API key"
}

{
  "error": "Internal server error"
}

API Reference

Customer Management

Device Management

Device Assignment

Ticket Management

Bulk Update Device Metadata

Overview

Authentication

Request Body

Constraints

Response

200 OK — Success

BulkMetadataResponseItem

400 Bad Request

401 Unauthorized

500 Internal Server Error

Examples

Status Codes

​Overview

​Authentication

​Request Body

​Constraints

​Response

​200 OK — Success

​BulkMetadataResponseItem

​400 Bad Request

​401 Unauthorized

​500 Internal Server Error

​Examples

​Status Codes

Overview

Authentication

Request Body

Constraints

Response

200 OK — Success

BulkMetadataResponseItem

400 Bad Request

401 Unauthorized

500 Internal Server Error

Examples

Status Codes