---
title: "Trigger a screen interaction"
method: POST
path: "/v1/screens/{id}/trigger"
tags: ["screens"]
---

# Trigger a screen interaction

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

## Request

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

Send a real-time trigger to a screen: `refresh`, `next`, `go-to-scene`, or `send-event`. The screen receives it immediately.

## Path parameters

- `id` string, required

## Request body

- object: A trigger. Fields other than `kind` apply to the kinds named.
  - `kind` 'refresh' | 'next' | 'prev' | 'go-to-page' | 'go-to-scene' | 'send-event', required
  - `page` integer: `go-to-page`: 1–100.
  - `sceneId` string: `go-to-scene`: the scene to show.
  - `event` string: `send-event`: the event name the content listens for.
  - `payload` string: `send-event`: an optional string payload.
  - `overlay` object: A popup shown over what is playing for `seconds`, then removed. The content underneath does not restart.
    - `contentKind` 'media' | 'app' | 'canvas', required
    - `contentId` string, required
    - `seconds` number: 1–600 (clamped); default 15.
    - `position` 'center' | 'top' | 'bottom' | 'top-left' | 'top-right' | 'bottom-left' | 'bottom-right': Default `center`.
    - `params` object: Values passed to the content, e.g. `{ "table": "4" }`.

## Response `201`

Success.

- object
  - `data` object, required
    - `id` string, required: The command id.
    - `kind` 'trigger', required
    - `trigger` object, required: The trigger as stored (only the fields its kind uses).
      - `kind` string, required
      - `page` integer
      - `sceneId` string
      - `event` string
      - `payload` string
    - `overlay` object
      - `contentKind` 'media' | 'app' | 'canvas', required
      - `contentId` string, required
      - `seconds` integer, required: 1–600; default 15.
      - `position` 'center' | 'top' | 'bottom' | 'top-left' | 'top-right' | 'bottom-left' | 'bottom-right', required
      - `params` object: Values passed to the content, e.g. `{ "table": "4" }`.

## Other responses

- `401`: Missing, expired or revoked bearer token.
- `403`: The token lacks the permission this operation needs (see `x-brix-permission`).
- `422`: Not a valid trigger, or the overlay content is not in this workspace.
- `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)