Devices API

Manage the lifecycle of IoT devices: creation, listing, updating metadata, reading status, and deletion.

---

List devices

GET /api/v1/devices

Query params:

Param	Type	Description
projectId	UUID	Filter by project
status	online | offline	Filter by connection status
page	number	Page number (default: 1)
limit	number	Items per page (default: 20, max: 100)

Response:

{
  "success": true,
  "data": {
    "devices": [
      {
        "id": "uuid",
        "name": "Greenhouse Sensor",
        "status": "online",
        "lastSeen": "2024-03-15T10:30:00.000Z",
        "projectId": "uuid",
        "token": "dt_..."
      }
    ],
    "total": 42,
    "page": 1
  }
}

---

Get a device

GET /api/v1/devices/{deviceId}

---

Create a device

POST /api/v1/devices
Content-Type: application/json

{
  "name": "Greenhouse Sensor",
  "projectId": "uuid",
  "description": "ESP32 with DHT22"
}

Response (201): Returns the full device with the token field.

caution

Save the token from the create response — it is the device's MQTT credential and cannot be retrieved later (only regenerated).

---

Update a device

PATCH /api/v1/devices/{deviceId}
Content-Type: application/json

{
  "name": "New Name",
  "description": "Updated description",
  "tags": ["greenhouse", "humidity"]
}

---

Regenerate device token

POST /api/v1/devices/{deviceId}/regenerate-token

Response:

{
  "success": true,
  "data": { "token": "dt_new-token-here" }
}

The old token is immediately invalidated.

---

Delete a device

DELETE /api/v1/devices/{deviceId}

Deletes the device and all its pin data.
This action is irreversible. A 204 No Content response indicates success.

---

Device status

GET /api/v1/devices/{deviceId}/status

Response:

{
  "success": true,
  "data": {
    "status": "online",
    "lastSeen": "2024-03-15T10:30:00.000Z",
    "ipAddress": "192.168.1.105",
    "firmwareVersion": "1.2.3"
  }
}