Dot | Control Image Content

Deprecated legacy endpoint

Status: Deprecated. The legacy endpoint https://dot.mindreset.tech/api/open/image currently forwards requests to the new API. This compatibility behavior may be removed in a future release. No removal date is confirmed.

To keep your integration compatible:

Update the request URL to the new endpoint: /api/authV2/open/device/:deviceId/image
Send parameters according to this document (e.g. taskType / refreshNow / taskAlias / image / link / border / ditherType / ditherKernel / taskKey)
If you rely on legacy response payloads or error codes, adapt your integration to the new API responses

Quick Guide

Prerequisites

Make sure you have retrieved and saved your API key in the Dot. App;
Make sure you own at least one device and have obtained its device serial number;
Make sure your device is connected to power;
Make sure your device is connected to the network;
Make sure you've added the Image API content to the device loop or fixed list from the Content Studio in the Dot. App.

What Image API is for

Image API sends posters, screenshots, dashboards, or a favorite image to your device. It is best when you already have a complete visual and want the device to show that image directly.

Choose a content list and display timing

Choose the loop list or fixed list; the loop list is used by default. A task identifier targets an item only in the selected list. Without an identifier, the first Image API item in that list is updated.

Enable immediate display for loop content to request a screen update while the device is online. A sleeping device on battery retrieves saved content after automatic wake. Fixed content follows the times configured in Dot. App: even the item currently on screen waits for the next scheduled refresh. The API preserves its time settings. Read Timing for details.

About image input

