Adds a schedule entry to a live channel.

By default, a new schedule entry cannot conflict with an existing one. Use the conflict_resolution property to resolve scheduling conflicts.

Request

Request syntax:

POST /channels/Live Channel ID/schedules

Define the following variable when submitting the above request:

VariableA variable represents a value that must be replaced. A variable consists of either a URL segment (e.g., "0001" in /0001/) or a query string value (e.g., "3" in mediaTypes=3).	Description
Live Channel ID Required	Identifies a live channel by its system-defined ID.

Request body:

Define a schedule entry through the following properties:

Name	Data Type	Description
ad_breaks	List of integers	Determines the duration for each ad break associated with the asset. Key information: Define ad break duration in the order in which ad breaks appear in the asset. Example: The following configuration indicates that the asset contains four ad breaks. It sets the duration of the first and third ad break to 90 seconds and the second and fourth ad break to 120 seconds: `'ad_breaks': [90, 120, 90, 120]`. Specify a duration for each ad break associated with the asset. This endpoint returns an error when the number of ad breaks associated with the asset do not match the number of ad breaks defined in this list. An exception to this rule occurs if you are skipping all ad breaks by setting this property to an empty list. Skip an ad break by setting its duration to 0. Example: The following configuration sets the duration of the first and last ad break to 90 seconds and skips the second ad break: `'ad_breaks': [90, 0, 90]`. Skip all ad breaks by omitting this property or setting it to an empty list.
conflict_resolution	String	Determines how scheduling conflicts are handled. Valid values are: `replace` - Overwrite previously scheduled entries with the new entry being scheduled. Overwriting a schedule entry that is currently being streamed truncates it at the point-in-time defined by the new schedule entry's start time. `trim-start` - Trim the beginning of the asset to fit within the current scheduling gap. `trim-end` - Trim from the end of the asset to fit within the current scheduling gap. Prevent previously scheduled entries from being overwritten by excluding this property from the request. Omitting this property causes our service to respond with a 409 Conflict when a scheduling conflict arises. Trimming an asset can affect the number of ads served. Specifically, we will not serve ads for an ad break positioned within a portion of the asset that is trimmed.
content_id Required	String	Used with `content_type: asset OR slicer` Identifies an asset by its system-defined ID or a Live Slicer by the ID defined within the SlicerID setting of its Live Slicer configuration file. You may only schedule another user's Live Slicer if it is streaming to a library shared with your account. Optionally specify `content_external_id` for assets instead.
content_external_id	String	Use with `content_type: asset` The `external_id` of the asset when `content_type` is set to asset. On a POST request, the system will attempt to locate the asset using the provided `external_id` only if `content_id` is not supplied.
content_owner	String	Use with `content_type: slicer` Identifies the user that owns the scheduled Live Slicer by its system-defined ID.
content_type Required	String	Determines whether the schedule entry points to an asset, ad break, or Live Slicer, or previously scheduled content. Valid values are: `ad`, `asset`, `slicer`, `replay_source`
desc	String	Defines the schedule entry's description.
dur Required	Integer	Determines the schedule entry's duration in milliseconds. Key information: This property is always required for scheduled ad breaks and Live Slicers. A schedule entry's duration cannot exceed 12 hours. content_type: asset Only - This property is required for scheduled assets when the ad_breaks property has been defined. If the ad_breaks property has not been defined, then the default value for this property is the asset's duration. Set a scheduled asset's duration to a value that is equal to or less than the sum of the asset's duration and all of its ad breaks. Ad break duration is determined by the ad_breaks property. Setting a duration that exceeds the sum of the asset's duration and all of its ad breaks generates an error. Example: The following payload indicates that the asset contains three 90 second ad breaks. `'content_type': 'asset', 'ad_breaks': [90, 90, 90]`. If the asset's duration is 25 minutes, then you should set dur to 1500270. `(25 * 60 * 1000) + 90 + 90 + 90 = 1500270`
external_id	String	Defines a schedule entry's custom ID.
offset	Integer	For `asset` entry only. The time offset in milliseconds where the playback will begin within the asset.
overwrite Deprecated	String	Determines how scheduling conflicts are handled. The conflict_resolution property takes precedence over this deprecated property.
replaced_by	String	Indicates the system-defined ID for the schedule entry that overwrote the current schedule entry.
replay_source	String	Use with `content_type: replay_source` Specifies the time frame of the content that should be played. Required values for replay_source as content_type: content_id, content_type, desc, dur, replay_source_start, replay_source_end.
replay_source_start	String	Use with `content_type: replay_source` Specifies the time (UTC) the content should begin playing. Syntax (ISO 8601): YYYY-MM-DDThh:mm:ss.sssZ
replay_source_end	String	Use with `content_type: replay_source` Specifies the time (UTC) the content should stop playing. Syntax (ISO 8601): YYYY-MM-DDThh:mm:ss.sssZ
start Required	String	Determines the schedule entry's start time (UTC). Syntax (ISO 8601): YYYY-MM-DDThh:mm:ss.sssZ Key information: Missing content slate occurs when there is a gap between scheduled entries. Set a schedule entry's start time to the previous entry's end time to prevent missing content slate. content_type: asset only - A schedule entry's start time determines the point-in-time at which the asset will start streaming. If a schedule entry's start time is in the past, then the system behaves as if the asset had been streaming since the specified start time. This means that the portion of the video that occurred in the past is excluded from your live channel's feed. You may not schedule an asset so that it ends in the past. Ensure that an asset's duration is sufficient to extend into the future when scheduling in the past. Example: If you schedule an asset 45 seconds into the past, then your live channel's feed will start streaming 45 seconds into the asset. If the asset's duration is 30 minutes, then only 29 minutes and 15 seconds of that asset's content will be included in your live channel's feed. On the other hand, if the asset's duration is 30 seconds, then this endpoint returns an error indicating that a schedule entry cannot end in the past.

