dot-device-openapi

Dot Device OpenAPI and MCP

Use this skill when the user wants to operate a Dot. device:

• List devices or find a device ID
• Check device status
• Read or update device settings
• Switch to the next content
• Send Text API content
• Send Image API content
• Send an already-designed Canvas API payload
• List loop or fixed tasks on a device

If the user asks to design a custom Canvas card, dashboard, or windowData layout, use dot-canvas-designer first, then return here only when the user wants to send it to a device.

Product Routing

Read products.md before choosing an integration for Read Pico or Rand/0, or when the user asks for hardware resources. Read Pico development uses its official firmware repository; Rand/0 Display Mode uses a local image protocol. Do not request Dot cloud credentials or use the sending scripts for those routes. The requirements below apply to supported Dot cloud API devices.

Local MCP

Compatible agents can use the local dot-mcp stdio server instead of constructing HTTP requests. It exposes only the fixed Dot tools below; it does not expose arbitrary HTTP access:

• Read-only: dot_list_devices, dot_get_device_status, dot_get_device_settings, dot_list_timezones, dot_list_tasks, dot_validate_canvas
• Device-changing: dot_update_device_settings, dot_switch_next_content, dot_send_text, dot_send_image, dot_send_canvas

The server reads DOT_API_KEY from the MCP process environment. It never accepts the key as a tool argument, stores it, or logs it. Device-changing requests are sent once without automatic retries.

Install the local server with pipx install git+https://github.com/MindReset/dot_skill.git, run it with dot-mcp, or use uvx --from git+https://github.com/MindReset/dot_skill.git dot-mcp. Platform configuration examples are in docs/mcp-configs.md.

Requirements

• Base URL: https://dot.mindreset.tech
• Authentication: Authorization: Bearer dot_app_<api_key>
• API key source: ask the user or read DOT_API_KEY from the local environment.
• Device ID source: ask the user, list devices, or use the ID the user provides.
• Rate limit: 10 requests per second.

Successful POST control endpoints (next, text, image, canvas) return a JSON object with a top-level message field. Do not expect a legacy { code, message, result } wrapper.

Workflow

1. Confirm a valid API key and device ID.
2. For Text API, Image API, or Canvas API writes, ensure the matching content has already been added to the selected loop or fixed list in Dot. App Content Studio. Use taskType: "fixed" for fixed content; omitting taskType selects the loop list. List that same list to find taskKey.
3. Pick the endpoint:
   • Text display: POST /api/authV2/open/device/:deviceId/text
   • Image display: POST /api/authV2/open/device/:deviceId/image
   • Canvas display: POST /api/authV2/open/device/:deviceId/canvas
   • Device status: GET /api/authV2/open/device/:deviceId/status
   • Device settings: GET /api/authV2/open/device/:deviceId/settings
   • Update device settings: POST /api/authV2/open/device/:deviceId/settings
   • Timezone list: GET /api/authV2/open/timezones
   • Device list: GET /api/authV2/open/devices
   • Next content: POST /api/authV2/open/device/:deviceId/next
   • Task list: GET /api/authV2/open/device/:deviceId/:taskType/list
4. Always include Content-Type: application/json for POST requests.

Scripts

Use the scripts in scripts/ for local execution:

• list_devices.py
• get_device_status.py
• get_device_settings.py
• update_device_settings.py
• list_tasks.py
• switch_next.py
• send_text.py
• send_image.py
• send_canvas.py

Text, image, and Canvas helper scripts support --task-alias for the user-readable task name shown in the device task list.

Use --task-type fixed to update fixed content. With Canvas --payload, omitting --task-type preserves the file's taskType; an explicit flag overrides it. If neither provides taskType, the API defaults to loop.

Request Notes

For Text API, parameters include taskType, refreshNow, taskKey, taskAlias, title, message, signature, icon, link, and styles.

For Image API, parameters include taskType, refreshNow, taskKey, taskAlias, image, link, border, ditherType, and ditherKernel.

For Canvas API sending, parameters include taskType, refreshNow, taskKey, taskAlias, data, windowData, layoutFull, link, and border. Build or revise windowData with dot-canvas-designer. Set the target list with top-level taskType, outside data.

For all three content APIs, taskKey selects a matching API item only within taskType; other lists are not searched. Without taskKey, update the first matching API item in that list. Fixed updates preserve the configured times and display at the next scheduled refresh, including when the item is already displayed. refreshNow is ignored for fixed content. Do not promise an immediate fixed-content display or issue a separate next-content command to force it.

For device settings, parameters include alias, location, timezone, interval, and sleep. Timezones must be one of the keys returned by GET /api/authV2/open/timezones. Intervals must use whole-minute multiples and cannot exceed 43,200,000 ms (12 hours). Minimums are model-specific: Quote/0 and Quote/1 use 60,000 ms in both power modes; Rand/0 uses 900,000 ms on external power and 3,600,000 ms on battery; ZenMeasure M401 uses 60,000 ms on external power and 1,800,000 ms on battery. These limits apply to automatic switching, not manual refresh. The battery interval controls automatic wake and content refresh timing. sleep.start and sleep.end use local HH:mm time in the device timezone, and an end time earlier than start means the next day.

For Text API, Image API, and Canvas API, use top-level taskAlias when the user wants a human-readable task-list name. Omit taskAlias to keep the existing task name. Send taskAlias: "" or taskAlias: null only when the user explicitly wants to clear the name. Never put taskAlias inside Canvas data.

References

• references/authentication.md
• references/api_reference.md
• OpenAPI schema: ../../openapi/dot-openapi.yaml