> ## Documentation Index > Fetch the complete documentation index at: https://docs.layarva.com/llms.txt > Use this file to discover all available pages before exploring further. # Replace a Structured Widget snapshot > Replaces the complete semantic-data snapshot for one active Structured Widget v2 source. Partial patches are not supported. ## OpenAPI ````yaml /api/openapi.yaml post /api/public/v1/widgets/{widgetId}/data/push openapi: 3.1.0 info: title: Layarva Public API version: 1.1.0 description: >- Implemented Queue, Structured Widget Push, and prayer-schedule public endpoints. Dashboard server actions are not public APIs. servers: - url: https://app.layarva.com security: [] paths: /api/public/v1/widgets/{widgetId}/data/push: post: tags: - Structured widgets summary: Replace a Structured Widget snapshot description: >- Replaces the complete semantic-data snapshot for one active Structured Widget v2 source. Partial patches are not supported. operationId: replaceStructuredWidgetSnapshot parameters: - name: widgetId in: path required: true description: Unique Widget ID copied from the Studio API integration dialog. schema: type: string - name: Idempotency-Key in: header required: false description: >- Strongly recommended stable identity for one logical snapshot. Retained for 24 hours. schema: type: string minLength: 8 maxLength: 180 requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/StructuredWidgetPushRequest' example: 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 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 status: SCHEDULED responses: '200': description: Snapshot accepted or an identical idempotent request replayed headers: X-Layarva-Data-Revision: description: Monotonic revision of the accepted Widget snapshot. schema: type: integer content: application/json: schema: $ref: '#/components/schemas/StructuredWidgetPushResult' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': description: Widget is unavailable to the supplied Workspace API Key content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' '409': description: >- Idempotency Key was reused with another body or source sequence did not increase content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' '413': description: Request exceeds 1 MiB content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' '415': description: Content-Type is not application/json content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' '422': description: Push envelope, Widget type, or strict semantic payload is invalid content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' '429': $ref: '#/components/responses/RateLimited' security: - workspaceBearer: [] - workspaceApiKeyHeader: [] components: schemas: StructuredWidgetPushRequest: type: object additionalProperties: false required: - pushVersion - widgetType - writeMode - data properties: pushVersion: type: integer const: 1 widgetType: type: string enum: - ANNOUNCEMENTS - TODAYS_SCHEDULE - EVENTS - TRANSPORT_BOARD writeMode: type: string const: REPLACE_SNAPSHOT source: $ref: '#/components/schemas/StructuredWidgetSourceMetadata' data: oneOf: - $ref: '#/components/schemas/AnnouncementPayloadV2' - $ref: '#/components/schemas/SchedulePayloadV2' - $ref: '#/components/schemas/EventPayloadV2' - $ref: '#/components/schemas/TransportBoardPayloadV2' description: >- Strict semantic payload. Its shape must match widgetType and the target Widget. StructuredWidgetPushResult: type: object required: - accepted - widgetId - widgetType - dataRevision - schemaVersion - acceptedAt - itemCount - warnings properties: accepted: type: boolean const: true widgetId: type: string widgetType: type: string enum: - ANNOUNCEMENTS - TODAYS_SCHEDULE - EVENTS - TRANSPORT_BOARD dataRevision: type: integer minimum: 1 schemaVersion: type: integer const: 2 acceptedAt: type: string format: date-time itemCount: type: integer minimum: 0 warnings: type: array items: type: string ErrorEnvelope: type: object properties: error: type: object required: - code - message properties: code: type: string message: type: string StructuredWidgetSourceMetadata: type: object additionalProperties: false properties: eventId: type: string minLength: 1 maxLength: 180 sequence: type: integer minimum: 0 description: Must be greater than the last accepted source sequence. generatedAt: type: string format: date-time AnnouncementPayloadV2: type: object additionalProperties: false required: - schemaVersion - items properties: schemaVersion: type: integer const: 2 title: type: string maxLength: 240 subtitle: type: string maxLength: 500 locale: type: string description: BCP 47 locale timezone: type: string description: IANA timezone updatedAt: type: string format: date-time expiresAt: type: string format: date-time footerNote: type: string maxLength: 1000 items: type: array maxItems: 200 items: type: object additionalProperties: false required: - id description: At least title or body is required. properties: id: type: string maxLength: 180 title: type: string maxLength: 240 body: type: string maxLength: 2000 priority: type: string enum: - INFO - IMPORTANT - WARNING - URGENT priorityLabel: type: string maxLength: 80 category: type: string maxLength: 120 location: type: string maxLength: 240 effectiveFrom: type: string format: date-time effectiveUntil: type: string format: date-time SchedulePayloadV2: type: object additionalProperties: false required: - schemaVersion - date - items properties: schemaVersion: type: integer const: 2 title: type: string maxLength: 240 subtitle: type: string maxLength: 500 locale: type: string description: BCP 47 locale timezone: type: string description: IANA timezone date: type: string format: date updatedAt: type: string format: date-time expiresAt: type: string format: date-time footerNote: type: string maxLength: 1000 items: type: array maxItems: 500 items: type: object additionalProperties: false required: - id - startAt - title properties: id: type: string maxLength: 180 startAt: type: string format: date-time endAt: type: string format: date-time title: type: string maxLength: 240 location: type: string maxLength: 240 host: type: string maxLength: 240 category: type: string maxLength: 120 status: type: string enum: - SCHEDULED - IN_PROGRESS - COMPLETED - DELAYED - CANCELLED notes: type: string maxLength: 1000 EventPayloadV2: type: object additionalProperties: false required: - schemaVersion - items properties: schemaVersion: type: integer const: 2 title: type: string maxLength: 240 subtitle: type: string maxLength: 500 locale: type: string description: BCP 47 locale timezone: type: string description: IANA timezone updatedAt: type: string format: date-time expiresAt: type: string format: date-time footerNote: type: string maxLength: 1000 items: type: array maxItems: 500 items: type: object additionalProperties: false required: - id - title - startAt properties: id: type: string maxLength: 180 title: type: string maxLength: 240 startAt: type: string format: date-time endAt: type: string format: date-time location: type: string maxLength: 240 category: type: string maxLength: 120 organizer: type: string maxLength: 240 speaker: type: string maxLength: 240 status: type: string enum: - UPCOMING - ONGOING - COMPLETED - POSTPONED - CANCELLED description: type: string maxLength: 2000 TransportBoardPayloadV2: type: object additionalProperties: false required: - schemaVersion - items properties: schemaVersion: type: integer const: 2 title: type: string maxLength: 240 subtitle: type: string maxLength: 500 locale: type: string description: BCP 47 locale timezone: type: string description: IANA timezone updatedAt: type: string format: date-time expiresAt: type: string format: date-time footerNote: type: string maxLength: 1000 items: type: array maxItems: 1000 items: type: object additionalProperties: false required: - id - movement - transportType description: At least one of scheduledAt, expectedAt, or actualAt is required. properties: id: type: string maxLength: 180 movement: type: string enum: - DEPARTURE - ARRIVAL transportType: type: string enum: - AIR - RAIL - COMMUTER_RAIL - METRO - LRT_TRAM - BUS - BRT - FERRY - MONORAIL - OTHER scheduledAt: type: string format: date-time expectedAt: type: string format: date-time actualAt: type: string format: date-time serviceCode: type: string maxLength: 80 routeLine: type: object additionalProperties: false properties: shortName: type: string maxLength: 80 longName: type: string maxLength: 240 color: type: string pattern: ^#[0-9A-Fa-f]{6}$ textColor: type: string pattern: ^#[0-9A-Fa-f]{6}$ operator: type: string maxLength: 240 serviceType: type: object additionalProperties: false required: - code - label properties: code: type: string maxLength: 80 label: type: string maxLength: 120 origin: $ref: '#/components/schemas/TransportPlace' destination: $ref: '#/components/schemas/TransportPlace' via: type: array maxItems: 30 items: $ref: '#/components/schemas/TransportPlace' boardingPoint: type: object additionalProperties: false required: - type - label properties: type: type: string enum: - GATE - PLATFORM - TRACK - BAY - BERTH - PIER - STOP - ZONE - OTHER label: type: string maxLength: 80 terminal: type: string maxLength: 80 status: type: object additionalProperties: false required: - code properties: code: type: string enum: - SCHEDULED - ON_TIME - EXPECTED - APPROACHING - AT_PLATFORM - BOARDING - FINAL_CALL - CLOSED - DELAYED - DEPARTED - ARRIVED - CANCELLED - DIVERTED - PLATFORM_CHANGED - SKIPPED - SUSPENDED - UNKNOWN label: type: string maxLength: 120 delayMinutes: type: integer minimum: -1440 maximum: 10080 remarks: type: string maxLength: 500 vehicleLabel: type: string maxLength: 120 boardingTime: type: string format: date-time checkInCounter: type: string maxLength: 80 baggageBelt: type: string maxLength: 80 occupancy: type: string enum: - EMPTY - MANY_SEATS - FEW_SEATS - STANDING - FULL - NOT_ACCEPTING - UNKNOWN zone: type: string maxLength: 80 updatedAt: type: string format: date-time TransportPlace: type: object additionalProperties: false required: - name properties: name: type: string maxLength: 240 code: type: string maxLength: 32 responses: BadRequest: description: Invalid request content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' Unauthorized: description: Authentication failed content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' RateLimited: description: Rate limit exceeded content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' securitySchemes: workspaceBearer: type: http scheme: bearer bearerFormat: Workspace API key workspaceApiKeyHeader: type: apiKey in: header name: x-layarva-api-key ````