Response

The response for a successful request contains the following properties:

Name	Data Type	Description
@id	String	Indicates the relative path to an endpoint that returns this schedule entry. You may not retrieve placeholder schedule entries by ID since they do not actually exist. Our system returns an invalid endpoint for placeholder schedule entries that starts with empty-.
@type	String	Returns Schedule.
ad_breaks	List of integers	Indicates the duration for each ad break associated with the asset.
content_id	String	Use with `content_type: asset OR slicer` Identifies an asset by its system-defined ID or a Live Slicer by the ID defined within the SlicerID setting of its Live Slicer configuration file.
content_owner	String	Use with `content_type: slicer` Identifies the user that owns the scheduled Live Slicer by its system-defined ID. This property is only returned for Live Slicers that belong to another user.
content_type	String	Indicates whether the schedule entry points to an asset, ad break, or Live Slicer, or previously scheduled content. Valid values are: `ad`, `asset`, `slicer`, `replay_source`
created	String	Indicates the timestamp (UTC) at which the schedule entry was created. Syntax (ISO 8601): YYYY-MM-DDThh:mm:ss.sssZ
deleted	String	include_deleted=1 Only Indicates the timestamp (UTC) at which the schedule entry was deleted. Syntax (ISO 8601): YYYY-MM-DDThh:mm:ss.sssZ
desc	String	Indicates the schedule entry's description. If the schedule entry does not have a description, then this property's value varies by the type of schedule entry. _ Asset: Indicates the name assigned to the asset. _ Ad Break: Returns Ad Break. * Slicer: Returns an empty string. Schedule entries created through the CMS are not assigned a description.
dur	Integer	Indicates the schedule entry's duration in milliseconds.
end	String	Indicates the schedule entry's end time (UTC). Syntax (ISO 8601): YYYY-MM-DDThh:mm:ss.sssZ
external_id	String	Indicates a schedule entry's custom ID.
id	String	Identifies a schedule entry by its system-defined ID.
lastmod	String	Indicates the timestamp (UTC) at which the schedule entry was last modified. Syntax (ISO 8601): YYYY-MM-DDThh:mm:ss.sssZ
owner	String	Indicates the system-defined ID for the user that owns the live channel associated with this schedule entry.
replaced_by	String	Indicates the system-defined ID for the schedule entry that overwrote the current schedule entry.
replay_source	String	Use with `content_type: replay_source` Specifies the time frame of the content that should be played. Required values for replay_source as content_type: content_id, content_type, desc, dur, replay_source_start, replay_source_end.
replay_source_end	String	Use with `content_type: replay_source` Specifies the time (UTC) the content should stop playing. Syntax (ISO 8601): YYYY-MM-DDThh:mm:ss.sssZ
replay_source_start	String	Use with `content_type: replay_source` Specifies the time (UTC) the content should begin playing. Syntax (ISO 8601): YYYY-MM-DDThh:mm:ss.sssZ
start	String	Indicates the schedule entry's start time (UTC). Syntax (ISO 8601): YYYY-MM-DDThh:mm:ss.sssZ
type	String	Indicates the type of schedule entry. Valid values are: _ Time: Identifies an actual schedule entry. _ Empty: Identifies a placeholder schedule entry that identifies a gap in the schedule.

