Screens API

Screens are designed in the console. Over the API you list them and show them. The screen’s layout, content and buttons can only be edited in the console.

Showing a screen

Pass the screen’s ID as screen to the Announcement API:

curl -X POST https://api-v3.voicemonkey.io/announce \
  -H "Content-Type: application/json" \
  -d '{
    "token": "YOUR_TOKEN",
    "device": "YOUR_SPEAKER_DEVICE_ID",
    "screen": "dashboard-x7k2p",
    "speech": "Good morning",
    "var-INSIDE_TEMP": "21"
  }'

• var-NAME parameters are saved before the screen is built, so a screen showing {INSIDE_TEMP} shows 21.
• speech is optional. Without it the screen appears silently.
• The screen ID can itself be a placeholder, e.g. "screen": "{TODAYS_SCREEN}".
• An unknown ID returns 404 SCREEN_NOT_FOUND.

Listing your screens

GET/POST https://api-v3.voicemonkey.io/screens

curl https://api-v3.voicemonkey.io/screens \
  -H "Authorization: Bearer YOUR_TOKEN"

Returns 200 with the ID, name and layout of each screen:

{
  "success": true,
  "data": [
    { "id": "dashboard-x7k2p", "name": "Dashboard", "layout": "hero_strip", "updatedAt": "2026-09-25T10:12:00.000Z" },
    { "id": "noticeboard-a1b2c", "name": "Noticeboard", "layout": "title_body", "updatedAt": "2026-09-24T18:40:00.000Z" }
  ]
}

Field	Description
id	Pass this as screen to /announce.
name	The screen’s name in the console.
layout	The layout key, e.g. full, title_body, grid_2x2.
updatedAt	When the screen was last saved.

data is [] if the account has no screens yet. Takes the same token parameter / Authorization header as every other endpoint and returns the same 401 errors.

Tips

• A screen shows the values its variables had when it was sent. To update it, send it again, or add a button that sets a variable (the screen redraws after the tap).
• Clocks, dates, countdowns and slideshows keep changing on the device without further requests.
• Each call counts as one request against your plan’s monthly limit, like any announcement.