Send an image as PNG Base64 data or a full HTTP(S) image URL. PNG Base64 may be bare Base64 or include the data:image/png;base64, prefix; the decoded payload must be no larger than 3MB. Remote image URLs must be anonymously accessible, require no authentication or special Referer, be no longer than 2048 characters, return a response body no larger than 3MB, and return image/* content directly.

Test image URLs for debugging

The following URLs are currently anonymously accessible and return image content that can be used with the Image API:

https://placehold.co/600x400/png
https://httpbin.org/image/png

If you want to verify your own image URL first, run:

curl -I 'https://your-image-url'

In most cases, you should confirm at least:

The HTTP status code is 200
The Content-Type is image/*, such as image/png or image/jpeg

The API rate limit is 10 requests per second. With the API, you can control device behavior and responses more flexibly.

Placeholders wrapped in ‘{{variable}}’ indicate values you must replace. Fill them with your actual values and remove the ‘{{}}’ braces.

Request Examples

POST

/api/authV2/open/device/:deviceId/image

Generated Code

1// Generating...

Update content in the fixed list

Query the fixed list, find the IMAGE_API item in the response, and use its key as taskKey:

curl 'https://dot.mindreset.tech/api/authV2/open/device/{{deviceId}}/fixed/list' \
  -H 'Authorization: Bearer dot_app_{{apiKey}}'

Call the same write endpoint with taskType: "fixed" and that taskKey at the top level. This request only saves the content; refreshNow: true does not display or refresh fixed content early:

curl -X POST 'https://dot.mindreset.tech/api/authV2/open/device/{{deviceId}}/image' \
  -H 'Authorization: Bearer dot_app_{{apiKey}}' \
  -H 'Content-Type: application/json' \
  -d '{
  "taskType": "fixed",
  "taskKey": "{{taskKey}}",
  "refreshNow": true,
  "image": "https://placehold.co/600x400/png"
}'

Response Example

This is an example response for immediate display of loop content.

{
	"message": "Device ABCD1234ABCD Image API content switched."
}

Reference Usage

Simple image without immediate display

curl -X POST \
	  https://dot.mindreset.tech/api/authV2/open/device/{{deviceId}}/image \
  -H 'Authorization: Bearer dot_app_UlSpzXNEXhYZIAFakHLCkMVVBLbsBIWxaRMVaJZGUOYKhDoDRZwLLvLujAIwQxbY' \
  -H 'Content-Type: application/json' \
  -d '{
    "refreshNow": false,
    "image": "{{PNG Base64 image data (max 3MB) or http(s) image URL}}",
    "link": "https://dot.mindreset.tech",
    "border": 0
  }'

Complex image

curl -X POST \
	  https://dot.mindreset.tech/api/authV2/open/device/{{deviceId}}/image \
  -H 'Authorization: Bearer dot_app_UlSpzXNEXhYZIAFakHLCkMVVBLbsBIWxaRMVaJZGUOYKhDoDRZwLLvLujAIwQxbY' \
  -H 'Content-Type: application/json' \
  -d '{
    "image": "{{PNG Base64 image data (max 3MB) or http(s) image URL}}",
    "link": "https://dot.mindreset.tech",
    "border": 1
  }'

Text image

Use common image tools (e.g., Figma, Sketch, Adobe Photoshop) to convert text to PNG, then convert it to base64 data.

curl -X POST \
	  https://dot.mindreset.tech/api/authV2/open/device/{{deviceId}}/image \
  -H 'Authorization: Bearer dot_app_UlSpzXNEXhYZIAFakHLCkMVVBLbsBIWxaRMVaJZGUOYKhDoDRZwLLvLujAIwQxbY' \
  -H 'Content-Type: application/json' \
  -d '{
    "image": "{{PNG Base64 image data (max 3MB) or http(s) image URL}}",
    "link": "https://dot.mindreset.tech",
    "border": 0,
    "ditherType": "NONE"
  }'

Image Dithering

Image dithering uses specific algorithms to reduce visual noise caused by color quantization, making images appear smoother. Common algorithms include Floyd–Steinberg, Atkinson, and Sierra. On e‑ink displays, dithering can further optimize black-and-white rendering so gray-level transitions look more natural.

When using the Image API, if you do not pass the ditherType parameter, the default is the error-diffusion Floyd–Steinberg algorithm. You can also disable it or adjust the dithering type and algorithm via parameters.

Enable Dithering

Error Diffusion (default)

Error diffusion distributes each pixel’s quantization error to neighboring pixels to reduce visual noise. It handles high-contrast areas effectively, yielding rich details and smooth gray transitions. Visually, it tends to look natural with no obvious grid and smooth gradients.

curl -X POST \
	  https://dot.mindreset.tech/api/authV2/open/device/{{deviceId}}/image \
  -H 'Authorization: Bearer dot_app_UlSpzXNEXhYZIAFakHLCkMVVBLbsBIWxaRMVaJZGUOYKhDoDRZwLLvLujAIwQxbY' \
  -H 'Content-Type: application/json' \
  -d '{
    "image": "{{PNG Base64 image data (max 3MB) or http(s) image URL}}",
    "link": "https://dot.mindreset.tech",
    "border": 0,
    "ditherType": "DIFFUSION"
  }'

Supported Error-Diffusion Kernels

Different error-diffusion kernels produce different visual results. Pass the algorithm via "ditherKernel": "{{dither algorithm}}".

Ordered Dithering

Ordered dithering applies a fixed, periodic threshold matrix to image pixels, unlike error diffusion which propagates the error dynamically. It helps reduce large color patches and banding, creating a visually uniform dot pattern. Due to periodicity, ordered dithered images often show a noticeable regular grid.

curl -X POST \
	  https://dot.mindreset.tech/api/authV2/open/device/{{deviceId}}/image \
  -H 'Authorization: Bearer dot_app_UlSpzXNEXhYZIAFakHLCkMVVBLbsBIWxaRMVaJZGUOYKhDoDRZwLLvLujAIwQxbY' \
  -H 'Content-Type: application/json' \
  -d '{
    "image": "{{PNG Base64 image data (max 3MB) or http(s) image URL}}",
    "link": "https://dot.mindreset.tech",
    "border": 0,
    "ditherType": "ORDERED"
  }'

Disable Dithering

If you primarily display text images via the Image API, we recommend disabling dithering to achieve sharper text.

curl -X POST \
	  https://dot.mindreset.tech/api/authV2/open/device/{{deviceId}}/image \
  -H 'Authorization: Bearer dot_app_UlSpzXNEXhYZIAFakHLCkMVVBLbsBIWxaRMVaJZGUOYKhDoDRZwLLvLujAIwQxbY' \
  -H 'Content-Type: application/json' \
  -d '{
    "image": "{{PNG Base64 image data (max 3MB) or http(s) image URL}}",
    "link": "https://dot.mindreset.tech",
    "border": 0,
    "ditherType": "NONE"
  }'

Troubleshooting

Endpoint

/api/authV2/open/device/:deviceId/image

Method

POST

Request Schema

Prop

Type

Choose the loop list or fixed list. If omitted, the loop list is used.

Default

loop

When enabled, requests immediate display of loop content; when disabled, only saves the content. Fixed content always waits for the next scheduled refresh, including the item currently on screen.

Default

true

Image displayed on the screen. Accepts PNG Base64 with or without a data URI prefix (decoded size up to 3MB), or a public HTTP(S) image URL. Recommended size: 296px×152px. URLs may contain up to 2048 characters and must directly return an image of up to 3MB without authentication.

Destination opened when the device is tapped with NFC. Accepts HTTP(S) URLs or an app URL scheme.

White or black screen border.

Default

How grayscale is converted to black and white: error diffusion, ordered dithering, or no dithering.

Default

DIFFUSION

Algorithm used for error diffusion. See the visual comparisons above to choose the desired texture.

Default

FLOYD_STEINBERG

Task identifier from the selected list. If omitted, updates the first Image API item in that list.

Name shown in the device task list, up to 100 characters. Omit to keep the current name; send an empty string to clear it. Does not change the displayed content.

Response Schema

The endpoint uses the HTTP status code to indicate the request result. The JSON response body only contains message.

Prop

Type

Human-readable result for a successful or failed request.

Status Codes

HTTP status	Meaning	Description
`200`	Success	Image API content switched / Data updated but content not switched
`400`	Invalid parameters	Invalid content list type Missing or invalid device ID Invalid image format Invalid screen border color Invalid dither type Invalid dither algorithm
`403`	Forbidden	You do not have permission to operate this device
`404`	Not found	Device not found or not registered Matching API content is missing from the selected list, or the task identifier does not match an Image API item in that list
`500`	Device response failure	Failed to switch Image API content

Troubleshoot list selection and display timing

400: use only loop or fixed for taskType.
404: ensure the request uses the same taskType as the list query and a taskKey from a matching API item in that list. Omitting taskType selects the loop list.
Fixed content was saved but the screen did not change: check its time settings in Dot. App and wait for the next scheduled refresh. refreshNow: true does not immediately refresh fixed content.

Deprecated legacy endpoint

To keep your integration compatible:

Update the request URL to the new endpoint: /api/authV2/open/device/:deviceId/image
Send parameters according to this document (e.g. taskType / refreshNow / taskAlias / image / link / border / ditherType / ditherKernel / taskKey)
If you rely on legacy response payloads or error codes, adapt your integration to the new API responses

Quick Guide

Prerequisites

Make sure you have retrieved and saved your API key in the Dot. App;
Make sure you own at least one device and have obtained its device serial number;
Make sure your device is connected to power;
Make sure your device is connected to the network;
Make sure you've added the Image API content to the device loop or fixed list from the Content Studio in the Dot. App.

What Image API is for

Image API sends posters, screenshots, dashboards, or a favorite image to your device. It is best when you already have a complete visual and want the device to show that image directly.

Choose a content list and display timing

About image input

Test image URLs for debugging

The following URLs are currently anonymously accessible and return image content that can be used with the Image API:

https://placehold.co/600x400/png
https://httpbin.org/image/png

If you want to verify your own image URL first, run:

curl -I 'https://your-image-url'

In most cases, you should confirm at least:

The HTTP status code is 200
The Content-Type is image/*, such as image/png or image/jpeg

The API rate limit is 10 requests per second. With the API, you can control device behavior and responses more flexibly.

Placeholders wrapped in ‘{{variable}}’ indicate values you must replace. Fill them with your actual values and remove the ‘{{}}’ braces.

Request Examples

POST

/api/authV2/open/device/:deviceId/image

Generated Code

1// Generating...

Update content in the fixed list

Query the fixed list, find the IMAGE_API item in the response, and use its key as taskKey:

curl 'https://dot.mindreset.tech/api/authV2/open/device/{{deviceId}}/fixed/list' \
  -H 'Authorization: Bearer dot_app_{{apiKey}}'

Call the same write endpoint with taskType: "fixed" and that taskKey at the top level. This request only saves the content; refreshNow: true does not display or refresh fixed content early:

curl -X POST 'https://dot.mindreset.tech/api/authV2/open/device/{{deviceId}}/image' \
  -H 'Authorization: Bearer dot_app_{{apiKey}}' \
  -H 'Content-Type: application/json' \
  -d '{
  "taskType": "fixed",
  "taskKey": "{{taskKey}}",
  "refreshNow": true,
  "image": "https://placehold.co/600x400/png"
}'

Response Example

This is an example response for immediate display of loop content.

{
	"message": "Device ABCD1234ABCD Image API content switched."
}

Reference Usage

Simple image without immediate display

curl -X POST \
	  https://dot.mindreset.tech/api/authV2/open/device/{{deviceId}}/image \
  -H 'Authorization: Bearer dot_app_UlSpzXNEXhYZIAFakHLCkMVVBLbsBIWxaRMVaJZGUOYKhDoDRZwLLvLujAIwQxbY' \
  -H 'Content-Type: application/json' \
  -d '{
    "refreshNow": false,
    "image": "{{PNG Base64 image data (max 3MB) or http(s) image URL}}",
    "link": "https://dot.mindreset.tech",
    "border": 0
  }'

Complex image

curl -X POST \
	  https://dot.mindreset.tech/api/authV2/open/device/{{deviceId}}/image \
  -H 'Authorization: Bearer dot_app_UlSpzXNEXhYZIAFakHLCkMVVBLbsBIWxaRMVaJZGUOYKhDoDRZwLLvLujAIwQxbY' \
  -H 'Content-Type: application/json' \
  -d '{
    "image": "{{PNG Base64 image data (max 3MB) or http(s) image URL}}",
    "link": "https://dot.mindreset.tech",
    "border": 1
  }'

Text image

Use common image tools (e.g., Figma, Sketch, Adobe Photoshop) to convert text to PNG, then convert it to base64 data.

curl -X POST \
	  https://dot.mindreset.tech/api/authV2/open/device/{{deviceId}}/image \
  -H 'Authorization: Bearer dot_app_UlSpzXNEXhYZIAFakHLCkMVVBLbsBIWxaRMVaJZGUOYKhDoDRZwLLvLujAIwQxbY' \
  -H 'Content-Type: application/json' \
  -d '{
    "image": "{{PNG Base64 image data (max 3MB) or http(s) image URL}}",
    "link": "https://dot.mindreset.tech",
    "border": 0,
    "ditherType": "NONE"
  }'

Image Dithering

Enable Dithering

Error Diffusion (default)

curl -X POST \
	  https://dot.mindreset.tech/api/authV2/open/device/{{deviceId}}/image \
  -H 'Authorization: Bearer dot_app_UlSpzXNEXhYZIAFakHLCkMVVBLbsBIWxaRMVaJZGUOYKhDoDRZwLLvLujAIwQxbY' \
  -H 'Content-Type: application/json' \
  -d '{
    "image": "{{PNG Base64 image data (max 3MB) or http(s) image URL}}",
    "link": "https://dot.mindreset.tech",
    "border": 0,
    "ditherType": "DIFFUSION"
  }'

Supported Error-Diffusion Kernels

Different error-diffusion kernels produce different visual results. Pass the algorithm via "ditherKernel": "{{dither algorithm}}".

Ordered Dithering

curl -X POST \
	  https://dot.mindreset.tech/api/authV2/open/device/{{deviceId}}/image \
  -H 'Authorization: Bearer dot_app_UlSpzXNEXhYZIAFakHLCkMVVBLbsBIWxaRMVaJZGUOYKhDoDRZwLLvLujAIwQxbY' \
  -H 'Content-Type: application/json' \
  -d '{
    "image": "{{PNG Base64 image data (max 3MB) or http(s) image URL}}",
    "link": "https://dot.mindreset.tech",
    "border": 0,
    "ditherType": "ORDERED"
  }'

Disable Dithering

If you primarily display text images via the Image API, we recommend disabling dithering to achieve sharper text.

curl -X POST \
	  https://dot.mindreset.tech/api/authV2/open/device/{{deviceId}}/image \
  -H 'Authorization: Bearer dot_app_UlSpzXNEXhYZIAFakHLCkMVVBLbsBIWxaRMVaJZGUOYKhDoDRZwLLvLujAIwQxbY' \
  -H 'Content-Type: application/json' \
  -d '{
    "image": "{{PNG Base64 image data (max 3MB) or http(s) image URL}}",
    "link": "https://dot.mindreset.tech",
    "border": 0,
    "ditherType": "NONE"
  }'

Troubleshooting

Endpoint

/api/authV2/open/device/:deviceId/image

Method

POST

Request Schema

Prop

Type

Choose the loop list or fixed list. If omitted, the loop list is used.

Default

loop

When enabled, requests immediate display of loop content; when disabled, only saves the content. Fixed content always waits for the next scheduled refresh, including the item currently on screen.

Default

true

Destination opened when the device is tapped with NFC. Accepts HTTP(S) URLs or an app URL scheme.

White or black screen border.

Default

How grayscale is converted to black and white: error diffusion, ordered dithering, or no dithering.

Default

DIFFUSION

Algorithm used for error diffusion. See the visual comparisons above to choose the desired texture.

Default

FLOYD_STEINBERG

Task identifier from the selected list. If omitted, updates the first Image API item in that list.

Name shown in the device task list, up to 100 characters. Omit to keep the current name; send an empty string to clear it. Does not change the displayed content.

Response Schema

The endpoint uses the HTTP status code to indicate the request result. The JSON response body only contains message.

Prop

Type

Human-readable result for a successful or failed request.

Status Codes

HTTP status	Meaning	Description
`200`	Success	Image API content switched / Data updated but content not switched
`400`	Invalid parameters	Invalid content list type Missing or invalid device ID Invalid image format Invalid screen border color Invalid dither type Invalid dither algorithm
`403`	Forbidden	You do not have permission to operate this device
`404`	Not found	Device not found or not registered Matching API content is missing from the selected list, or the task identifier does not match an Image API item in that list
`500`	Device response failure	Failed to switch Image API content

Troubleshoot list selection and display timing

400: use only loop or fixed for taskType.
404: ensure the request uses the same taskType as the list query and a taskKey from a matching API item in that list. Omitting taskType selects the loop list.
Fixed content was saved but the screen did not change: check its time settings in Dot. App and wait for the next scheduled refresh. refreshNow: true does not immediately refresh fixed content.

Control Image Content

Contents

Control Image Content

Contents