Sample Request/Response

The code below (Python 3) shows how to add a schedule entry.

This code imports names from the api_auth module for V4 APIs (see below).

import json, requests, datetime, time
from api_auth import APICredentials, APIParams
channel_id = 'Hak3zjnPLSW5o0j8GMpzRMsa' # Replace with the ID for the desired live channel.
asset_id = 'ae071e89574248c2ab179fe73d436c3e' # Replace with the ID for the desired asset.

def convert_ts(utc_tstamp):
    """
        Convert a UTC timestamp to ISO 8601 format (YYYY-MM-DDThh:mm:ss.sZ).
        :param utc_tstamp: The UTC timestamp to convert (expected milliseconds)
    """
    iso_format = "%Y-%m-%dT%H:%M:%S.%fZ"
    try:
        _ts = float("{0:.3f}".format(utc_tstamp/1000.0))
        return "{}{}".format(datetime.datetime.utcfromtimestamp(_ts).strftime(iso_format)[:-4], "Z")
    except Exception:
        print ("Invalid timestamp: {}".format(utc_tstamp))
        raise

class ScheduleEntry:
    def __init__(self):
        self.host = "https://services.uplynk.com"

    def run(self):
        """
        Create a schedule entry.
        """
        self._create_schedule_entry()

    def _create_schedule_entry(self):
        url = "{}{}{}{}".format(self.host, "/api/v4/channels/", channel_id, "/schedules")

        start = int((time.time() + 3600) * 1000.0) # 1 hour from now
        start = convert_ts(start)

        payload = {
            'content_id': asset_id,
            'content_type': 'asset',
            'start': start
        }

        headers = {'Content-Type': 'application/json'}

        response = requests.post(
            url, params=APIParams(APICredentials()).get_params({}), data=json.dumps(payload), headers=headers
        )

        print(response.json())

ScheduleEntry().run()

Response:

{
	'@id': '/channels/Hak3zjnPLSW5o0j8GMpzRMsa/schedules/2158c7452b7841158972e019a5bd5f12',
	'@type': 'Schedule',
	'created': '2021-02-16T00:57:10.402Z',
	'lastmod': '2021-02-16T00:57:10.402Z',
	'id': '2158c7452b7841158972e019a5bd5f12',
	'owner': 'ab533864a92b46a1a286cdd49b0a9bd3',
	'content_id': 'ae071e89574248c2ab179fe73d436c3e',
	'content_type': 'asset',
	'desc': 'Sports Segment',
	'dur': 2343598,
	'external_id': '',
	'start': '2021-02-16T00:57:10.402Z',
	'end': '2021-02-16T01:36:14.000Z',
	'type': 'Time',
	'ad_breaks': []
}