> ## Documentation Index
> Fetch the complete documentation index at: https://docs.telemetron.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Create or Update Device

> Register a new device or update an existing device by identifier

## 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

<ParamField header="x-api-key" type="string" required>
  Your organization's API key
</ParamField>

## Request Body

<ParamField body="identifier" type="string" required>
  A unique identifier for the device. Must be a non-empty string.
</ParamField>

<ParamField body="type" type="string">
  The device type (e.g., `"sensor"`, `"gateway"`, `"controller"`). Required when creating a new device. Optional when updating an existing device.
</ParamField>

<ParamField body="properties" type="object">
  Optional metadata object containing additional device properties.
</ParamField>

## Response

<ResponseField name="success" type="boolean">
  Indicates whether the operation was successful.
</ResponseField>

<ResponseField name="message" type="string">
  A human-readable message describing the result.
</ResponseField>

<ResponseField name="deviceId" type="string">
  The unique ID of the created or updated device.
</ResponseField>

<ResponseField name="identifier" type="string">
  The identifier of the device.
</ResponseField>

<ResponseField name="type" type="string | null">
  The device type.
</ResponseField>

## Examples

### Create a New Device

<CodeGroup>
  ```bash cURL theme={null}
  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"
      }
    }'
  ```

  ```javascript JavaScript theme={null}
  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);
  ```

  ```python Python theme={null}
  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())
  ```
</CodeGroup>

<RequestExample>
  ```bash cURL - Create New Device theme={null}
  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"
      }
    }'
  ```

  ```javascript JavaScript - Create New Device theme={null}
  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);
  ```

  ```python Python - Create New Device theme={null}
  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())
  ```
</RequestExample>

### Update an Existing Device

<CodeGroup>
  ```bash cURL theme={null}
  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"
      }
    }'
  ```

  ```javascript JavaScript theme={null}
  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);
  ```

  ```python Python theme={null}
  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())
  ```
</CodeGroup>

<RequestExample>
  ```bash cURL - Update Existing Device theme={null}
  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"
      }
    }'
  ```

  ```javascript JavaScript - Update Existing Device theme={null}
  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);
  ```

  ```python Python - Update Existing Device theme={null}
  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())
  ```
</RequestExample>

### Response

<CodeGroup>
  ```json Success - Created theme={null}
  {
    "success": true,
    "message": "Device created successfully",
    "deviceId": "dev_abc123",
    "identifier": "sensor-001",
    "type": "sensor"
  }
  ```

  ```json Success - Updated theme={null}
  {
    "success": true,
    "message": "Device updated successfully",
    "deviceId": "dev_abc123",
    "identifier": "sensor-001",
    "type": "sensor"
  }
  ```

  ```json Error - Missing Identifier theme={null}
  {
    "error": "identifier is required and must be a non-empty string"
  }
  ```

  ```json Error - Missing Type for New Device theme={null}
  {
    "error": "type is required for new devices and must be a non-empty string"
  }
  ```
</CodeGroup>

<ResponseExample>
  ```json Success - Created theme={null}
  {
    "success": true,
    "message": "Device created successfully",
    "deviceId": "dev_abc123",
    "identifier": "sensor-001",
    "type": "sensor"
  }
  ```

  ```json Success - Updated theme={null}
  {
    "success": true,
    "message": "Device updated successfully",
    "deviceId": "dev_abc123",
    "identifier": "sensor-001",
    "type": "sensor"
  }
  ```

  ```json Error - Missing Identifier theme={null}
  {
    "error": "identifier is required and must be a non-empty string"
  }
  ```

  ```json Error - Missing Type for New Device theme={null}
  {
    "error": "type is required for new devices and must be a non-empty string"
  }
  ```

  ```json Error - Missing API Key theme={null}
  {
    "error": "Missing API key"
  }
  ```

  ```json Error - Invalid API Key theme={null}
  {
    "error": "Invalid API key"
  }
  ```

  ```json Error - Invalid JSON theme={null}
  {
    "error": "Invalid JSON payload"
  }
  ```
</ResponseExample>

## 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                                      |