---
title: "Send a command to a screen"
method: POST
path: "/v1/screens/{id}/commands"
tags: ["screens"]
---

# Send a command to a screen

`POST /v1/screens/{id}/commands`

## Request

- Base URL: `https://api.brixsignage.com`
- URL: `https://api.brixsignage.com/v1/screens/{id}/commands`
- Auth: HTTP bearer

Queue a command for a screen's device, such as reboot, turning the display on or off, taking a screenshot, or clearing the cache. The device runs the command the next time it checks in.

Queues a device command (reboot, refresh, screenshot, volume, …). Poll GET /v1/screens/{id}/commands/{commandId} for the device's answer.

**Notes.**
- A `screenshot` that coalesces onto an older pending one answers 200 (not 201) with `coalesced: true`.

## Path parameters

- `id` string, required

## Request body

- object
  - `kind` 'reboot' | 'cec-on' | 'cec-off' | 'clear-cache' | 'refresh' | 'screenshot' | 'start-mirror' | 'stop-mirror' | 'selftest' | 'pull-logs' | 'unlock-kiosk' | 'trigger' | 'set-volume' | 'set-mute' | 'set-brightness' | 'set-input' | 'rs232' | 'rekey' | 'set-proxy' | 'update-player' | 'update-app' | 'clear-obstruction' | 'add-wifi' | 'wake-screen' | 'set-timezone' | 'restart-app' | 'pause-recovery' | 'speed-test' | 'recover-peer' | 'set-fallback-wifi' | 'collect-diagnostics' | 'log-verbose', required
  - `payload` object: Per-kind payload: `set-volume` {level 0-100}, `set-brightness` {level}, `set-mute` {muted}, `set-input` {input}, … Most kinds take none.

## Response `201`

Success.

- object
  - `data` object, required
    - `id` string, required: Command id.
    - `kind` 'reboot' | 'cec-on' | 'cec-off' | 'clear-cache' | 'refresh' | 'screenshot' | 'start-mirror' | 'stop-mirror' | 'selftest' | 'pull-logs' | 'unlock-kiosk' | 'trigger' | 'set-volume' | 'set-mute' | 'set-brightness' | 'set-input' | 'rs232' | 'rekey' | 'set-proxy' | 'update-player' | 'update-app' | 'clear-obstruction' | 'add-wifi' | 'wake-screen' | 'set-timezone' | 'restart-app' | 'pause-recovery' | 'speed-test' | 'recover-peer' | 'set-fallback-wifi' | 'collect-diagnostics' | 'log-verbose', required
    - `status` 'pending', required
    - `coalesced` boolean: True when a stale pending screenshot command was reused instead.

## Other responses

- `401`: Missing, expired or revoked bearer token.
- `403`: The token lacks the permission this operation needs (see `x-brix-permission`).
- `404`: No such screen in this workspace.
- `422`: Unknown kind or invalid payload.
- `5XX`: Server error. The body carries a `requestId` to quote to support.

---

[API](https://skmtc.dev/brixsignage/apis/brix-api.md) · [All operations](https://skmtc.dev/brixsignage/apis/brix-api/llms.txt) · [OpenAPI document](https://skmtc.dev/brixsignage/apis/brix-api/revisions/02fd3665dc7d?raw)