Planned actions

A planned action is a one-shot runtime operation deferred to a fixed instant on a Live stream that is already on air: activate or deactivate a Destination, apply or clear a logo, switch to or from a blackout, switch the input source, push a metadata value, or set ad values.

Planned actions compose with Schedules instead of extending them: a Schedule decides when a Live stream is on air; a planned action decides what changes during that window. Each action fires at most once — there is no recurrence. To repeat an operation, create several actions; an interval is a pair (for example, a blackout from 10:00 to 10:30 is a blackout on action at 10:00 plus a blackout off action at 10:30).

Every action is the deferred equivalent of a runtime operation you can also run immediately from the On air panel or its runtimeOptions/* endpoints — same parameters, same effect, only the moment changes.

What an action can do

The Action picker in the dialog offers nine operations. Each maps 1:1 to a runtime endpoint fired at the planned time:

State-changing actions (Destinations, logo, blackout, source switch) are persisted on the Live stream when they fire — the applied state survives an encoder restart exactly like the equivalent manual operation. Metadata and ad-value actions are one-off pulses with no persisted state.

Creating a planned action

Below the form, the Planned for … list shows the Live stream's pending actions with their Name, Action, Fire at and Status. When completed or failed actions exist, a Show all / Show pending only toggle reveals the recent history. Each pending row exposes Edit, Enable / Disable and Delete.

On the calendar

Planned actions render on the Scheduler's Week and Day views as dashed instant chips at their Fire at time — distinct from the solid duration blocks of Schedule occurrences. The colour follows the status: amber while pending, green when completed, red on error; a disabled action is dimmed with its name struck through. Clicking a chip opens the manager.

Lifecycle and rules

An action's status moves from pending to exactly one terminal state:

• The Live stream must be on air at fire time. An action whose broadcast is not running when its time comes ends in error — it is never re-armed for a later start.
• Execution window. An action fires within [fireAt, fireAt + catchUpSeconds] (catchUpSeconds defaults to 120, accepts 0–86400). If the platform could not fire it inside the window — for example the Control host was down — the action expires to error instead of firing late: a late blackout or ad cue can be worse than none.
• Granularity. Due actions are picked up within the following minute of their Fire at time. Same-instant actions fire in a deterministic order: state-changing actions before metadata/ad-value pulses.
• Terminal actions are immutable. Editing, enabling or disabling a completed or error action returns 409. Deleting is allowed in any state.
• Retention. Terminal actions are removed automatically 24 hours after their fire time — like one-shot Schedules, they clean up after themselves.

API surface

Planned actions are a first-class REST resource — everything the dialog does is available to integrators:

The PlannedAction object carries livestreamId, name, command, payload (validated per command at creation), fireAt (ISO-8601 — send a timezone offset to be explicit), catchUpSeconds, enabled, plus the read-only status, resultDetail, firedAt, createdBy and createdAt. Validation failures return 400; an unknown Live stream or action returns 404; mutating a terminal action returns 409.

Example — plan a blackout that keeps the live audio, tonight at 22:00:

curl -X POST "https://<your-host>/c21apiv2/livestreams/<livestreamId>/actions" \
  -H "Authorization: Bearer <YOUR_API_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Evening cartela",
    "command": "blackout_on",
    "payload": { "mode": "File", "file": "cartela.mp4", "keep_input_audio": true },
    "fireAt": "2026-07-03T22:00:00+02:00"
  }'

From a voice or chat agent

The MCP server's voice profile exposes the planned-action surface to agents: addLivestreamAction, getLivestreamActions, getPlannedAction, updatePlannedAction and deletePlannedAction. An operator can create, reschedule ("move it to 22:30") or cancel an action by voice; enablePlannedAction / disablePlannedAction stay on the larger profiles.

FAQ