The complete workflow
Library content → Playlist draft → Ready version → Publication on a Channel → Screen playback.“Immutable” means the Ready version and published content are fixed. Editing a draft does not change an existing Ready version or Publication. Release changes by creating another Ready version and publishing it again. Immutable does not mean a device cannot go offline or report an error.
Before you start: Postman setup
- Create a Platform / Workspace API key, not a Widget key.
- Set
platform_basetohttps://api.layarva.com/api/platform/v1/workspaces/YOUR_WORKSPACE_ID. - Set Authorization → Bearer Token to your Platform key.
- For POST, PATCH and DELETE, add
Content-Type: application/jsonand anIdempotency-Key. Use Body → raw → JSON. - Use a new operation UUID for each new change. Reuse it only when retrying that same request with the same body. GET needs no body or Idempotency-Key.
{{playlist_id}}. Save real IDs from your own responses; example IDs from another workspace will not work.
For this example, select library.read, playlists.read, playlists.create, playlists.update, channels.read, channels.create, publications.read and publications.execute. Add library.upload to upload a file, publications.request if approval is required, and screens.read to check playback. The key’s account must also be allowed to perform these actions.
Step 1: Choose Library content
Send GET{{platform_base}}/assets?type=IMAGE&limit=25.
Choose an item in data and save its id as asset_id. Search by name with q, for example /assets?type=IMAGE&q=poster&limit=25.
For a new file, follow the upload guide. Wait for COMMITTED, then use the returned data.assetId.
Do not use a file URL as
sourceId. Studio Designs are not Library assets; Design creation and listing are not provided by this API. Existing Library video/audio files can be used even when their format is not supported by API upload.
Step 2: Create the Playlist
Send POST{{platform_base}}/playlists:
data.id as playlist_id and data.draftRevision as draft_revision.
This creates an editable draft. An empty Playlist cannot be marked Ready.
Step 3: Add content to the draft
Read GET{{platform_base}}/playlists/{{playlist_id}}/draft and save the latest data.draftRevision as draft_revision.
Send PATCH {{platform_base}}/playlists/{{playlist_id}}:
draft_revision must contain the returned number. Leave the variable without quotation marks. Save the new data.draftRevision returned by PATCH.
Items play in array order. Add more objects for more content; use sourceType: "design" with a Design ID for Studio content.
If there is a revision conflict, read the draft again and review the changes before retrying with a new operation UUID. Do not keep resending a stale revision.
Step 4: Set as Ready
Read the latest draft revision. Ensure at least one item is enabled, sources exist, and content does not mix portrait and landscape orientations. Send POST{{platform_base}}/playlists/{{playlist_id}}/ready:
data.id as ready_operation_id: it is an operation ID, not a Playlist version ID.
Check GET {{platform_base}}/operations/{{ready_operation_id}} using the same key:
Set a reasonable timeout; do not poll indefinitely or publish before Ready succeeds. Reading a Ready operation needs
playlists.read.
To use an existing Ready version, list GET /playlists?ready=true&limit=25, then GET /playlists/{{playlist_id}}/versions?limit=25. Each version’s id is a playlistVersionId. ready=true does not mean newer draft edits are already included.
Step 5: Choose or create the Channel
List GET{{platform_base}}/channels?limit=25, or send POST {{platform_base}}/channels:
data.id as channel_id. See Channels and Locations for editing and deletion.
Step 6: Request approval only if required
Skip this step for direct publishing. ForOWNER_ADMIN_ONLY, the key’s account must be an Owner or Admin.
For APPROVAL_REQUIRED, send POST {{platform_base}}/playlists/{{playlist_id}}/approval-requests with publications.request:
data.id as approval_id. An authorized, different reviewer approves it in Layarva; the API cannot approve its own request.
Check GET {{platform_base}}/approval-requests/{{approval_id}}. Continue only when data.status is APPROVED. Approval belongs to that exact Ready version.
Step 7: Publish to the Channel
Send POST{{platform_base}}/publications:
This performs “add Playlist to Channel and publish.” No extra add-to-Channel request is needed. Do not PATCH a Channel with a Playlist ID; Channel editing only changes its supported details.
data.id as publish_operation_id, then check GET {{platform_base}}/operations/{{publish_operation_id}} using the same key. Reading a publish operation needs publications.read.
Wait for SUCCEEDED, then save data.result.publicationId as publication_id. Stop on FAILED or CANCELLED and inspect failureCode.
A Publication uses the exact Ready version selected. Later edits do not overwrite it; publish again to create a new release.
Step 8: Confirm the release and playback
Read GET{{platform_base}}/publications/{{publication_id}}. Confirm playlistVersionId and channelId match your choices. List releases with GET /publications?channelId={{channel_id}}&limit=25.
List GET {{platform_base}}/screens?channelId={{channel_id}}&limit=25. For a Screen, read GET {{platform_base}}/screens/{{screen_id}}/playback:
desiredPublicationId: the Publication the Screen is expected to use.activePublicationId: the Publication the Player has reported as active.- Also check
state,playbackEnabledand the Screen’s recentlastPingAt. A new Screen may have no playback report yet.
Edit or remove later
- Read
/playlists/{{playlist_id}}/draft. - PATCH changes with the latest
expectedDraftRevision. - Request Ready again and wait for the new
playlistVersionId. - Publish that version and check playback.
/playlists/{{playlist_id}} with {} and playlists.delete to archive an unused Playlist. A Playlist referenced by a Publication, Channel, Schedule or other protected resource cannot simply be removed. Queue-managed Playlists must be managed through Queue Management.

