> ## 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.

# Manage Playlists and Publish to Channels

> Create a Playlist, add content, Set as Ready, publish to a Channel and check Screen playback.

## The complete workflow

**Library content → Playlist draft → Ready version → Publication on a Channel → Screen playback.**

| Name | Meaning | ID to save in Postman |
| - | - | - |
| Asset | Your uploaded Library file | `asset_id` |
| Playlist | The editable content list and playback order | `playlist_id` |
| Ready version | A fixed copy of the Playlist, ready to publish | `playlist_version_id` |
| Channel | The destination followed by your Screens | `channel_id` |
| Publication | A release of one exact Ready version to one Channel | `publication_id` |

> [!NOTE]
>
> “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](https://docs.layarva.com/developers/platform-request-keys.md) 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](https://docs.layarva.com/developers/platform-library.md). Wait for `COMMITTED`, then use the returned `data.assetId`.

| `sourceType` | `sourceId` to use |
| - | - |
| `image`, `video`, `audio`, `lottie` | The matching Library asset ID |
| `design` | The ID of an existing Design in your workspace's Studio |

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`:

```json theme={null}
{
  "name": "Lobby welcome",
  "description": "Welcome content for the lobby",
  "items": []
}
```

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.

> [!TIP]
>
> 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}}`:

```json theme={null}
{
  "expectedDraftRevision": {{draft_revision}},
  "items": [
    {
      "sourceType": "image",
      "sourceId": "{{asset_id}}",
      "durationSeconds": 10,
      "enabled": true
    }
  ]
}
```

`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.

> [!WARNING]
>
> `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`:

```json theme={null}
{
  "expectedDraftRevision": {{draft_revision}}
}
```

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:

| `data.status` | Next action |
| - | - |
| `PENDING` or `RUNNING` | Wait a few seconds and check again |
| `SUCCEEDED` | Save `data.result.playlistVersionId` as `playlist_version_id` |
| `FAILED` or `CANCELLED` | Stop; inspect `data.failureCode` and fix the cause |

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`:

```json theme={null}
{
  "name": "Lobby",
  "description": "Main lobby Screens"
}
```

Save `data.id` as `channel_id`. See [Channels and Locations](https://docs.layarva.com/developers/platform-channels-locations.md) 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`:

```json theme={null}
{
  "playlistVersionId": "{{playlist_version_id}}",
  "note": "Please review the lobby welcome content"
}
```

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`:

```json theme={null}
{
  "playlistVersionId": "{{playlist_version_id}}",
  "channelId": "{{channel_id}}"
}
```

> [!NOTE]
>
> 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.

> [!WARNING]
>
> `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.

## Related guides

* [Upload files and choose a folder](https://docs.layarva.com/developers/platform-library.md)
* [Channels and Locations](https://docs.layarva.com/developers/platform-channels-locations.md)
* [Schedules](https://docs.layarva.com/developers/platform-schedules.md)
* [Screens and pairing](https://docs.layarva.com/developers/platform-screens.md)
* [Operation UUID examples](https://docs.layarva.com/developers/platform-request-keys.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.