Devices API

Manage your Palpable IoT devices programmatically.

List Devices

Retrieve all devices associated with your account.

GET /api/devices

Response

{
  "devices": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "Living Room Hub",
      "status": "online",
      "location": "Living Room",
      "pairingCode": "ABCD-1234",
      "lastSeen": "2024-01-15T10:30:00Z",
      "createdAt": "2024-01-01T00:00:00Z",
      "modules": [
        {
          "id": "mod-123",
          "moduleId": "SHT40",
          "name": "Temperature & Humidity",
          "i2cAddress": 68,
          "capabilities": ["temperature", "humidity"]
        }
      ]
    }
  ]
}

Device Status Values

Status	Description
`online`	Device is connected and responding
`offline`	Device is not currently connected
`pairing`	Device is awaiting pairing completion
`pending`	Hardware ordered but not yet arrived

Create Device

Create a new device entry. This generates a pairing code that can be used to connect physical hardware.

POST /api/devices

Request Body

{
  "name": "Kitchen Sensor",
  "location": "Kitchen",
  "modules": ["SHT40", "VEML7700"],
  "status": "pairing"
}

Field	Type	Required	Description
`name`	string	Yes	Device display name
`location`	string	No	Physical location
`modules`	string[]	No	Expected module IDs
`status`	string	No	Initial status (`pairing` or `pending`)

Response

{
  "device": {
    "id": "550e8400-e29b-41d4-a716-446655440001",
    "name": "Kitchen Sensor",
    "status": "pairing",
    "location": "Kitchen",
    "pairingCode": "WXYZ-5678",
    "expectedModules": ["SHT40", "VEML7700"],
    "createdAt": "2024-01-15T12:00:00Z",
    "modules": []
  }
}

Get Device

Retrieve details for a specific device.

GET /api/devices/{deviceId}

Path Parameters

Parameter	Type	Description
`deviceId`	uuid	The device's unique identifier

Response

{
  "device": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "Living Room Hub",
    "status": "online",
    "location": "Living Room",
    "firmwareVersion": "1.2.0",
    "lastSeen": "2024-01-15T10:30:00Z",
    "modules": [...]
  }
}

Update Device

Update device properties.

PATCH /api/devices/{deviceId}

Request Body

{
  "name": "Main Hub",
  "location": "Office"
}

Response

{
  "device": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "Main Hub",
    "location": "Office",
    "updatedAt": "2024-01-15T14:00:00Z"
  }
}

Delete Device

Remove a device from your account.

DELETE /api/devices/{deviceId}

Response

{
  "success": true,
  "message": "Device deleted"
}

Device Modules

Each device can have multiple I2C modules connected. Modules are automatically detected when the device comes online.

Common Module Types

Module ID	Description	Capabilities
`SHT40`	Temperature & Humidity Sensor	`temperature`, `humidity`
`VEML7700`	Ambient Light Sensor	`lux`, `white`
`SGP40`	Air Quality Sensor	`voc_index`
`LIS3DH`	Accelerometer	`acceleration_x`, `acceleration_y`, `acceleration_z`
`SHTC3`	Temperature & Humidity	`temperature`, `humidity`
`BMP280`	Barometric Pressure	`pressure`, `temperature`

For a complete list of supported modules, see the Hardware Catalog (opens in a new tab).

Introduction Commands API