API Reference

Push To Display API

v1 — Current

Send structured display messages to boards via a single HTTP endpoint. Authenticate with a push token, target specific panels, and control layout rendering.

Quick start

Getting started

1. Sign in and open the admin portal.
2. Create a board — you'll receive a signed board ID.
3. Issue a push token under the Tokens section.
4. Bind a display device to the board using the mobile app.
5. Send your first API request (see below).

Authentication

API authentication

All API requests require a push token passed in the X-Api-Key header. Push tokens are scoped to your account and can be issued, listed, and revoked through the admin portal.

X-Api-Key: <your-push-token>

Endpoint

`POST` /api/v1/updates

Queues a display update for every device mapped to the requested board. Updates are delivered in real time via SignalR.

Request body

Request fields

Field	Type	Required	Description
`boardId`	string	Yes	Signed board ID from the admin portal.
`segments`	array	Yes	One or more content segments to display. At least one segment required.
`panelId`	integer	No	Target panel (1–4). Defaults to 1. Selects which panel to update in multi-panel layouts.
`fullPanel`	boolean	No	When true, the content fills the entire panel area. Defaults to false.
`density`	string	No	Content density. Allowed: `compact`, `standard`, `spacious`.
`alignX`	string	No	Horizontal alignment. Allowed: `start`, `center`, `end`.
`alignY`	string	No	Vertical alignment. Allowed: `start`, `center`, `end`.
`background`	string	No	Panel background color in hex format (#RRGGBB).

Segment object

Segment fields

Each segment represents a line or block of text in the display message.

Field	Type	Required	Description
`text`	string	Yes	The text content to display.
`size`	string	No	Text size. Allowed: `small`, `medium`, `large`.
`weight`	string	No	Font weight. Allowed: `regular`, `semibold`, `bold`.
`color`	string	No	Text color in hex format (#RRGGBB).
`background`	string	No	Segment background color in hex format (#RRGGBB).

Example

Example request

curl -X POST https://api.pushtodisplay.com/api/v1/updates \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: <your-push-token>" \
  -d '{
  "boardId": "<signed-board-id>",
  "panelId": 1,
  "fullPanel": false,
  "density": "standard",
  "alignX": "center",
  "alignY": "center",
  "background": "#0F172A",
  "segments": [
    {
      "text": "Deploy completed",
      "color": "#E8FFF6",
      "background": "#0A4A36",
      "size": "large",
      "weight": "bold"
    },
    {
      "text": "Queue: 12 | Escalations: 0",
      "color": "#061A13"
    }
  ]
}'

Response

Response — 202 Accepted

A successful request returns 202 Accepted with a confirmation payload. The message is queued and delivered to all devices registered to the board.

{
  "messageId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "deviceIds": ["device-001", "device-002"],
  "enqueuedAtUtc": "2026-04-14T12:00:00Z",
  "userId": "user-abc",
  "boardId": "<signed-board-id>"
}

Errors

Error responses

Status	Meaning
`400`	Bad request — missing or invalid fields (boardId, segments, panelId range, invalid hex color).
`401`	Unauthorized — missing or invalid push token in X-Api-Key header.
`403`	Forbidden — the push token does not have access to the specified board.
`404`	Board not found — the boardId does not match any registered board.

Layouts

Display layout presets

Boards support four layout presets configured through the mobile app. Use the panelId field to target specific panels within each layout.

Layout	Panels	Valid panelId	Description
Full Screen	1	1	Single panel fills the entire display.
Stacked	2	1–2	Top (1) and bottom (2) horizontal panels.
Side by Side	2	1–2	Left (1) and right (2) vertical panels.
2×2 Grid	4	1–4	Top-left (1), top-right (2), bottom-left (3), bottom-right (4).

Notes

Additional notes

Content-Type. All requests must include Content-Type: application/json.

Delivery. Messages are delivered in real time to all devices currently connected to the board. Devices that are offline will receive the latest message when they reconnect.

Idempotency. Each request generates a unique messageId. The same payload sent twice will produce two separate display updates.

Need help? Contact support or email [email protected].