Skip to main content

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

  1. Create a Platform / Workspace API key, not a Widget key.
  2. Set platform_base to https://api.layarva.com/api/platform/v1/workspaces/YOUR_WORKSPACE_ID.
  3. Set Authorization → Bearer Token to your Platform key.
  4. For POST, PATCH and DELETE, add Content-Type: application/json and an Idempotency-Key. Use Body → raw → JSON.
  5. 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.
The examples use Postman variables such as {{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:
The response is 201 Created. Save data.id as playlist_id and data.draftRevision as draft_revision. This creates an editable draft. An empty Playlist cannot be marked Ready.
You can also include content in items during creation. The separate step below shows how to add or edit content later.

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.
items replaces the complete draft list; it does not append automatically. Include every item you want to keep. Preserve existing item id values and send only supported fields: id, sourceType, sourceId, durationSeconds, enabled and optional transition. Do not send display-only fields such as name from a GET response.
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:
The response is 202 Accepted, not “Ready completed.” Save 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:
Save 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. For OWNER_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:
Save 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.
The response is 202 Accepted. Save 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, playbackEnabled and the Screen’s recent lastPingAt. A new Screen may have no playback report yet.
202, operation SUCCEEDED, or a Publication record does not prove playback on every Screen. The Publication’s recorded status is not a per-device live delivery report. A disconnected Screen may still play older content. Check the Player report and the actual display when physical playback matters.
For a new Channel with no default content, its first manual publish sets the default Ready version. Later publishes do not automatically replace an existing default. Schedules need default content to return to after a time window ends.

Edit or remove later

  1. Read /playlists/{{playlist_id}}/draft.
  2. PATCH changes with the latest expectedDraftRevision.
  3. Request Ready again and wait for the new playlistVersionId.
  4. Publish that version and check playback.
Use DELETE /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.