Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/ErsatzTV/legacy/llms.txt

Use this file to discover all available pages before exploring further.

The Scripted Schedule API is invoked by the ErsatzTV scripted schedule engine when building a playout for a channel that uses a Python script. Each playout build gets a unique buildId UUID, and all endpoints for that build are rooted at /api/scripted/playout/build/{buildId}/. The API mirrors the scripted playout’s operation sequence: first declare content sources, then place items into the schedule using timing controls, and optionally configure EPG grouping, graphics, and watermarks.
These endpoints are consumed by the etv_client Python library, which is imported inside a scripted schedule script. You do not typically call them directly. See Scripted Schedules for the Python-level API.

​
Common Path Parameter

Every endpoint below shares this path parameter as part of its base route:
​
buildId
string (uuid)
required
A UUID that uniquely identifies the current playout build session. Generated by ErsatzTV when the scripted schedule engine starts a build.

​
Context

​
GET /context

Returns the current state of the playout build. Operation ID: GetContext. Returns a PlayoutContext object. 
curl "http://localhost:8409/api/scripted/playout/build/550e8400-e29b-41d4-a716-446655440000/context"
​
currentTime
string (date-time)
required
The current scheduling cursor position within the playout build. This advances as content is added.
​
startTime
string (date-time)
required
The start time of this playout build window.
​
finishTime
string (date-time)
required
The end time of this playout build window. The build is complete when currentTime reaches finishTime.
​
isDone
boolean
required
true when currentTime has reached or passed finishTime, indicating the playout build is complete.

​
Content Addition

Content addition endpoints register a named content source (identified by a key) against a library object — a collection, show, smart collection, search query, or playlist. Once registered, the key is used in scheduling operations to reference that content.

​
POST /add_collection

Registers a manual collection as a named content source. Operation ID: AddCollection.
​
key
string
required
Unique name used to reference this content throughout the scripted schedule (e.g. "action_movies").
​
collection
string
required
The name of an existing manual collection in ErsatzTV.
​
order
string
Playback order for items in the collection. Supported values: Chronological, Shuffle.
curl -X POST "http://localhost:8409/api/scripted/playout/build/{buildId}/add_collection" \
  -H "Content-Type: application/json" \
  -d '{"key": "action", "collection": "Action Movies", "order": "Shuffle"}'

​
POST /add_marathon

Registers a marathon content source that groups content from multiple GUIDs and/or search queries. Operation ID: AddMarathon.
​
key
string
required
Unique name used to reference this content.
​
groupBy
string
required
How to group the combined content. Valid values: show, season, artist, album.
​
itemOrder
string
Playback order within each group. Supported values: Chronological, Shuffle.
​
guids
object
Dictionary of external content identifiers ({ "imdb": ["tt0111161", "tt0068646"] }).
​
searches
array of strings
List of search query strings to include in the marathon.
​
playAllItems
boolean
When true, plays all items from one group before advancing to the next. When false, plays one item from each group in rotation.
​
shuffleGroups
boolean
When true, randomizes the order of groups.

​
POST /add_multi_collection

Registers an existing multi-collection as a named content source. Operation ID: AddMultiCollection.
​
key
string
required
Unique name used to reference this content.
​
multiCollection
string
required
The name of the existing multi-collection in ErsatzTV.
​
order
string
Playback order. Supported values: Chronological, Shuffle.

​
POST /add_playlist

Registers an existing playlist as a named content source. Operation ID: AddPlaylist.
​
key
string
required
Unique name used to reference this content.
​
playlist
string
required
The name of the existing playlist in ErsatzTV.
​
playlistGroup
string
required
The name of the playlist group that contains the named playlist.

​
POST /create_playlist

Creates a new ad-hoc playlist inline and registers it as a named content source. Unlike add_playlist, this endpoint constructs the playlist from a list of (content key, count) pairs rather than referencing an existing playlist by name. Operation ID: CreatePlaylist.
​
key
string
required
Unique name used to reference this content throughout the scripted schedule.
​
items
array of objects
required
Ordered list of playlist items. Each item specifies a content key and how many items to draw from it.Item fields:
  • content (string, required) — the key of a previously registered content source.
  • count (integer, required) — how many items to take from that content source per playlist cycle.
curl -X POST "http://localhost:8409/api/scripted/playout/build/{buildId}/create_playlist" \
  -H "Content-Type: application/json" \
  -d '{
    "key": "rotation",
    "items": [
      {"content": "action_movies", "count": 2},
      {"content": "commercials", "count": 1}
    ]
  }'
Returns 200 OK on success, or 404 Not Found if the buildId is not active.

​
POST /add_search

