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

# Register Device

> Register a wearable device in your project

Register a device using its serial number. The response includes the Bota device ID (`dev_*`) that you use for later device APIs such as bind, heartbeat, commands, and settings.

<Note>
  Store the returned `id` alongside the device serial number in your system. If the mapping is unavailable later, recover it with `GET /devices?serial_number={serial_number}`.
</Note>

## Authentication

Requires an [API key](/authentication) with `devices:write` scope.

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST https://api.bota.dev/v1/devices \
    -H "Authorization: Bearer sk_live_..." \
    -H "Content-Type: application/json" \
    -d '{
      "serial_number": "SN-2025-001234",
      "model": "bota_pin",
      "firmware_version": "1.2.0"
    }'
  ```

  ```javascript Node.js theme={null}
  const response = await fetch('https://api.bota.dev/v1/devices', {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer sk_live_...',
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      serial_number: 'SN-2025-001234',
      model: 'bota_pin',
      firmware_version: '1.2.0',
    }),
  });

  const device = await response.json();
  ```

  ```python Python theme={null}
  import requests

  response = requests.post(
      'https://api.bota.dev/v1/devices',
      headers={
          'Authorization': 'Bearer sk_live_...',
          'Content-Type': 'application/json',
      },
      json={
          'serial_number': 'SN-2025-001234',
          'model': 'bota_pin',
          'firmware_version': '1.2.0',
      },
  )

  device = response.json()
  ```
</RequestExample>

## Request Body

<ParamField body="serial_number" type="string" required>
  Device serial number (unique identifier from hardware).
</ParamField>

<ParamField body="model" type="string" required>
  Device model. One of `bota_pin`, `bota_pin_pro`, or `bota_note`.
</ParamField>

<ParamField body="firmware_version" type="string">
  Current firmware version on the device.
</ParamField>

<ParamField body="metadata" type="object">
  Arbitrary key-value metadata.
</ParamField>

## Response

Returns the newly registered device object.

<ResponseExample>
  ```json 201 theme={null}
  {
    "id": "dev_abc123",
    "serial_number": "SN-2025-001234",
    "model": "bota_pin",
    "firmware_version": "1.2.0",
    "status": "unbound",
    "end_user_id": null,
    "metadata": {},
    "created_at": "2025-01-15T10:30:00Z",
    "updated_at": "2025-01-15T10:30:00Z"
  }
  ```

  ```json 409 theme={null}
  {
    "error": {
      "code": "resource_already_exists",
      "message": "Device with serial_number 'SN-2025-001234' is already registered"
    }
  }
  ```
</ResponseExample>

## Response Fields

| Field                 | Type            | Description                                                                              |
| --------------------- | --------------- | ---------------------------------------------------------------------------------------- |
| `id`                  | string          | Device identifier (`dev_*`)                                                              |
| `serial_number`       | string          | Physical serial number                                                                   |
| `model`               | string          | Device model (`bota_pin` or `bota_note`)                                                 |
| `firmware_version`    | string \| null  | Current firmware version                                                                 |
| `status`              | string          | `unbound` or `bound`                                                                     |
| `end_user_id`         | string \| null  | Bound end user (`eu_*`), null if unbound                                                 |
| `battery_percent`     | integer \| null | Battery level (0-100), null if no heartbeat received                                     |
| `storage_used_mb`     | integer \| null | Storage used in MB                                                                       |
| `storage_total_mb`    | integer \| null | Total storage capacity in MB                                                             |
| `signal_strength_dbm` | integer \| null | Signal strength in dBm                                                                   |
| `last_heartbeat_at`   | string \| null  | Last heartbeat timestamp (ISO 8601)                                                      |
| `recording_state`     | object \| null  | Current recording state (device\_state, pending\_recordings, flags, connection\_type\[]) |
| `metadata`            | object          | Custom key-value metadata                                                                |
| `created_at`          | string          | Creation timestamp (ISO 8601)                                                            |
| `updated_at`          | string          | Last update timestamp (ISO 8601)                                                         |

## Resolving a Device ID from a Serial Number

For a newly registered device, use the `id` returned by this endpoint.

For an already registered device, use the exact [List Devices](/api-reference/devices/list) `serial_number` filter. If registration returns `409` and the filter returns a device, reuse its `dev_*` ID. If the filter returns an empty `data` array, the device is registered elsewhere or is inaccessible to this project.