Skip to main content

Before you start

Use the Postman setup: platform_base is https://api.layarva.com/api/platform/v1/workspaces/YOUR_WORKSPACE_ID, with your Platform key as the Bearer token. For POST, PATCH and DELETE, use Body → raw → JSON, Content-Type: application/json and a new Idempotency-Key per new change. GET needs no body or operation key. For the main workflow, select screens.read, screens.create, screens.pair, screens.update and screens.playback. Other actions have their own permissions listed below. Your plan limits apply; all assigned IDs must belong to the same workspace. Queue-managed Screens are protected.

Step 1: Choose the delivery mode

The steps below use CLOUD. Cloud pairing codes are not used to pair an Edge-served LAN display or an offline-package Screen.

Step 2: List or create the Screen record

List existing Screens with GET {{platform_base}}/screens?limit=25, or search with /screens?q=Lobby&limit=25. To create an unpaired Cloud Screen, send POST {{platform_base}}/screens:
Create or choose these IDs using the Channel and Location guide. They are optional for a Cloud Screen; omit fields you have not assigned. The response is 201 Created. Save data.id as screen_id. Creating the record does not pair the physical Player.

Step 3: Pair the actual Cloud Player

  1. Open Layarva Player on the device you own.
  2. Read its current six-digit pairing code.
  3. Send POST {{platform_base}}/screens/{{screen_id}}/pair:
Set pairing_code to the real code as a string, including leading zeroes. Do not generate a random number or use a code from another device. Keep it private. If it expires, obtain a fresh code from the Player; do not repeatedly retry the old code.

Alternative: create and pair in one request

If you have not already created a Screen record, send POST {{platform_base}}/screens/pair with screens.pair:
Save the returned data.id. Choose either this one-request flow or the create-then-pair flow above; do not use both for the same device.

Step 4: Assign or change Channel and Location

Send PATCH {{platform_base}}/screens/{{screen_id}}:
This changes the assignments, not the Playlist itself. Publish Ready content to the Channel so assigned Screens can receive it. You can also change name and clientId. Where permitted, null clears an assignment. Do not change delivery mode through PATCH; use the dedicated delivery endpoint below.

Optional: configure output size and fit

Include a complete displayConfig in your create or PATCH request:
This PATCH example uses 1920×1080, centered content, 100% zoom and zero offsets. Width supports 320–7680, height 240–4320, zoom 25–400%, and offsets −100 to 100. Fit modes are FIT, FILL, STRETCH, CUSTOM; anchors include CENTER and the eight edge/corner positions.

Step 5: Check connection and playback

Read GET {{platform_base}}/screens/{{screen_id}}. Check paired, status, lastPingAt and assignments. status represents current connectivity; do not use storedStatus as proof of a recent heartbeat. Read GET {{platform_base}}/screens/{{screen_id}}/playback:
  • playbackEnabled shows whether playback is enabled.
  • desiredPublicationId is the expected release.
  • activePublicationId is the release reported active by the Player.
  • state and updatedAt help interpret the report. A new Screen may have no report yet.
A successful pairing or command response is not proof of physical playback. Check recent reports and the actual display.

Step 6: Enable playback or control audio

Send POST {{platform_base}}/screens/{{screen_id}}/playback:
Use false to disable playback. For audio, send POST /screens/{{screen_id}}/audio with {"videoMuted": false}; true mutes video audio. Both changes require screens.playback.

Other Screen actions

Use the same authenticated JSON setup and a new operation UUID for each new change. Do not change force to true simply to bypass a delivery conflict. Review the handover requirements first. This endpoint does not convert a Screen into offline-package mode. Unlock codes are not returned by reads; do not log them. Deleting/archiving is not a remote wipe of a disconnected device. Offline lease revocation is enforced when the Player reconnects.

Filter and paginate Screen lists

Examples: /screens?channelId={{channel_id}}&limit=25, /screens?locationId={{location_id}}&status=ONLINE, or /screens?deliveryMode=EDGE&edgeDeviceId={{edge_id}}. For more pages, send the returned page.nextCursor as after. Stop when it is null. See all supported filters.