Devices

Use the device endpoints to inspect devices connected to your account, update their settings, and manage their installed apps.

Device identifiers

deviceId can be the device ID returned by the API, its serial number, or its MAC address. Your API key can access devices owned by the same account.

List devices

GET/v1/devices

List the devices connected to the authenticated account, oldest first.

Request

GET /v1/devices
Authorization: Bearer <API key>

200 response

[
  {
    "id": "device-id",
    "name": "Kitchen",
    "brightness": 30,
    "volume": 50,
    "lastOnline": "2026-09-08T15:30:00.000Z",
    "autoDim": true,
    "timezone": "America/Lima",
    "scheduleInterval": 30,
    "sleep": {
      "enabled": true,
      "start": "22:00",
      "end": "07:00"
    }
  }
]

Accounts without devices receive 200 [].

Get a device

GET/v1/devices/{deviceId}

Return one device using the same response shape as the list endpoint.

Request

GET /v1/devices/{deviceId}
Authorization: Bearer <API key>

Missing devices return 404; requests without permission to access the device return 403.

Update a device

PATCH/v1/devices/{deviceId}

Update only the settings included in the request body.

Request

PATCH /v1/devices/{deviceId}
Authorization: Bearer <API key>
Content-Type: application/json

At least one supported field is required. Omitted fields remain unchanged and unknown fields are rejected.

Request body

{
  "brightness": 75,
  "sleepEnabled": true,
  "sleepStart": "23:00"
}

Field	Type	Validation
name	string	1–25 characters
brightness	integer	0–100
volume	integer	0–100
autoDim	boolean	—
timezone	string	Available timezone ID
sleepEnabled	boolean	—
sleepStart	string	24-hour HH:mm
sleepEnd	string	24-hour HH:mm
scheduleInterval	integer	At least 15 seconds

The response is the updated device in the same shape returned by GET /v1/devices. A partial sleep update preserves any sleep settings you omit.

Invalid bodies return 400, missing devices return 404, and requests without permission to update the device return 403.

List installations

GET/v1/devices/{deviceId}/installations

List installations in the order they appear in the device's rotation.

Request

GET /v1/devices/{deviceId}/installations
Authorization: Bearer <API key>

200 response

[
  {
    "id": "installation-id",
    "app": {
      "id": "app-id",
      "name": "Weather"
    },
    "createdAt": "2026-09-04T10:00:00.000Z"
  },
  {
    "id": "pushed-installation-id",
    "app": null,
    "createdAt": "2026-09-04T11:00:00.000Z"
  }
]

For an app installation, id is the installation ID returned by the API and app contains the app ID and name. For an installation created through a push, id is the caller-provided installationId and app is null.

Missing devices return 404; requests without permission to access the device return 403.

Delete an installation

DELETE/v1/devices/{deviceId}/installations/{installationId}

Remove an app or pushed installation from a device.

Request

DELETE /v1/devices/{deviceId}/installations/{installationId}
Authorization: Bearer <API key>

installationId may be the ID returned for an app installation or the caller-provided ID returned for a pushed installation. The installation is matched within the specified device.

A successful deletion returns 200 {}. Missing devices or installations return 404; requests without permission to update the device return 403.