---
title: "Send a command to many screens"
method: POST
path: "/v1/screens/commands"
tags: ["screens"]
---

# Send a command to many screens

`POST /v1/screens/commands`

## Request

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

Queue the same command across many screens in a single request, using `screenIds`, `kind`, and an optional `payload`. Screen IDs you do not have permission to edit are silently dropped from the request rather than causing an error. Use this instead of sending one request per screen.

Queues one command on many screens. Unknown or out-of-reach ids are silently dropped. Risky kinds (set-proxy, set-input, rs232, add-wifi) on a large cohort go to a small canary batch first and the rest are staged.

**Notes.**
- When no requested screen is reachable the answer is 200 (not 201) with `{ issued: 0, commandIds: [] }`.

## 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.
  - `screenIds` string[], required

## Response `201`

Success.

- object
  - `data` object, required
    - `issued` integer, required
    - `commandIds` string[], required
    - `staged` integer: Canary rollouts: commands held behind the canary.
    - `rolloutId` string
    - `canary` true

## Other responses

- `401`: Missing, expired or revoked bearer token.
- `403`: The token lacks the permission this operation needs (see `x-brix-permission`).
- `422`: Unknown kind, invalid payload, or empty/oversized `screenIds`.
- `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)