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

> Choose a Ready Playlist version, create a playback schedule, then check, edit, pause or delete it.

## What a Schedule does

A Schedule plays an **exact Ready Playlist version** on a Channel at a specified time. After a timed window ends, the Channel returns to its default content.

## Before you start

Use the [Postman setup](https://docs.layarva.com/developers/platform-quickstart.md). Set `platform_base` to `https://api.layarva.com/api/platform/v1/workspaces/YOUR_WORKSPACE_ID` and use 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](https://docs.layarva.com/developers/platform-request-keys.md) for each new change. GET needs no body or operation key.

Permissions are `schedules.read`, `schedules.create`, `schedules.update` and `schedules.delete` as needed. Creating or updating also needs `publications.execute` and must follow your workspace's publishing/approval rules.

## Step 1: Prepare the Channel and scheduled content

1. Choose a Channel with **default Ready content** to return to. A new Channel's first manual publication sets this default if none exists.
2. Prepare a **different Playlist** for the scheduled content using [Playlist → Ready](https://docs.layarva.com/developers/platform-playlists-publication.md).
3. Save the Channel ID as `channel_id` and the scheduled Ready version ID as `scheduled_version_id`.

Do not use the same Playlist as the Channel's default. If the Channel has no default, a Schedule can remain `DRAFT` instead of being enabled. Check your Channel with **GET** `/channels/{{channel_id}}`; `defaultPlaylistVersionId` identifies its default version.

## Step 2: Create a weekly Schedule

Send **POST** `{{platform_base}}/schedules`:

```json theme={null}
{
  "name": "Weekday evening promotion",
  "channelId": "{{channel_id}}",
  "playlistVersionId": "{{scheduled_version_id}}",
  "scheduleType": "WEEKLY",
  "timezone": "Asia/Jakarta",
  "weeklyWindows": [
    {
      "daysOfWeek": [1, 2, 3, 4, 5],
      "startTime": "17:00",
      "endTime": "19:00"
    }
  ],
  "paused": false
}
```

This means Monday–Friday, 17:00–19:00 in Jakarta. Days are `0=Sunday`, `1=Monday`, through `6=Saturday`.

A successful response is **201 Created**. Save `data.id` as `schedule_id`. Check `data.controlState`; creation alone does not prove a device is playing the scheduled content.

### Other timing types

| `scheduleType` | Fields and behavior |
| - | - |
| `ALWAYS` | Applies continuously while enabled; omit one-time dates and weekly windows |
| `ONE_TIME` | Supply `startAtUtc`; optional `endAtUtc` must be later. Use timestamps with `Z` or an explicit timezone offset |
| `WEEKLY` | Supply at least one weekly window and its weekdays |

For example, a one-time Schedule can use:

```json theme={null}
{
  "name": "Special event",
  "channelId": "{{channel_id}}",
  "playlistVersionId": "{{scheduled_version_id}}",
  "scheduleType": "ONE_TIME",
  "timezone": "Asia/Jakarta",
  "startAtUtc": "2026-11-01T10:00:00+07:00",
  "endAtUtc": "2026-11-01T12:00:00+07:00",
  "paused": false
}
```

Replace the example dates with your event's dates. Overlapping Schedules on a Channel are rejected; review existing timing before creating another.

## Step 3: List and check the Schedule

Send **GET** `{{platform_base}}/schedules?channelId={{channel_id}}&limit=25`.

Read one Schedule with **GET** `{{platform_base}}/schedules/{{schedule_id}}`. Save `data.updatedAt` as `schedule_updated_at` before editing.

* `DRAFT`: not enabled; check default content and dependencies.
* `ACTIVE` or `ENABLED`: enabled for execution, not necessarily playing at this moment.
* `PAUSED`: timing is retained but execution is paused.

A list filter `controlState=ENABLED` selects enabled Schedules, including records returned as `ACTIVE`. If available, `lifecycleStatus` describes timing separately from control state.

Check [Screen playback](https://docs.layarva.com/developers/platform-screens.md#step-5-check-connection-and-playback) to confirm delivery at the scheduled time.

## Step 4: Edit, pause or resume

Read the Schedule first, then send **PATCH** `{{platform_base}}/schedules/{{schedule_id}}`:

```json theme={null}
{
  "expectedUpdatedAt": "{{schedule_updated_at}}",
  "name": "Updated evening promotion",
  "weeklyWindows": [
    {
      "daysOfWeek": [1, 2, 3, 4, 5],
      "startTime": "18:00",
      "endTime": "20:00"
    }
  ]
}
```

Send the complete desired `weeklyWindows` array when changing it. For a pause, the body can be just:

```json theme={null}
{
  "expectedUpdatedAt": "{{schedule_updated_at}}",
  "paused": true
}
```

To resume, use `paused: false`. Save the new `updatedAt` after every successful change. If there is a conflict, read the current Schedule and review it before retrying; do not reuse an outdated timestamp.

## Step 5: Delete the Schedule

Send **DELETE** `{{platform_base}}/schedules/{{schedule_id}}` with `{}` and `schedules.delete`.

This removes future scheduled execution. It is not an immediate stop command for content already playing on a disconnected device. Campaign-managed Schedules must be managed through Layarva.

> [!NOTE]
>
> Keep the key and its issuing account authorized for future scheduled runs. Expired or revoked keys no longer authorize those runs. Use a suitable expiry or Never expire, and revoke keys you no longer need.

## Related guides

* [Create Ready content and publish](https://docs.layarva.com/developers/platform-playlists-publication.md)
* [Channels and Locations](https://docs.layarva.com/developers/platform-channels-locations.md)
* [Screen playback](https://docs.layarva.com/developers/platform-screens.md)


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