Registers a search query as a named content source. Operation ID: AddSearch.
​
key
string
required
Unique name used to reference this content.
​
query
string
required
The ErsatzTV search query string (e.g. genre:Action year:>2010 type:movie).
​
order
string
Playback order. Supported values: Chronological, Shuffle.

​
POST /add_smart_collection

Registers an existing smart collection as a named content source. Operation ID: AddSmartCollection.
​
key
string
required
Unique name used to reference this content.
​
smartCollection
string
required
The name of the existing smart collection in ErsatzTV.
​
order
string
Playback order. Supported values: Chronological, Shuffle.

​
POST /add_show

Registers a show (identified by external GUIDs) as a named content source. Operation ID: AddShow.
​
key
string
required
Unique name used to reference this content.
​
guids
object
required
Dictionary mapping provider name to GUID value (e.g. {"imdb": "tt0903747"}).
​
order
string
Playback order. Supported values: Chronological, Shuffle.

​
POST /add_all

Adds all remaining items from the named content source into the schedule. Returns the updated PlayoutContext. Operation ID: AddAll.
​
content
string
required
The key of the content source to add.
​
fillerKind
string
Marks the scheduled items as a specific filler type, influencing EPG grouping. Valid values correspond to FillerKind enum entries.
​
customTitle
string
Overrides the EPG title for all added items.
​
disableWatermarks
boolean
When true, disables watermarks for these scheduled items.

​
POST /add_count

Adds a specific number of items from the named content source. Returns the updated PlayoutContext. Operation ID: AddCount.
​
content
string
required
The key of the content source.
​
count
integer
required
Number of items to add from the content source.
​
fillerKind
string
Optional filler kind for EPG grouping.
​
customTitle
string
Optional EPG title override.
​
disableWatermarks
boolean
Disable watermarks for these items.

​
POST /add_duration

Adds content from the named source until a specified duration is filled. Returns the updated PlayoutContext. Operation ID: AddDuration.
​
content
string
required
The key of the content source.
​
duration
string
required
The amount of time to fill (e.g. "01:00:00" for one hour).
​
fallback
string
Content key used to fill remaining unscheduled time. One item is looped and trimmed to fit exactly.
​
trim
boolean
When true, the last item is trimmed to fit exactly within the specified duration.
​
discardAttempts
integer
When trim is false, the number of items to discard when searching for one that fits.
​
stopBeforeEnd
boolean
When false, allows the last item to run over the specified duration.
​
offlineTail
boolean
When true, remaining time after the last fitting item is left as offline (unscheduled).
​
fillerKind
string
Optional filler kind for EPG grouping.
​
customTitle
string
Optional EPG title override.
​
disableWatermarks
boolean
Disable watermarks for these items.

​
Timing Control

Timing endpoints advance or hold the scheduling cursor to precise points in time, padding schedules with content or leaving gaps.

​
POST /pad_to_next

Adds content until the next occurrence of a specific minute interval (e.g. the next :00, :30, or :15 boundary). Returns the updated PlayoutContext. Operation ID: PadToNext.
​
content
string
required
The key of the content source to use for padding.
​
minutes
integer
required
The minute interval to pad to (e.g. 30 means pad to the next half-hour boundary).
​
fallback
string
Fallback content key for exact-fit filling.
​
trim
boolean
Trim the last item to fit the interval boundary exactly.
​
discardAttempts
integer
Number of items to discard when searching for a fitting item (when trim is false).
​
stopBeforeEnd
boolean
When false, allows overrun of the interval boundary.
​
offlineTail
boolean
Leave remaining time after fitting items as offline.
​
fillerKind
string
Filler kind for EPG grouping.
​
customTitle
string
EPG title override.
​
disableWatermarks
boolean
Disable watermarks.

​
POST /pad_until

Adds content until a specified time of day. Returns the updated PlayoutContext. Operation ID: PadUntil.
​
content
string
required
The key of the content to use for padding.
​
when
string
required
Time of day to pad until (e.g. "22:00:00").
​
tomorrow
boolean
When true and the current time is already past when, pads until that time the following day. When false, no items are added.
​
fallback
string
Fallback content for exact-fit filling.
​
trim
boolean
Trim the last item to fit exactly.
​
discardAttempts
integer
Items to discard when searching for a fit.
​
stopBeforeEnd
boolean
Allow overrun of the target time.
​
offlineTail
boolean
Leave remaining time offline.
​
fillerKind
string
Filler kind for EPG grouping.
​
customTitle
string
EPG title override.
​
disableWatermarks
boolean
Disable watermarks.

​
POST /pad_until_exact

