Your First Request

This page walks through a complete API request with all available options.

Full example

curl -X POST https://api.pushtodisplay.com/api/v1/updates \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: <your-api-key>" \
  -d '{
  "boardId": "<signed-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"
    }
  ]
}'

Response — 202 Accepted

A successful request returns 202 Accepted with a confirmation payload. The message is queued for delivery to all devices currently registered to the target board.

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

Error responses

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

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.