Skip to main content

Push images

Use the push endpoint to display a 64×32 image immediately or add it to a device's regular content rotation. PNG, WebP, and GIF inputs are supported.

POST/v1/devices/{deviceId}/push

Display a temporary image or create a persistent rotation entry.

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

Request body​

FieldTypeRequiredBehavior
imagestringYesBase64 or a PNG/WebP/GIF data URL. The image must be 64×32 and at most 192 KiB. PNG and GIF input is converted to lossless WebP.
durationnumberNoTemporary display duration in seconds. Defaults to 5; allowed values are 5, 10, 15, 30, 35, 40, and 45. Ignored when installationId is present.
installationIdstringNoCreates or updates a persistent entry in the device's rotation.
backgroundbooleanNoWhen true, updates a persistent installation without displaying it immediately. Use with installationId.

A successful request returns 200 {}. Invalid requests return 400, missing devices return 404, and requests without permission to update the device return 403.

Display a temporary image​

Omit installationId to display the image immediately for a limited time. The device resumes its regular rotation when the duration ends. A newer push replaces any temporary image currently on the display.

Request body
{
  "image": "data:image/webp;base64,<base64 WebP>",
  "duration": 10
}

If you omit duration, the image is shown for 5 seconds.

Create a persistent installation​

Include installationId to add the image to the device's content rotation. Choose a stable identifier from your application so you can update or delete the same installation later.

Request body
{
  "image": "data:image/png;base64,<base64 PNG>",
  "installationId": "daily-metrics"
}

The image is displayed immediately, then appears in the regular rotation. Its initial display duration uses the device's configured scheduleInterval. Sending another request with the same installationId replaces the existing image.

To update the rotation without interrupting the current display, set background to true:

Background update
{
  "image": "data:image/png;base64,<base64 PNG>",
  "installationId": "daily-metrics",
  "background": true
}

Use the delete installation endpoint when you no longer want the image in the device's rotation.

Was this helpful?