Adds content until an exact datetime. Returns the updated PlayoutContext. Operation ID: PadUntilExact.
​
content
string
required
The key of the content to use for padding.
​
when
string (date-time)
required
The exact ISO 8601 datetime to pad until.
​
fallback
string
Fallback content for exact-fit filling.
​
trim
boolean
Trim the last item to fit exactly.
​
discardAttempts
integer
Items to discard when searching for a fit.
​
stopBeforeEnd
boolean
Allow overrun of the target time.
​
offlineTail
boolean
Leave remaining time offline.
​
fillerKind
string
Filler kind for EPG grouping.
​
customTitle
string
EPG title override.
​
disableWatermarks
boolean
Disable watermarks.

​
POST /wait_until

Inserts unscheduled (offline) time until the specified time of day. Returns the updated PlayoutContext. Operation ID: WaitUntil.
​
when
string
required
The time of day to wait until (e.g. "06:00:00"). Parsed as TimeOnly.
​
tomorrow
boolean
When true, if when has already passed, wait until that time the next day.
​
rewindOnReset
boolean
When true, the playout cursor is allowed to move backward when the playout is reset.

​
POST /wait_until_exact

Inserts unscheduled time until an exact datetime. Returns the updated PlayoutContext. Operation ID: WaitUntilExact.
​
when
string (date-time)
required
The exact ISO 8601 datetime to wait until.
​
rewindOnReset
boolean
When true, allows the cursor to rewind on playout reset.

​
GET /peek_next/

Returns the duration of the next item from a named content source without advancing the scheduling cursor. Useful for making conditional scheduling decisions in a script. Operation ID: PeekNext.
​
content
string
required
The key of the content source to peek at.
curl "http://localhost:8409/api/scripted/playout/build/{buildId}/peek_next/action_movies"
​
content
string
required
The content key that was peeked.
​
milliseconds
integer (int64)
required
Duration of the next item in milliseconds.
Returns 404 Not Found if the content key does not exist or the collection is empty.

​
POST /skip_items

Skips a specific number of items in a content source without scheduling them. Operation ID: SkipItems.
​
content
string
required
The key of the content source.
​
count
integer
required
The number of items to skip.

​
POST /skip_to_item

Advances the position in a content source to a specific season and episode. Operation ID: SkipToItem.
​
content
string
required
The key of the content source (must reference a show).
​
season
integer
required
The target season number.
​
episode
integer
required
The target episode number within the season.

​
EPG & Overlays

​
POST /start_epg_group

Starts a new EPG group, causing subsequent scheduled items to be grouped together as a single logical program in the Electronic Programme Guide. Operation ID: StartEpgGroup.
​
advance
boolean
When true, starts a new EPG group. When false, continues within the current group.
​
customTitle
string
Custom title to apply to all items within this EPG group.

​
POST /stop_epg_group

Closes the current EPG group. Items scheduled after this call will start a new group in the EPG. Operation ID: StopEpgGroup. No request body required.

​
POST /graphics_on

Enables one or more named graphics elements (on-screen overlays) for subsequently scheduled items. Operation ID: GraphicsOn.
​
graphics
array of strings
required
List of graphics element names to activate.
​
variables
object
Key-value pairs that are passed as variables to the graphics elements (e.g. for templated overlays).

​
POST /graphics_off

Disables one or more named graphics elements. Operation ID: GraphicsOff.
​
graphics
array of strings
List of graphics element names to deactivate. If null or empty, all graphics elements are turned off.

​
POST /watermark_on

Activates one or more named watermarks for subsequently scheduled items. Operation ID: WatermarkOn.
​
watermark
array of strings
required
List of existing watermark names to turn on.

​
POST /watermark_off

Deactivates one or more named watermarks. Operation ID: WatermarkOff.
​
watermark
array of strings
List of watermark names to turn off. If null or empty, all scripted watermarks are turned off.

​
POST /pre_roll_on

Activates a pre-roll playlist, causing the named playlist to play before each subsequent content item. Operation ID: PreRollOn.
​
playlist
string
required
The key of a scripted playlist to use as pre-roll.

​
POST /pre_roll_off

Deactivates the active pre-roll playlist. No request body required. Operation ID: PreRollOff.

​
PlayoutContext Fields (Shared Response)

Many scheduling endpoints return a PlayoutContext representing the updated build state after the operation:
​
currentTime
string (date-time)
required
Updated scheduling cursor position after this operation completed.
​
startTime
string (date-time)
required
Start of the build window (unchanged by scheduling operations).
​
finishTime
string (date-time)
required
End of the build window (unchanged by scheduling operations).
​
isDone
boolean
required
true when currentTime has reached finishTime.

Build docs developers (and LLMs) love

Get started for freeTalk to us