Display Screens

Changes Display Screens settings shared by every facility in the facility's brand: the boot screen shown while screens start up, and what templated content shows. Organisation admins only; read the current values and canEdit with display_settings_read boot_screen or templated.

Actions:

• save_boot_screen: Save the boot screen. Sets the boot screen image (PNG, JPEG or WebP, up to 10 MB, from a public https imageUrl or imageBase64) and/or how it is laid out. Without an image, fit and background re-render the current one. Screens pick it up when they next start. Asks for confirmation.
• reset_boot_screen: Reset the boot screen. Removes the brand's boot screen; screens go back to the default one when they next start. Asks for confirmation.
• save_templated: Save templated content settings. What templated content screens and the Schedule show: the data source name, workout names, programs in the Schedule and how far ahead, training phases and how far ahead. Asks for confirmation.

Creates, renames and deletes Display Screen groups at a facility and sets which screens are in them. Groups are publish targets (display_publish targets.groupIds) and command targets (display_screen_command groupIds). When several screens, groups or targets are given, this acts on all of them in one call; check with the user before acting on many.

Actions:

• save: Save a group. Create: name (and optionally screenIds). Rename: groupId (id or current name) and name. screenIds replaces the members; screens not listed leave this group but keep their other groups.
• delete: Delete a group. Deletes a group: its screens leave it (they keep their other groups) and content published to the group is removed from the schedule. Needs groupId. Asks for confirmation.

Publishes static HTML apps ("hosted apps") for Display Screens. Call display_library_read app_guidelines first for screen sizes, design rules, limits and the SDK, and display_screenshot afterwards to check the result on a screen. When several screens, groups or targets are given, this acts on all of them in one call; check with the user before acting on many.

Actions:

• publish: Publish a hosted app. Creates a hosted app (name + files) or publishes a new version (appId + files; it goes live everywhere the app is shown, rollback undoes it). publishTo also puts it on screens, as display_publish does; a brand or organisation target needs confirm. Needs files. May ask for confirmation.
• rollback: Roll back a hosted app. Makes an earlier version current again, everywhere the app is shown. List versions with display_library_read app_versions. Needs appId, version.

Reads the Display Screens content library visible to a facility: media (images, videos), apps (web pages, hosted HTML apps, AI Agent apps, CCTV views) and playlists, plus AI Agent apps and CCTV sources that can be added.

