# Pearl REST API control scheduled CMS events

Scheduled events come from the content management system configured on the Pearl device. The API lists them and can force-start, stop, pause, resume, and extend an event outside its scheduled window.

*Applies to: Pearl-2, Pearl Mini, Pearl Nexus, Pearl Nano.*

**Listing events.**

```
GET /api/v2.0/schedule/events
```

| Parameter | Effect |
| --- | --- |
| `from` / `to` | Earliest scheduled start and latest scheduled finish |
| `limit` | Maximum number of events returned |
| `status` | Return only events with a given status |
| `extstatus` | Include extended status information |
| `full` | Include all available event fields rather than a subset |
| `cmsinfo` | Include a `capabilities` array in `extra_data` |

**Event statuses** are `scheduled` (upcoming), `running` (ongoing), `paused`, and `finished`. A finished event may still have asset uploads in progress.

**Fetching one event.** `GET /schedule/events/{eventId}` accepts either an event ID or an alias. Aliases can be used as a parameter but never appear in a response:

| Alias | Meaning |
| --- | --- |
| `upcoming` | The next scheduled event |
| `ongoing` | The ongoing event, running or paused |
| `running` | The running ongoing event |
| `paused` | The paused ongoing event |
| `completed` | The most recent completed event |

**Control endpoints and their state requirements.**

| Method and path | Requirement |
| --- | --- |
| `POST /schedule/events/{eventId}/control/start` | Only an event with status `scheduled` can be started |
| `POST /schedule/events/{eventId}/control/stop` | Only an event with status `running` or `paused` can be stopped |
| `POST /schedule/events/{eventId}/control/pause` | Only an event with status `running` can be paused |
| `POST /schedule/events/{eventId}/control/resume` | Only an event with status `paused` can be resumed |
| `POST /schedule/events/{eventId}/control/extend` | Only an event with status `running` or `paused` can be extended |

Calling a control endpoint on an event in the wrong state returns HTTP 409, and an unknown event ID returns 404.

Pausing and resuming Kaltura and EchoVideo events requires firmware 4.24.6 or newer.

EchoVideo scheduled events can be started early only up to five minutes before the scheduled start time.

There are no REST API commands for YuJa CMS functions.

**Extending an event.** Send the number of seconds to add to the current finish time:

```json
{ "finish": 300 }
```

If an extended event overlaps with the next scheduled event, an error is returned.

> product: pearl-family · topic: cms-integration · source: pearl-rest-api.md · updated: Oct 7, 2026