Skip to main content
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" }
    }
  }'

{
  "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" }
  ]
}

​
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

​
x-api-key
string
required
Your organization’s API key

​
Request Body

​
devices
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

​
success
boolean
Always true on a 200 response.
​
updated
number
Count of devices that were found and updated.
​
notFound
number
Count of identifiers that matched no device in the organization.
​
results
BulkMetadataResponseItem[]
Per-identifier result in the same order as the input keys.

​
BulkMetadataResponseItem

FieldTypeDescription
identifierstringThe trimmed device identifier
deviceIdstringThe 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:
MessageCause
"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" }
    }
  }'

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" }
    }
  }'

{
  "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" }
  ]
}

​
Status Codes

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