Each item has a contentRef (media#…, app#…, playlist#…) for display_publish and playlists. ownerScope shows who owns it (facility#, brand# or org#); content can only be published within its owner. Media with status processing isn't ready yet; failed needs re-uploading. Web pages with frameable: false can't play in playlists, only as a full-page screen. Items with a displayIssue are skipped by screens: an AI Agent app that is unpublished, paused, display-off, audience-limited or without Custom Apps; a CCTV view with no-cctv, cctv-off (a facility admin turns CCTV on for screens in Display Screens settings) or no-cameras.

Actions:

• list: List library items. Media and apps (paged; filter by type, kind, tag or name), or with type agent-apps the AI Agent apps allowed on screens that you can publish with display_publish content.agentAppId. Each item has a type: media, app or agent-app.
• cctv_sources: List CCTV sources. The facility's cameras and shared Live Views for display_publish content.cctv, and whether CCTV on screens is turned on. Needs CCTV access at the facility.
• get: Get a library item. One media item, app or playlist by contentRef. Needs contentRef.
• usages: Where content is used. The live schedule assignments and playlists that use a media item or app (or the assignments for a playlist). Content in use cannot be deleted. Needs contentRef.
• app_versions: List hosted app versions. The versions of a hosted app and which one is current, for display_hosted_apps_write rollback. Needs appId.
• app_guidelines: Hosted app guidelines. Screen sizes, design rules, bundle limits, the Display App SDK and a starter template. Call this before building an app for display_hosted_apps_write publish.
• check_url: Check a web page. Whether a web page can be shown inside playlists (some sites refuse to be framed), with hints about how it looks. Pages that refuse framing can still be a full-page screen. Needs url.
• playlists: List playlists. Playlists visible to the facility (paged), each with its items (contentRef, duration, fit).

Adds and changes Display Screens library content: upload images and videos, create web page, AI Agent app and CCTV view apps, edit names, tags, durations and dates, delete unused items, and refresh an app's preview. Hosted HTML apps are published with display_hosted_apps_write; playlists with display_playlists_write.

Design images at 1920×1080 (landscape) or 1080×1920 (portrait). New media starts as processing while web-ready versions are made; it can go into playlists straight away and plays once ready. ownerScope: facility (default), brand or organisation (brand and organisation need organisation-wide access).

Actions:

• upload_media: Upload an image or video. Adds an image or video from a public https url (preferred; images up to 25 MB, videos up to 200 MB) or base64 with mimeType (up to 20 MB). JPEG, PNG, WebP, GIF images; MP4, WebM, MOV videos (converted to H.264 MP4 up to 1080p). Larger videos: create_video_upload.
• create_video_upload: Start a large video upload. For videos up to 2 GB: records the video and returns a presigned upload (PUT the file to upload.url with upload.headers before upload.expiresAt), then call transcode with its contentRef. Needs name, mimeType, bytes.
• transcode: Process a video. Converts a video for screens: after create_video_upload, again after a failure, or for an older video screens cannot play. Needs contentRef.
• create_app: Add an app. Adds a web page (kind url, pass url; checked for framing), an AI Agent app (kind agent-app, pass agentAppId from display_library_read list type agent-apps) or a CCTV view (kind cctv-view, facility-owned, needs CCTV access). Needs kind, name.
• update: Update a library item. Changes a media item's or app's name, tags or duration; a media item's validFrom/validTo (ISO, null clears; outside them it is skipped); a web page's url; or a CCTV view's cameras, view, layout or quality. Needs contentRef.
• delete: Delete a library item. Deletes a media item or app. Blocked while it is in a live schedule or playlist: the error lists them (remove them with display_schedule_write delete or display_playlists_write save first). Needs contentRef. Asks for confirmation.
• refresh_preview: Refresh an app's preview. Takes a new screenshot of an app for its library preview (for example after the page changed). Needs contentRef.

Creates, updates and deletes Display Screens playlists: ordered loops of media and apps. Changes reach every screen showing the playlist within seconds. Publish a playlist with display_publish content.contentRef "playlist#".

Actions:

• save: Save a playlist. Create: name + items (items may be empty). Update: playlistId + any of name, items, transition; items replaces the whole list, so send every item in order.
• delete: Delete a playlist. Deletes a playlist. Blocked while it is published anywhere: the error lists the assignments to remove first (display_schedule_write delete). Needs playlistId. Asks for confirmation.

Puts content on Display Screens: a media item, playlist, app, web page, AI Agent app or CCTV live view, on screens, groups, the facility, its brand or its organisation.

mode: now (default) replaces what the targets normally show; scheduled shows it only in weekly windows (facility time zone) and/or between from and to; takeover interrupts everything for durationMin (or until a time), then ends by itself (stop early with display_takeover_stop). Screens resolve what to show by layer (takeover > scheduled > default), then by how specific the target is (screen > group > facility > brand > organisation).

CCTV: live camera feeds are visible to anyone near the screens. The first call returns requiresConfirmation (code CCTV_CONFIRMATION_REQUIRED); ask the user, then call again with confirmCctv: true. The facility must have "Allow CCTV on display screens" on.

Only player-mode screens show published content; others are listed in warnings. Returns a batchId; display_schedule_write delete with it undoes the whole publish. When several screens, groups or targets are given, this acts on all of them in one call; check with the user before acting on many.

Reads what is published to Display Screens: for one screen, what it shows at a time and over a range (resolved across every layer and target it inherits from) plus the assignments that reach it; or the assignments published to a group, the facility, its brand or its organisation.

Assignment ids (as_…) and batch ids (bt_…) are what display_schedule_write updates or deletes. Times are ISO; windows are in the facility time zone.

Actions:

• get: Get a screen's schedule. What a screen shows at at (default now), its timeline from from to to (default 24 hours), and every assignment that reaches it. Needs screenId.
• list_assignments: List assignments. Assignments published to a group (groupId), or to the facility, its brand or its organisation (target, default facility). Paged, newest change first.

Changes what is published to Display Screens: edit an assignment's timing, priority or content (optionally across its whole publish), or remove one assignment or a whole publish. Find ids with display_schedule_read. Removing content from the schedule leaves it in the library; to end a takeover early but keep its history, use display_takeover_stop.

Actions:

• update: Update an assignment. Changes timing (weekly windows, from/to; null clears a date), priority, or content of an assignment. applyToBatch makes the same change to every target of the publish. A takeover can only get a new end time. CCTV content needs confirmCctv after the user agreed. Needs assignmentId.
• delete: Remove from the schedule. Removes one assignment (assignmentId) or everything from one publish (batchId). Screens go back to what they would otherwise show within seconds. Asks for confirmation.

Sends a live command to Display Screens at a facility: reload (player screens refetch their schedule), identify (flash the screen's name and code, to find it in the venue), displayOn/displayOff (the TV panel), rebootDevice (restarts the screen's computer, 1–2 minutes blank; needs confirm: true) or osd (a short on-screen message; pass message).

Pick screens with screenIds and/or groupIds (every screen of those groups at the facility), or allScreens: true for every screen at the facility (displayOn/displayOff then reach templated content screens too). Returns per-screen results. When several screens, groups or targets are given, this acts on all of them in one call; check with the user before acting on many.

Reads a facility's Display Screens: list them with their status and what is on now and next (filter by group, status or display mode), get one screen's full detail and timeline, or list screen groups with their screens.

Display mode is shown to users as "Data Source": player is "User managed content", program-builder is "Templated content" (never say "Program Builder" to users), url is "Full-page website (Kiosk Mode)". Times are ISO; the facility time zone is returned.

Actions:

• list: List screens. Screens at the facility (paged), each with status, last heartbeat, groups, tags and what is on now and next. Also returns the groups.
• get: Get a screen. One screen's full detail (status, heartbeat, player version, recent errors) and, for player screens, what it shows over a time range (default the next 24 hours, max 14 days). Needs screenId.
• groups: List screen groups. Screen groups at the facility (paged), each with its screens.

Changes Display Screens: pair a new screen by its pairing code; rename a screen, set its groups and tags, or switch its display mode (shown to users as "Data Source"); rotate a player screen's token; make a time-limited preview link of a screen or content; or factory reset a screen (removes it from the facility).

Display modes: player ("User managed content"), url ("Full-page website (Kiosk Mode)", pass url, https only), program-builder ("Templated content"; never say "Program Builder" to users). Changing mode reloads the screen now and changes what members see, so it needs the user to confirm.

Actions:

• update: Update a screen. Sets a screen's name, groups (ids or names; replaces the current groups), tags (replaces them) and/or display mode. A mode change returns requiresConfirmation first. Needs screenId. May ask for confirmation.
• rotate_token: Rotate screen token. Issues a new token for a player screen and reloads it; the old token stops working. Use when a screen's player URL may have leaked. Needs screenId. Asks for confirmation.
• create_preview_link: Create a preview link. A link (valid for a limited time) that shows what a screen shows, or how content looks, optionally at a future time. Anyone with the link can view it until it expires.
• reset: Factory reset a screen. Removes the screen from the facility and factory resets it; a powered-off screen resets when it next comes online, then shows its pairing page. Pass confirmName: the screen name exactly as the user typed it. Needs Device Management. Needs screenId, confirmName. Asks for confirmation.
• pair: Pair a new screen. Adds a new screen to the facility by the 6-character code on its pairing page, then reloads it. Facilities with Display Screens only start it on player; with templated content too, mode picks (default program-builder). Needs Device Management. Needs pairingCode, name. Asks for confirmation.

Captures what a Display Screen shows right now and returns the image, so you can check your own work after publishing (layout, text size, nothing cut off or scrolling). Waits up to 15 seconds for the screen to answer; offline screens time out. Also returns a portal URL for the JPEG (signed-in users only, kept for 10 minutes).

Screenshots can include live CCTV and members in view; don't share them outside the conversation.

Reads Display Screens settings for a facility: the fallback slate, polling and nightly reload, CCTV on screens; the screen power schedule (with the next days' on/off times); automations (brightness, bell volume, check-in power, round timer state); the brand's boot screen and templated content settings; and, with templated content, the scheduled program dates and the templated schedule.

Actions:

• settings: Get facility display settings. The fallback slate (message, background, logo, facility name), polling interval, nightly reload time and whether CCTV may be shown on screens.
• power_schedule: Get the power schedule. When screens turn on and off: the saved schedule (or the older automations' equivalent), the facility time zone and the on/off times for the next 7 days.
• power_schedule_preview: Preview a power schedule. The on/off times a schedule would give over the next 7 days, without saving it. Needs schedule.
• automations: Get display automations. Automatic brightness (day/night levels and triggers), bell volume levels and schedule (decimal hours, 6.5 = 06:30), check-in power, and the round timer state, for one or several facilities. usesGlobalDefaults is true until the facility saves its own.
• boot_screen: Get the brand's boot screen. The image the facility's brand shows while screens start up (fit, background, image URLs) and whether you can change it (organisation admins).
• templated: Get the brand's templated content settings. What templated content screens and the Schedule show for the facility's brand (source name, workout names, programs and training phases, look-ahead days) and whether you can change it (organisation admins).
• program_dates: List scheduled program dates. The dates with a workout program, from the start of this month to the brand's look-ahead. Needs templated content (Program Builder) at the facility.
• templated_schedule: Get the templated schedule. Programs and training phases between two dates (YYYY-MM-DD, at most 62 days), as the brand shows them. Needs templated content (Program Builder) at the facility. Needs from, to.

Changes a facility's Display Screens settings: the fallback slate, polling and nightly reload, and "Allow CCTV on display screens"; the screen power schedule; and automations (brightness, bell volume, check-in power). Fields you leave out keep their current values. Brand-wide settings (boot screen, templated content) are in display_brand_settings_write.

Actions:

• save_settings: Save facility display settings. The fallback slate shown when nothing is scheduled, polling interval (30–300 s), nightly reload time (HH:mm) and allowCctv. Turning allowCctv on needs the user to confirm and a facility admin with CCTV access. May ask for confirmation.
• save_power_schedule: Save the power schedule. Changes when screens turn on and off; the fields you pass are merged into the saved schedule. Returns the next 7 days' on/off times. Check with display_settings_read power_schedule_preview first. Needs schedule.
• save_automations: Save display automations. Changes automatic brightness, bell volume and check-in power settings. The facility then keeps its own settings instead of the global defaults.

Ends running Display Screens takeovers now: for one publish (batchId from display_publish), for targets (default: takeovers published to the whole facility), or with allScreens for every takeover published to the facility, its screens or their groups. Brand and organisation takeovers only stop by batchId. Screens return to their scheduled or default content within seconds; returns how many stopped. When several screens, groups or targets are given, this acts on all of them in one call; check with the user before acting on many.

Controls templated content screens (display mode "Templated content" in display_screens_read): load a day's workout program on them, or control the round timer. User managed content and full-page website screens are never affected.

Actions:

• load_program: Load a workout program. Loads a date's workout program (YYYY-MM-DD, default today) from the facility's data source on every templated content screen at one or several facilities; screens reload within seconds. Use it to show today's or another day's workout, or when screens show the wrong one. Several facilities need confirm. May ask for confirmation.
• clock: Control the round timer. Plays, pauses, restarts or stops the round timer on templated content screens, mutes or unmutes round sounds, sets the bell volume (setvolume with volume 0–100) or asks for its state. Needs templated content (Program Builder) at the facility. Needs command.