Queue a typed operational, Display Control, or bounded player-recovery command

POST

/api/v1/screens/{id}/commands

curl --request POST \
  --url https://example.com/api/v1/screens/2489E9AD-2EE2-8E00-8EC9-32D5F69181C0/commands \
  --header 'Content-Type: application/json' \
  --data '{ "type": "sync_now", "payload": {}, "idempotencyKey": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0" }'

Display Control command types are display_power_on, display_power_off, display_set_input, display_set_volume, display_mute, display_unmute, display_set_brightness, and display_probe. They are capability-gated by the target Player. A Browser Player runs only sync_now, reload_playback, identify_screen, retry_current_item and skip_current_item; any other command type for a Browser Screen is refused with command_not_supported_by_player. Requires an Owner or Administrator with the write scope. Cookie-authenticated unsafe requests require X-CSRF-Token.

Parameters

Path Parameters

id

required

string format: uuid

Request Body^required

Media typeapplication/json

object

type

required

string

Allowed values: sync_now reload_playback identify_screen clear_media_cache clear_website_data disable_playback enable_playback install_player_update retry_player_recovery exit_safe_mode power_assist_sleep power_assist_wake retry_current_item skip_current_item recreate_renderer recreate_playback_session restart_activity restart_player_process resynchronize_player run_player_self_test install_autostart remove_autostart prepare_airplay_session stop_airplay_session test_airplay_support display_power_on display_power_off display_set_input display_set_volume display_mute display_unmute display_set_brightness display_probe provision_presentation_network test_presentation_network

payload

Per-type command arguments validated at queue time.

object

key

additional properties

any

idempotencyKey

string | null format: uuid

Responses

202

Command queued

Media typeapplication/json

object

data

required

object

id

required

string format: uuid

state

required

string

Allowed values: pending

expiresAt

required

string format: date-time

Example

{
  "data": {
    "state": "pending"
  }
}

422

The payload is invalid (command_invalid_payload), or the Screen’s player cannot run this command type (command_not_supported_by_player).

429

Pending command limit reached