Push Structured Widget Data

What you’ll accomplish

You will activate a Structured Widget Push source, authenticate a server-to-server request, replace the current snapshot, and implement safe retries.

Supported Widgets

Structured Push v2 currently supports these exact mappings:

Studio Widget	`widgetType`
Announcements	`ANNOUNCEMENTS`
Today’s Schedule	`TODAYS_SCHEDULE`
Events	`EVENTS`
Departure & Arrival	`TRANSPORT_BOARD`

Endpoint

POST https://app.layarva.com/api/public/v1/widgets/{widgetId}/data/push

The API accepts a complete replacement snapshot. Partial patches are not supported.

Prerequisites

A supported Widget added to a Design.
Content editing permission to activate its Push source.
The Widget’s Unique Widget ID.
An active Workspace API Key stored in a trusted backend or automation.

Select the Widget in Studio Canvas.
Open Properties → Data Source.
Select Layarva Push API.
Open API Setup & Usage Guide.
Copy the Unique Widget ID and the one-time full Workspace API Key.
Save and publish the Design once.

The full key cannot be displayed again. Rotate it if the value is lost or exposed.

Authenticate the request

Authorization: Bearer <workspace-api-key>
Content-Type: application/json
Idempotency-Key: agenda-20260827-revision-001

Authorization: Bearer is recommended. The route also accepts x-layarva-api-key for server integrations. Do not send both.

Send a schedule snapshot

curl -X POST \
  "https://app.layarva.com/api/public/v1/widgets/<WIDGET_ID>/data/push" \
  -H "Authorization: Bearer <WORKSPACE_API_KEY>" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: agenda-20260827-revision-001" \
  --data-binary @- <<'JSON'
{
  "pushVersion": 1,
  "widgetType": "TODAYS_SCHEDULE",
  "writeMode": "REPLACE_SNAPSHOT",
  "source": {
    "eventId": "cms-agenda-sync-20260827-001",
    "sequence": 101,
    "generatedAt": "2026-08-27T08:00:00+07:00"
  },
  "data": {
    "schemaVersion": 2,
    "title": "Today's Agenda",
    "subtitle": "Main meeting room",
    "locale": "en-US",
    "timezone": "Asia/Jakarta",
    "date": "2026-08-27",
    "updatedAt": "2026-08-27T08:00:00+07:00",
    "items": [
      {
        "id": "agenda-001",
        "startAt": "2026-08-27T09:00:00+07:00",
        "endAt": "2026-08-27T09:30:00+07:00",
        "title": "Morning Briefing",
        "location": "Meeting Room A",
        "host": "Operations",
        "status": "SCHEDULED"
      }
    ]
  }
}
JSON

Understand the request envelope

Field	Required	Rule
`pushVersion`	Yes	Integer `1`
`widgetType`	Yes	Must match the target Widget
`writeMode`	Yes	Must be `REPLACE_SNAPSHOT`
`source.eventId`	No	Source-system event identity for audit
`source.sequence`	Recommended	Non-negative safe integer that increases for each new snapshot
`source.generatedAt`	Recommended	ISO 8601 timestamp with an offset
`data`	Yes	Strict semantic Widget payload with `schemaVersion: 2`

Unknown envelope and payload fields are rejected. HTML markup is not accepted in semantic text fields.

Successful response

{
  "accepted": true,
  "widgetId": "wdg_example",
  "widgetType": "TODAYS_SCHEDULE",
  "dataRevision": 12,
  "schemaVersion": 2,
  "acceptedAt": "2026-08-27T01:00:01.125Z",
  "itemCount": 1,
  "warnings": []
}

The response also includes X-Layarva-Data-Revision. Record the revision with the source event in your integration logs.

Implement idempotency and ordering

Idempotency-Key is optional but strongly recommended for every logical snapshot.
A key contains 8–180 characters and is retained for 24 hours.
Retrying the same key with the same raw body returns the original response.
Reusing the key with a different raw body returns HTTP 409 IDEMPOTENCY_KEY_REUSED.
When source.sequence is present, it must be greater than the last accepted sequence.
An equal or lower sequence returns HTTP 409 STALE_SOURCE_SEQUENCE.

Keep the serialized body unchanged during an idempotent retry. Even harmless whitespace changes produce a different request hash.

Request limits

Maximum body size: 1 MiB.
Default rate limit: 120 Push attempts per Widget in a rolling one-minute window.
Content-Type must include application/json.
Schedule and Event arrays accept up to 500 items.
Announcement arrays accept up to 200 items.
Transport arrays accept up to 1,000 items.

Handle errors

HTTP	Representative code	Action
400	`INVALID_JSON`, `INVALID_IDEMPOTENCY_KEY`	Correct the JSON or header
401	`AUTHENTICATION_REQUIRED`	Supply a Workspace API Key
403	`WIDGET_NOT_FOUND_OR_FORBIDDEN`	Verify the key, workspace, active source, and Widget ID
409	`IDEMPOTENCY_KEY_REUSED`, `STALE_SOURCE_SEQUENCE`	Preserve the original retry body or increase sequence
413	`PAYLOAD_TOO_LARGE`	Reduce the snapshot below 1 MiB
415	`UNSUPPORTED_CONTENT_TYPE`	Send `application/json`
422	`SCHEMA_VALIDATION_FAILED`, `UNSUPPORTED_WIDGET_TYPE`	Correct the envelope or semantic payload
429	`RATE_LIMITED`	Back off for at least one minute with jitter

Do not retry schema, authentication, or conflict errors blindly. Retry HTTP 429 and transient server failures with exponential backoff, preserving the Idempotency Key and body for the same logical snapshot.

Validate the integration

Send the first snapshot and require accepted: true.
Record its dataRevision.
Confirm the Player changes after the configured Widget refresh interval.
Retry the identical request and confirm the revision does not increase.
Send a new body with a new Idempotency Key and higher sequence.
Confirm the Widget changes without republishing the Design.
Test invalid schema, stale sequence, expired key, rate limit, and temporary network failure behavior.

Important notes

This endpoint is not a general API for editing Designs, Playlists, Screens, or Publications.
The Push API changes the Widget’s semantic data, not its layout or visual style.
Legacy Widget integration dialogs can use a different endpoint and body. Use the request generated by that Widget’s Studio dialog.
Keep Static JSON valid so the Player has a safe fallback before the first accepted dynamic snapshot.

Build with Layarva

Queue API Reference

Structured Widget API Reference

Prayer Schedule API Reference

What you’ll accomplish

Supported Widgets

Endpoint

Prerequisites

Get the Widget ID and API key

Authenticate the request

Send a schedule snapshot

Understand the request envelope

Successful response

Implement idempotency and ordering

Request limits

Handle errors

Validate the integration

Important notes

​What you’ll accomplish

​Supported Widgets

​Endpoint

​Prerequisites

​Get the Widget ID and API key

​Authenticate the request

​Send a schedule snapshot

​Understand the request envelope

​Successful response

​Implement idempotency and ordering

​Request limits

​Handle errors

​Validate the integration

​Important notes

​Related guides

What you’ll accomplish

Supported Widgets

Endpoint

Prerequisites

Get the Widget ID and API key

Authenticate the request

Send a schedule snapshot

Understand the request envelope

Successful response

Implement idempotency and ordering

Request limits

Handle errors

Validate the integration

Important notes

Related guides