POST /v1/updates

Sends a display update to a board. The content is delivered in real time to every device connected to that board.

POST https://api.pushtodisplay.com/v1/updates

Headers

Header	Required	Value
`Content-Type`	Yes	`application/json`
`X-Api-Key`	Yes	Your API key

Request body

Field	Type	Required	Description
`boardId`	string	No	The board to update. If omitted, your default board is used.
`blocks`	array	Yes	One or more content blocks. At least one block is required.
`panelId`	integer	No	Which panel to update (1–4). Defaults to 1.
`fullPanel`	boolean	No	When `true`, content fills the entire panel area. Defaults to `false`.
`density`	string	No	Content spacing: `compact`, `standard`, or `spacious`.
`alignX`	string	No	Horizontal alignment: `start`, `center`, or `end`.
`alignY`	string	No	Vertical alignment: `start`, `center`, or `end`.
`background`	string	No	Panel background color in hex format (`#RRGGBB`).

Block fields

Each block is a unit of text content with optional styling. Blocks are rendered in order, left to right within the panel. In fullPanel mode, blocks render top to bottom instead.

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

Examples

Simple text update

curl -X POST https://api.pushtodisplay.com/v1/updates \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: <your-api-key>" \
  -d '{
  "boardId": "<board-id>",
  "blocks": [{ "text": "System operational" }]
}'

Styled multi-block update

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

Python

import requests

requests.post(
    "https://api.pushtodisplay.com/v1/updates",
    headers={"X-Api-Key": "<your-api-key>"},
    json={
        "boardId": "<board-id>",
        "blocks": [{"text": "Build passed", "size": "large", "weight": "bold"}]
    }
)

Node.js

await fetch("https://api.pushtodisplay.com/v1/updates", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "X-Api-Key": "<your-api-key>",
  },
  body: JSON.stringify({
    boardId: "<board-id>",
    blocks: [{ text: "Build passed", size: "large", weight: "bold" }],
  }),
});

C#

using var client = new HttpClient();
client.DefaultRequestHeaders.Add("X-Api-Key", "<your-api-key>");

await client.PostAsJsonAsync(
    "https://api.pushtodisplay.com/v1/updates",
    new {
        boardId = "<board-id>",
        blocks = new[] { new { text = "Build passed", size = "large", weight = "bold" } }
    });

Response

202 Accepted

A successful request returns 202 Accepted. The message has been queued for delivery.

{
  "messageId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "enqueuedAtUtc": "2026-04-14T12:00:00Z",
  "userId": "user-abc"
}

Field	Type	Description
`messageId`	string	Unique identifier for this update.
`enqueuedAtUtc`	string	UTC timestamp when the message was queued.
`userId`	string	The authenticated user who sent the update.

Error responses

Status	Meaning
`400`	Bad request — missing or invalid fields (empty blocks, panelId out of range, invalid hex color).
`401`	Unauthorized — missing or invalid API key.
`403`	Forbidden — the API key doesn't have access to this board.
`404`	Board not found — the boardId doesn't match any board you own.
`409`	Quota exceeded — you've hit your monthly message limit for your subscription tier.
`413`	Payload too large — the request body exceeds your tier's message size limit.
`429`	Rate limited — you're sending updates faster than your tier allows. Wait and retry.

For more detail on quotas and rate limits, see Rate Limits.

Behavior notes

Real-time delivery. Updates are delivered instantly to all connected devices. There's no polling — devices receive a push the moment the message is queued.
Offline devices. A device that's offline will receive the latest update when it reconnects. Intermediate updates are not queued per device.
Panel independence. Sending an update to one panel doesn't affect other panels. Each panel holds its own content.
No idempotency. Each request creates a new update. Sending the same payload twice produces two separate updates with different message IDs.