Blackout API

Blackouts are incompatible with live channels that can leverage schedule entries.
Learn more.

Use the Blackout API, which is a versioned API, to:

Administer audience and superaudiences via the following endpoints:

Endpoint	Description
Add Audience POST /audiences	Adds an audience or superaudience.
Delete Audience DELETE /audiences/Audience ID	Deletes an audience or superaudience.
Get Audience GET /audiences/Audience ID	Retrieves a specific audience or superaudience.
Get Multiple Audiences GET /audiences	Retrieves one or more audiences or superaudiences.
Update Audience PATCH /audiences/Audience ID	Updates a specific audience or superaudience.

Administer rules via the following endpoints:

Endpoint	Description
Add Rule POST /rules	Adds a rule.
Delete Rule DELETE /rules/Rule ID	Deletes a rule.
Get Multiple Rules GET /rules	Retrieves one or more rules.
Get Rule GET /rule/Rule ID	Retrieves a specific rule.
Update Rule PATCH /rules/Rule ID	Updates a specific rule.

Administer blackout configurations via the following endpoints:

Endpoint	Description
Add Blackout POST /channels/Live Channel ID/blackouts	Adds a blackout configuration to a live channel.
Delete Blackout DELETE /channels/Live Channel ID/blackouts/Blackout ID	Deletes a blackout configuration from a live channel.
Get Blackout GET /channels/Live Channel ID/blackouts/Blackout ID	Retrieves a blackout configuration associated with a specific live channel.
Get Multiple Blackouts GET /channels/Live Channel ID/blackouts	Retrieves either all or recently updated blackout configurations associated with a specific live channel.
Update Blackout PATCH /channels/Live Channel ID/blackouts/Blackout ID	Updates a specific blackout configuration.

Learn more about blackout and how to set it up through audiences, rules, and blackouts.

Base URL

Use the following base URL:

https://services.uplynk.com/api/v4

Audiences

Automate the following audience-related tasks:

create | retrieve all | retrieve | update | delete

Add Audience

Adds one of the following:

Audience
1. Set the type parameter to Single.
2. Define the conditions under which a viewer qualifies for this audience through the match_type parameter and the following parameters:
  
  country_codes | devices | dma_codes | ip_networks | zip_codes
Superaudience
1. Set the type parameter to Multiple.
2. Set the sub_audiences parameter to the set of audiences that will be associated with this superaudience.
3. Determine the conditions under which a viewer qualifies for this superaudience through the match_type parameter.

Request

Request syntax:

POST /audiences

Request body parameters:

Pass the following request body parameters:

Name	Data Type	Description
country_codes	List of string values	Audience only Identifies the set of countries associated with this audience. Specify each country by its two character country code (ISO 3166). View a list of country codes.
desc Required	String	Defines the name of the audience or superaudience.
devices	List of string values	Audience only Identifies the set of devices associated with this audience. Specify a name or description for each desired device. Each value in this List will be compared against the value defined for the repl.cbdevice playback URL parameter.
dma_codes	List of string values	Audience only Identifies the set of designated market areas (DMA) associated with this audience. Specify the ID for each desired United States DMA. Request Nielsen DMA data.
external_id	String	Defines the external ID associated with this audience or superaudience.
ip_networks	List of string values	Audience only Identifies the set of IP addresses or subnets associated with this audience. Specify each desired IP address or subnet.
match_type	String	Determines the set of criteria that will be required to qualify a viewer for this audience or superaudience. Valid values are: ALL \| ANY \| NONE Learn more.
sub_audiences	List of string values	Superaudience only Defines the set of audiences associated with this superaudience. Specify the system-defined ID for each desired audience. Learn more.
type	String	Determines whether this configuration is an audience or a superaudience. Valid values are: Single \| Multiple Learn more.
zip_codes	List of string values	Audience only Identifies the set of United States zip codes associated with this audience. Specify each desired 5 digit zip code.

Authentication

Pass a digital signature based off of msg.

Learn more.

Response

A successful request returns a 201 Created response that contains the following properties:

Name	Data Type	Description
@id	String	Indicates the relative path to an endpoint that returns this audience or superaudience.
@type	String	Returns Audience.
country_codes	List of string values	Audience only Indicates the set of countries associated with this audience. Each value identifies a country by its two character country code (ISO 3166). View a list of country codes.
created	String	Indicates the timestamp (UTC) at which the audience or superaudience was created. Syntax (ISO 8601): YYYY-MM-DDThh:mm:ss.sssZ
desc	String	Indicates the name of the audience or superaudience.
devices	List of string values	Audience only Indicates the set of devices associated with this audience. Each value identifies a device by its name or description. Each value in this List will be compared against the value defined for the repl.cbdevice playback URL parameter.
dma_codes	List of string values	Audience only Indicates the set of designated market areas (DMA) associated with this audience. Each value identifies a United States DMS by its ID. Request Nielsen DMA data.
external_id	String	Indicates the external ID associated with this audience or superaudience.
id	String	Identifies this audience or superaudience by its system-defined ID.
ip_networks	List of string values	Audience only Indicates the set of IP addresses or subnets associated with this audience. Each value identifies either an IP address or IP network.
match_type	String	Determines the set of criteria that will be required to qualify a viewer for this audience or superaudience. Valid values are: ALL \| ANY \| NONE Learn more.
owner	String	Indicates the system-defined ID for the user that owns this audience or superaudience.
sub_audiences	List of string values	Superaudience only Indicates the set of audiences associated with this superaudience. Each value identifies an audience by its system-defined ID. Learn more.
type	String	Indicates whether this configuration is an audience or a superaudience. Valid values are: Single \| Multiple Learn more.
zip_codes	List of string values	Audience only Indicates the set of United States zip codes associated with this audience. Each value identifies a zip code.

Sample Request/Response

Call the add_audience module (Python 3) to create an audience. This module imports names from the api_auth module.

import json, requests
from api_auth import APICredentials, APIParams

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

    def run(self):
        """
        Create a audience.
        """
        self._create_audience()

    def _create_audience(self):
        url = "{}{}".format(self.host, "/api/v4/audiences")

        payload = {
            'desc': 'My New audience', # Replace with the audience's name.
            'country_codes': ['US', 'CA', 'MX'], # Replace with the desired country codes.
            'external_id': 'NorthAmerica', # Replace with the audience's external ID.
            'match_type': 'ANY' # Determines when a viewer qualifies for this audience.            
        }

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

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

        print(response.json())

Audience().run()

Response:

{
	'@id': '/api/v4/audiences/abc11672b78c4d03bf4756ec3ea46a22',
	'@type': 'Audience',
	'created': '2021-06-30T22:32:09.362Z',
	'id': 'cc1c1672b78c4d03bf4756ec3ea46a45',
	'owner': 'abc123def456ghi789jkl012mno345pq',
	'match_type': 'ANY',
	'external_id': 'NorthAmerica',
	'country_codes': ['CA', 'MX', 'US'],
	'dma_codes': [],
	'desc': 'My New audience',
	'devices': [],
	'ip_networks': [],
	'zip_codes': [],
	'sub_audiences': [],
	'type': 'Single'
}

Delete Audience

Deletes an audience or superaudience.

Request

Request syntax:

DELETE /audiences/Audience ID

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
Audience ID Required	Identifies an audience by its system-defined or external ID. Use the Get Multiple Audiences endpoint to retrieve a list of audiences/superaudience and their IDs.

Description

Audience ID

Required

Identifies an audience by its system-defined or external ID.

Use the Get Multiple Audiences endpoint to retrieve a list of audiences/superaudience and their IDs.

Authentication

Pass a digital signature based off of msg.

Learn more.

Response

A successful request returns a 200 OK response that contains the following properties:

Name	Data Type	Description
@id	String	Indicates the relative path to the requested endpoint.
@type	String	Returns Audience.
message	String	Returns Deleted.

Sample Request/Response

Call the delete_audience module (Python 3) to delete an audience or superaudience. This module imports names from the api_auth module.

import json, requests
from api_auth import APICredentials, APIParams
audience_id = 'Hak3zjnPLSW5o0j8GMpzRMsa' # Replace with the ID for the desired audience.

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

    def run(self):
        """
        Deletes an audience.
        """
        self._delete_audience()

    def _delete_audience(self):
        url = "{}{}{}".format(self.host, "/api/v4/audiences/", audience_id)
 
        response = requests.delete(
            url, params=APIParams(APICredentials()).get_params({})
        )

        print(response.json())

DeleteAudience().run()

Response:

{
	'@id': '/api/v4/audiences/Hak3zjnPLSW5o0j8GMpzRMsa',
	'@type': 'Audience',
	'message': 'Deleted'
}

Get Audience

Retrieves an audience or a superaudience.

Request

Request syntax:

GET /audiences/Audience ID

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
Audience ID Required	Identifies an audience by its system-defined or external ID. Use the Get Multiple Audiences endpoint to retrieve a list of audiences/superaudience and their IDs.

Description

Audience ID

Required

Identifies an audience by its system-defined or external ID.

Use the Get Multiple Audiences endpoint to retrieve a list of audiences/superaudience and their IDs.

Authentication

Pass a digital signature based off of msg.

Learn more.

Response

A successful request returns a 200 OK response that contains the following properties:

Name	Data Type	Description
@id	String	Indicates the relative path to an endpoint that returns this audience or superaudience.
@type	String	Returns Audience.
country_codes	List of string values	Audience only Indicates the set of countries associated with this audience. Each value identifies a country by its two character country code (ISO 3166). View a list of country codes.
created	String	Indicates the timestamp (UTC) at which the audience or superaudience was created. Syntax (ISO 8601): YYYY-MM-DDThh:mm:ss.sssZ
desc	String	Indicates the name of the audience or superaudience.
devices	List of string values	Audience only Indicates the set of devices associated with this audience. Each value identifies a device by its name or description. Each value in this List will be compared against the value defined for the repl.cbdevice playback URL parameter.
dma_codes	List of string values	Audience only Indicates the set of designated market areas (DMA) associated with this audience. Each value identifies a United States DMS by its ID. Request Nielsen DMA data.
external_id	String	Indicates the external ID associated with this audience or superaudience.
id	String	Identifies this audience or superaudience by its system-defined ID.
ip_networks	List of string values	Audience only Indicates the set of IP addresses or subnets associated with this audience. Each value identifies either an IP address or IP network.
match_type	String	Determines the set of criteria that will be required to qualify a viewer for this audience or superaudience. Valid values are: ALL \| ANY \| NONE Learn more.
owner	String	Indicates the system-defined ID for the user that owns this audience or superaudience.
sub_audiences	List of string values	Superaudience only Indicates the set of audiences associated with this superaudience. Each value identifies an audience by its system-defined ID. Learn more.
type	String	Indicates whether this configuration is an audience or a superaudience. Valid values are: Single \| Multiple Learn more.
zip_codes	List of string values	Audience only Indicates the set of United States zip codes associated with this audience. Each value identifies a zip code.

Sample Request/Response

Call the get_audience module (Python 3) to retrieve a specific audience. This module imports names from the api_auth module.

import json
import requests
from api_auth import APICredentials, APIParams

class GetReplaceMeREPLACEME:
    def __init__(self):


import json, requests
from api_auth import APICredentials, APIParams
audience_id = '02ed9f65570746528e7b3d0628960025' # Replace with the ID for the desired audience.

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

    def run(self):
        self._get_audience()

    def _get_audience(self):        
        url = "{}{}{}".format(self.host, "/api/v4/audiences/", audience_id)

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

        response = requests.get(
            url, params=APIParams(APICredentials()).get_params({}), headers=headers
        )
  
        print(response.json())
  
Audience().run()

Response:

{
	'@id': '/api/v4/audiences/abc11672b78c4d03bf4756ec3ea46a22',
	'@type': 'Audience',
	'created': '2021-06-30T22:32:09.362Z',
	'id': 'cc1c1672b78c4d03bf4756ec3ea46a45',
	'owner': 'abc123def456ghi789jkl012mno345pq',
	'match_type': 'ANY',
	'external_id': 'NorthAmerica',
	'country_codes': ['CA', 'MX', 'US'],
	'dma_codes': [],
	'desc': 'My New audience',
	'devices': [],
	'ip_networks': [],
	'zip_codes': [],
	'sub_audiences': [],
	'type': 'Single'
}

Get Multiple Audiences

Retrieves one or more audiences or superaudiences.

Request

GET /audiences?page=Page Number&page_size=Items Per Page

Request query string parameters:

Pass the following optional request query string parameters:

Name	Description
page=Page Number	Filter the response by a specific page. Replace this variable with the desired page. Use the navigation links within the @links object to navigate between pages. Default Value: 1
page_size=Items Per Page	Sets the number of audience configurations that may be included on each page. The number of items per page determines the number of pages that may be returned. The maximum page size is 40. Default value: 40

Name

Description

page=Page Number

Filter the response by a specific page. Replace this variable with the desired page.

Use the navigation links within the @links object to navigate between pages.

Default Value:

page_size=Items Per Page

Sets the number of audience configurations that may be included on each page.

The number of items per page determines the number of pages that may be returned.

The maximum page size is 40.

Default value:

Authentication

Pass a digital signature based off of msg.

Learn more.

Response

A successful request returns a 200 OK response that contains the following properties:

Name	Data Type	Description
@id	String	Indicates the relative path to the requested endpoint.
@type	String	Returns Collection.
items	List of dictionaries	Contains a list of audience configurations.
total_items	Integer	Indicates the total number of audience configurations.

items List

The items list describes each audience configuration via the following properties:

Name	Data Type	Description
@id	String	Indicates the relative path to an endpoint that returns this audience or superaudience.
@type	String	Returns Audience.
country_codes	List of string values	Audience only Indicates the set of countries associated with this audience. Each value identifies a country by its two character country code (ISO 3166). View a list of country codes.
created	String	Indicates the timestamp (UTC) at which the audience or superaudience was created. Syntax (ISO 8601): YYYY-MM-DDThh:mm:ss.sssZ
desc	String	Indicates the name of the audience or superaudience.
devices	List of string values	Audience only Indicates the set of devices associated with this audience. Each value identifies a device by its name or description. Each value in this List will be compared against the value defined for the repl.cbdevice playback URL parameter.
dma_codes	List of string values	Audience only Indicates the set of designated market areas (DMA) associated with this audience. Each value identifies a United States DMS by its ID. Request Nielsen DMA data.
external_id	String	Indicates the external ID associated with this audience or superaudience.
id	String	Identifies this audience or superaudience by its system-defined ID.
ip_networks	List of string values	Audience only Indicates the set of IP addresses or subnets associated with this audience. Each value identifies either an IP address or IP network.
match_type	String	Determines the set of criteria that will be required to qualify a viewer for this audience or superaudience. Valid values are: ALL \| ANY \| NONE Learn more.
owner	String	Indicates the system-defined ID for the user that owns this audience or superaudience.
sub_audiences	List of string values	Superaudience only Indicates the set of audiences associated with this superaudience. Each value identifies an audience by its system-defined ID. Learn more.
type	String	Indicates whether this configuration is an audience or a superaudience. Valid values are: Single \| Multiple Learn more.
zip_codes	List of string values	Audience only Indicates the set of United States zip codes associated with this audience. Each value identifies a zip code.

Sample Request/Response

Call the get_multiple_audiences module (Python 3) to retrieve multiple audiences. This module imports names from the api_auth module.

import json, requests
from api_auth import APICredentials, APIParams

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

    def run(self):
        self._get_multiple_audiences()

    def _get_multiple_audiences(self):        
        url = "{}{}".format(self.host, "/api/v4/audiences")

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

        response = requests.get(
            url, params=APIParams(APICredentials()).get_params({}), headers=headers
        )
  
        print(response.json())
  
Audience().run()

Response:

{
	'@id': '/api/v4/audiences',
	'@type': 'Collection',
	'items': [{
			'@id': '/api/v4/audiences/e1fa7c93edda4541937899ad032b9051',
			'@type': 'Audience',
			'id': 'e1fa7c93edda4541937899ad032b9051',
			'created': '2021-06-30T17:57:51.765Z',
			'owner': 'abc123def456ghi789jkl012mno345pq',
			'match_type': 'ANY',
			'external_id': '',
			'country_codes': [],
			'dma_codes': [],
			'desc': 'Beverly Hills',
			'devices': [],
			'ip_networks': [],
			'zip_codes': ['90503'],
			'sub_audiences': [],
			'type': 'Single'
		}, {
			'@id': '/api/v4/audiences/abc11672b78c4d03bf4756ec3ea46a22',
			'@type': 'Audience',
			'created': '2021-06-30T22:32:09.362Z',
			'id': 'cc1c1672b78c4d03bf4756ec3ea46a45',
			'owner': 'abc123def456ghi789jkl012mno345pq',
			'match_type': 'ANY',
			'external_id': 'NorthAmerica',
			'country_codes': ['CA', 'MX', 'US'],
			'dma_codes': [],
			'desc': 'My New audience',
			'devices': [],
			'ip_networks': [],
			'zip_codes': [],
			'sub_audiences': [],
			'type': 'Single'
		}
	],
	'total_items': 2
}

Update Audience

Updates an audience or a superaudience.

You may not convert an audience to a superaudience or vice versa. As a result, you may not modify the type property.

Request

Request syntax:

PATCH /audiences/Audience ID

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
Audience ID Required	Identifies an audience by its system-defined or external ID. Use the Get Multiple Audiences endpoint to retrieve a list of audiences/superaudience and their IDs.

Description

Audience ID

Required

Identifies an audience by its system-defined or external ID.

Use the Get Multiple Audiences endpoint to retrieve a list of audiences/superaudience and their IDs.

Request body parameters:

Pass the following request body parameters:

Name	Data Type	Description
country_codes	List of string values	Audience only Identifies the set of countries associated with this audience. Specify each country by its two character country code (ISO 3166). View a list of country codes.
desc	String	Defines the name of the audience or superaudience.
devices	List of string values	Audience only Identifies the set of devices associated with this audience. Specify a name or description for each desired device. Each value in this List will be compared against the value defined for the repl.cbdevice playback URL parameter.
dma_codes	List of string values	Audience only Identifies the set of designated market areas (DMA) associated with this audience. Specify the ID for each desired United States DMA. Request Nielsen DMA data.
external_id	String	Defines the external ID associated with this audience or superaudience.
ip_networks	List of string values	Audience only Identifies the set of IP addresses or subnets associated with this audience. Specify each desired IP address or subnet.
match_type	String	Determines the set of criteria that will be required to qualify a viewer for this audience or superaudience. Valid values are: ALL \| ANY \| NONE Learn more.
sub_audiences	List of string values	Superaudience only Defines the set of audiences associated with this superaudience. Specify the system-defined ID for each desired audience. Learn more.
zip_codes	List of string values	Audience only Identifies the set of United States zip codes associated with this audience. Specify each desired 5 digit zip code.

Authentication

Pass a digital signature based off of msg.

Learn more.

Response

A successful request returns a 200 OK response that contains the following properties:

Name	Data Type	Description
@id	String	Indicates the relative path to an endpoint that returns this audience or superaudience.
@type	String	Returns Audience.
country_codes	List of string values	Audience only Indicates the set of countries associated with this audience. Each value identifies a country by its two character country code (ISO 3166). View a list of country codes.
created	String	Indicates the timestamp (UTC) at which the audience or superaudience was created. Syntax (ISO 8601): YYYY-MM-DDThh:mm:ss.sssZ
desc	String	Indicates the name of the audience or superaudience.
devices	List of string values	Audience only Indicates the set of devices associated with this audience. Each value identifies a device by its name or description. Each value in this List will be compared against the value defined for the repl.cbdevice playback URL parameter.
dma_codes	List of string values	Audience only Indicates the set of designated market areas (DMA) associated with this audience. Each value identifies a United States DMS by its ID. Request Nielsen DMA data.
external_id	String	Indicates the external ID associated with this audience or superaudience.
id	String	Identifies this audience or superaudience by its system-defined ID.
ip_networks	List of string values	Audience only Indicates the set of IP addresses or subnets associated with this audience. Each value identifies either an IP address or IP network.
match_type	String	Determines the set of criteria that will be required to qualify a viewer for this audience or superaudience. Valid values are: ALL \| ANY \| NONE Learn more.
owner	String	Indicates the system-defined ID for the user that owns this audience or superaudience.
sub_audiences	List of string values	Superaudience only Indicates the set of audiences associated with this superaudience. Each value identifies an audience by its system-defined ID. Learn more.
type	String	Indicates whether this configuration is an audience or a superaudience. Valid values are: Single \| Multiple Learn more.
zip_codes	List of string values	Audience only Indicates the set of United States zip codes associated with this audience. Each value identifies a zip code.

Sample Request/Response

Call the update_audience module (Python 3) to update an audience. This module imports names from the api_auth module.

import json, requests
from api_auth import APICredentials, APIParams
audience_id = 'abc11672b78c4d03bf4756ec3ea46a22' # Replace with the ID for the desired audience.

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

    def run(self):
        """
        Update an audience.
        """
        self._update_audience()

    def _update_audience(self):
        url = "{}{}{}".format(self.host, "/api/v4/audiences/", audience_id)

        payload = {            
            'country_codes': ['US', 'MX'] # Replace with the desired country codes.
        }

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

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

        print(response.json())

Audience().run()

Response:

{
	'@id': '/api/v4/audiences/abc11672b78c4d03bf4756ec3ea46a22',
	'@type': 'Audience',
	'created': '2021-06-30T22:32:09.362Z',
	'id': 'cc1c1672b78c4d03bf4756ec3ea46a45',
	'owner': 'abc123def456ghi789jkl012mno345pq',
	'match_type': 'ANY',
	'external_id': 'NorthAmerica',
	'country_codes': ['MX', 'US'],
	'dma_codes': [],
	'desc': 'My New audience',
	'devices': [],
	'ip_networks': [],
	'zip_codes': [],
	'sub_audiences': [],
	'type': 'Single'
}

Rules

Automate the following rule-related tasks:

create | retrieve all | retrieve | update | delete

Add Rule

Adds a rule.

Request

Request syntax:

POST /rules

Request body parameters:

Pass the following request body parameters:

Name	Data Type	Description
all_viewers	Boolean	Determines whether this rule applies to all audiences. Default value: False
alternate_content_id	String	Identifies the alternate content that will be streamed to blacked out viewers by its ID. The alternate_content_type parameter determines how you should configure this parameter. alternate_content_type: asset Asset ID alternate_content_type: channel Live Channel ID alternate_content_type: slicer Live Slicer ID alternate_content_type: slate Conditional blackout slate will be streamed to blacked out viewers. This parameter should be an empty value.
alternate_content_loop	Boolean	Determines whether alternate content will be looped. Valid values are: True \| False
alternate_content_type	String	Defines the type of alternate content that will be streamed to blacked out viewers. Valid case-sensitive values are: asset \| channel \| slate \| slicer Identify alternate content through both the alternate_content_id and the alternate_content_type parameters. For example, specify a CMS asset by setting the alternate_content_type parameter to asset and the alternate_content_id parameter to the desired asset ID.
audience	String	all_viewers: false Identifies an audience or superaudience by its system-defined ID. This rule will only be applied to the specified audience when the all_viewers parameter is set to False.
desc Required	String	Defines the name of the rule.
external_id	String	Defines the external ID associated with this rule.

Authentication

Pass a digital signature based off of msg.

Learn more.

Response

A successful request returns a 201 Created response that contains the following properties:

Name	Data Type	Description
@id	String	Indicates the relative path to an endpoint that returns this rule.
@type	String	Returns Rule.
all_viewers	Boolean	Indicates whether this rule applies to all audiences. Default value: False
alternate_content_id	String	Indicates the alternate content that will be streamed to blacked out viewers by its ID. The alternate_content_type parameter determines the type of ID defined within this parameter. alternate_content_type: asset Asset ID alternate_content_type: channel Live Channel ID alternate_content_type: slicer Live Slicer ID alternate_content_type: slate Conditional blackout slate will be streamed to blacked out viewers. This parameter should be an empty value.
alternate_content_loop	Boolean	Indicates whether alternate content will be looped. Valid values are: True \| False
alternate_content_type	String	Indicates the type of alternate content that will be streamed to blacked out viewers. Valid case-sensitive values are: asset \| channel \| slate \| slicer Identify alternate content through both the alternate_content_id and the alternate_content_type parameters. For example, specify a CMS asset by setting the alternate_content_type parameter to asset and the alternate_content_id parameter to the desired asset ID.
audience	String	all_viewers: false Indicates an audience or superaudience by its system-defined ID. This rule will only be applied to the specified audience when the all_viewers parameter is set to False.
created	String	Indicates the timestamp (UTC) at which the rule was created. Syntax (ISO 8601): YYYY-MM-DDThh:mm:ss.sssZ
desc	String	Indicates the name of the rule.
external_id	String	Indicates the external ID associated with this rule.
id	String	Identifies this rule by its system-defined ID.
owner	String	Indicates the system-defined ID for the user that owns this rule.

Sample Request/Response

Call the add_rule module (Python 3) to create a rule. This module imports names from the api_auth module.

import json, requests
from api_auth import APICredentials, APIParams

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

    def run(self):
        """
        Create a rule.
        """
        self._create_rule()

    def _create_rule(self):
        url = "{}{}".format(self.host, "/api/v4/rules")

        payload = {
            'desc': 'My New Rule', # Replace with the rule's name.
            'alternate_content_type': 'slate', # Sets alternate content to slate.
            'all_viewers': True # Applies this rule to all viewers.
        }

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

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

        print(response.json())

Rule().run()

Response:

{
	'@id': '/api/v4/rules/c1fb5a555b9d45b7a43552f65a268075',
	'@type': 'Rule',
	'created': '2021-07-01T23:34:38.215Z',
	'id': 'c1fb5a555b9d45b7a43552f65a268075',
	'owner': 'abc123def456ghi789jkl012mno345pq',
	'external_id': '',
	'audience': '',
	'alternate_content_type': 'slate',
	'alternate_content_id': '',
	'alternate_content_loop': True,
	'all_viewers': True,
	'desc': 'My New Rule'
}

Delete Rule

Deletes a rule.

Request

Request syntax:

DELETE /rules/Rule ID

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
Rule ID Required	Identifies a rule by its system-defined or external ID. Use the Get Multiple Rules endpoint to retrieve a list of rules and their IDs.

Description

Rule ID

Required

Identifies a rule by its system-defined or external ID.

Use the Get Multiple Rules endpoint to retrieve a list of rules and their IDs.

Authentication

Pass a digital signature based off of msg.

Learn more.

Response

A successful request returns a 200 OK response that contains the following properties:

Name	Data Type	Description
@id	String	Indicates the relative path to the requested endpoint.
@type	String	Returns Rule.
message	String	Returns Deleted.

Sample Request/Response

Call the delete_rule module (Python 3) to delete a rule. This module imports names from the api_auth module.

import json, requests
from api_auth import APICredentials, APIParams
rule_id = 'c1eb5a555b9d45b7a43552f65a268075' # Replace with the ID for the desired rule.

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

    def run(self):
        """
        Deletes a rule.
        """
        self._delete_rule()

    def _delete_rule(self):
        url = "{}{}{}".format(self.host, "/api/v4/rules/", rule_id)
 
        response = requests.delete(
            url, params=APIParams(APICredentials()).get_params({})
        )

        print(response.json())

DeleteRule().run()

Response:

{
	'@id': '/api/v4/rules/c1eb5a555b9d45b7a43552f65a268075',
	'@type': 'Rule',
	'message': 'Deleted'
}

Get Multiple Rules

Retrieves one or more rules.

Request

GET /rules?page=Page Number&page_size=Items Per Page

Request query string parameters:

Pass the following request query string parameters:

Name	Description
page=Page Number	Filter the response by a specific page. Replace this variable with the desired page. Use the navigation links within the @links object to navigate between pages. Default Value: 1
page_size=Items Per Page	Sets the number of rule configurations that may be included on each page. The number of items per page determines the number of pages that may be returned. The maximum page size is 40. Default value: 40

Name

Description

page=Page Number

Filter the response by a specific page. Replace this variable with the desired page.

Use the navigation links within the @links object to navigate between pages.

Default Value:

page_size=Items Per Page

Sets the number of rule configurations that may be included on each page.

The number of items per page determines the number of pages that may be returned.

The maximum page size is 40.

Default value:

Authentication

Pass a digital signature based off of msg.

Learn more.

Response

A successful request returns a 200 OK response that contains the following properties:

Name	Data Type	Description
@id	String	Indicates the relative path to the requested endpoint.
@type	String	Returns Collection.
items	List of dictionaries	Contains a list of rule configurations.
total_items	Integer	Indicates the total number of rule configurations.

items List

The items list describes each rule configuration via the following properties:

Name	Data Type	Description
@id	String	Indicates the relative path to an endpoint that returns this rule.
@type	String	Returns Rule.
all_viewers	Boolean	Indicates whether this rule applies to all audiences. Default value: False
alternate_content_id	String	Indicates the alternate content that will be streamed to blacked out viewers by its ID. The alternate_content_type parameter determines the type of ID defined within this parameter. alternate_content_type: asset Asset ID alternate_content_type: channel Live Channel ID alternate_content_type: slicer Live Slicer ID alternate_content_type: slate Conditional blackout slate will be streamed to blacked out viewers. This parameter should be an empty value.
alternate_content_loop	Boolean	Indicates whether alternate content will be looped. Valid values are: True \| False
alternate_content_type	String	Indicates the type of alternate content that will be streamed to blacked out viewers. Valid case-sensitive values are: asset \| channel \| slate \| slicer Identify alternate content through both the alternate_content_id and the alternate_content_type parameters. For example, specify a CMS asset by setting the alternate_content_type parameter to asset and the alternate_content_id parameter to the desired asset ID.
audience	String	all_viewers: false Indicates an audience or superaudience by its system-defined ID. This rule will only be applied to the specified audience when the all_viewers parameter is set to False.
created	String	Indicates the timestamp (UTC) at which the rule was created. Syntax (ISO 8601): YYYY-MM-DDThh:mm:ss.sssZ
desc	String	Indicates the name of the rule.
external_id	String	Indicates the external ID associated with this rule.
id	String	Identifies this rule by its system-defined ID.
owner	String	Indicates the system-defined ID for the user that owns this rule.

Sample Request/Response

Call the get_multiple_rules module (Python 3) to retrieve multiple rules. This module imports names from the api_auth module.

import json, requests
from api_auth import APICredentials, APIParams

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

    def run(self):
        self._get_multiple_rules()

    def _get_multiple_rules(self):        
        url = "{}{}".format(self.host, "/api/v4/rules")

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

        response = requests.get(
            url, params=APIParams(APICredentials()).get_params({}), headers=headers
        )
  
        print(response.json())
  
Rule().run()

Response:

{
	'@id': '/api/v4/rules',
	'@type': 'Collection',
	'items': [{
			'@id': '/api/v4/rules/abce337d51f04b6da043cc7f28c9fe2f',
			'@type': 'Rule',
			'id': 'abce337d51f04b6da043cc7f28c9fe2f',
			'created': '2021-07-01T20:45:59.171Z',
			'owner': 'abc123def456ghi789jkl012mno345pq',
			'external_id': '',
			'audience': 'e1fa7c93edda4541937899ad032b9051',
			'alternate_content_type': 'slate',
			'alternate_content_id': '',
			'alternate_content_loop': True,
			'all_viewers': False,
			'desc': 'audiences'
		}, {
			'@id': '/api/v4/rules/72511122bf2541728641aefe7b4e58fe',
			'@type': 'Rule',
			'id': '72511122bf2541728641aefe7b4e58fe',
			'created': '2021-07-01T20:30:04.122Z',
			'owner': 'abc123def456ghi789jkl012mno345pq',
			'external_id': '',
			'audience': '',
			'alternate_content_type': 'slicer',
			'alternate_content_id': 'slicer1',
			'alternate_content_loop': False,
			'all_viewers': True,
			'desc': 'allviewersslicer'
		}
	],
	'total_items': 2
}

Get Rule

Retrieves a specific rule.

Request

Request syntax:

GET /rules/Rule ID

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
Rule ID Required	Identifies a rule by its system-defined or external ID. Use the Get Multiple Rules endpoint to retrieve a list of rules and their IDs.

Description

Rule ID

Required

Identifies a rule by its system-defined or external ID.

Use the Get Multiple Rules endpoint to retrieve a list of rules and their IDs.

Authentication

Pass a digital signature based off of msg.

Learn more.

Response

A successful request returns a 200 OK response that contains the following properties:

Name	Data Type	Description
@id	String	Indicates the relative path to an endpoint that returns this rule.
@type	String	Returns Rule.
all_viewers	Boolean	Indicates whether this rule applies to all audiences. Default value: False
alternate_content_id	String	Indicates the alternate content that will be streamed to blacked out viewers by its ID. The alternate_content_type parameter determines the type of ID defined within this parameter. alternate_content_type: asset Asset ID alternate_content_type: channel Live Channel ID alternate_content_type: slicer Live Slicer ID alternate_content_type: slate Conditional blackout slate will be streamed to blacked out viewers. This parameter should be an empty value.
alternate_content_loop	Boolean	Indicates whether alternate content will be looped. Valid values are: True \| False
alternate_content_type	String	Indicates the type of alternate content that will be streamed to blacked out viewers. Valid case-sensitive values are: asset \| channel \| slate \| slicer Identify alternate content through both the alternate_content_id and the alternate_content_type parameters. For example, specify a CMS asset by setting the alternate_content_type parameter to asset and the alternate_content_id parameter to the desired asset ID.
audience	String	all_viewers: false Indicates an audience or superaudience by its system-defined ID. This rule will only be applied to the specified audience when the all_viewers parameter is set to False.
created	String	Indicates the timestamp (UTC) at which the rule was created. Syntax (ISO 8601): YYYY-MM-DDThh:mm:ss.sssZ
desc	String	Indicates the name of the rule.
external_id	String	Indicates the external ID associated with this rule.
id	String	Identifies this rule by its system-defined ID.
owner	String	Indicates the system-defined ID for the user that owns this rule.

Sample Request/Response

Call the get_rule module (Python 3) to retrieve a specific rule. This module imports names from the api_auth module.

import json, requests
from api_auth import APICredentials, APIParams
rule_id = 'abce337d51f04b6da043cc7f28c9fe2f' # Replace with the ID for the desired rule.

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


    def run(self):
        self._get_rule()

    def _get_rule(self):        
        url = "{}{}{}".format(self.host, "/api/v4/rules/", rule_id)

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

        response = requests.get(
            url, params=APIParams(APICredentials()).get_params({}), headers=headers
        )
  
        print(response.json())
  
Rule().run()

Response:

{
	'@id': '/api/v4/rules/abce337d51f04b6da043cc7f28c9fe2f',
	'@type': 'Rule',
	'id': 'abce337d51f04b6da043cc7f28c9fe2f',
	'created': '2021-07-01T20:45:59.171Z',
	'owner': 'abc123def456ghi789jkl012mno345pq',
	'external_id': '',
	'audience': 'e1fa7c93edda4541937899ad032b9051',
	'alternate_content_type': 'slate',
	'alternate_content_id': '',
	'alternate_content_loop': True,
	'all_viewers': False,
	'desc': 'audiences'
}

Update Rule

Updates a specific rule.

Request

Request syntax:

PATCH /rules/Rule ID

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
Rule ID Required	Identifies a rule by its system-defined or external ID. Use the Get Multiple Rules endpoint to retrieve a list of rules and their IDs.

Description

Rule ID

Required

Identifies a rule by its system-defined or external ID.

Use the Get Multiple Rules endpoint to retrieve a list of rules and their IDs.

Request body parameters:

Pass the following request body parameters:

Name	Data Type	Description
all_viewers	Boolean	Determines whether this rule applies to all audiences. Default value: False
alternate_content_id	String	Identifies the alternate content that will be streamed to blacked out viewers by its ID. The alternate_content_type parameter determines how you should configure this parameter. alternate_content_type: asset Asset ID alternate_content_type: channel Live Channel ID alternate_content_type: slicer Live Slicer ID alternate_content_type: slate Conditional blackout slate will be streamed to blacked out viewers. This parameter should be an empty value.
alternate_content_loop	Boolean	Determines whether alternate content will be looped. Valid values are: True \| False
alternate_content_type	String	Defines the type of alternate content that will be streamed to blacked out viewers. Valid case-sensitive values are: asset \| channel \| slate \| slicer Identify alternate content through both the alternate_content_id and the alternate_content_type parameters. For example, specify a CMS asset by setting the alternate_content_type parameter to asset and the alternate_content_id parameter to the desired asset ID.
audience	String	all_viewers: false Identifies an audience or superaudience by its system-defined ID. This rule will only be applied to the specified audience when the all_viewers parameter is set to False.
desc	String	Defines the name of the rule.
external_id	String	Defines the external ID associated with this rule.

Authentication

Pass a digital signature based off of msg.

Learn more.

Response

A successful request returns a 200 OK response that contains the following properties:

Name	Data Type	Description
@id	String	Indicates the relative path to an endpoint that returns this rule.
@type	String	Returns Rule.
all_viewers	Boolean	Indicates whether this rule applies to all audiences. Default value: False
alternate_content_id	String	Indicates the alternate content that will be streamed to blacked out viewers by its ID. The alternate_content_type parameter determines the type of ID defined within this parameter. alternate_content_type: asset Asset ID alternate_content_type: channel Live Channel ID alternate_content_type: slicer Live Slicer ID alternate_content_type: slate Conditional blackout slate will be streamed to blacked out viewers. This parameter should be an empty value.
alternate_content_loop	Boolean	Indicates whether alternate content will be looped. Valid values are: True \| False
alternate_content_type	String	Indicates the type of alternate content that will be streamed to blacked out viewers. Valid case-sensitive values are: asset \| channel \| slate \| slicer Identify alternate content through both the alternate_content_id and the alternate_content_type parameters. For example, specify a CMS asset by setting the alternate_content_type parameter to asset and the alternate_content_id parameter to the desired asset ID.
audience	String	all_viewers: false Indicates an audience or superaudience by its system-defined ID. This rule will only be applied to the specified audience when the all_viewers parameter is set to False.
created	String	Indicates the timestamp (UTC) at which the rule was created. Syntax (ISO 8601): YYYY-MM-DDThh:mm:ss.sssZ
desc	String	Indicates the name of the rule.
external_id	String	Indicates the external ID associated with this rule.
id	String	Identifies this rule by its system-defined ID.
owner	String	Indicates the system-defined ID for the user that owns this rule.

Sample Request/Response

Call the update_rule module (Python 3) to update a rule. This module imports names from the api_auth module.

import json, requests
from api_auth import APICredentials, APIParams
rule_id = 'c2eb5a555b9d45b7a43552f65a268075' # Replace with the ID for the desired rule.

class Rule:
    def __init__(self):
        self.host = "https://services.uplynk.com"import json, requests

    def run(self):
        """
        Update a rule.
        """
        self._update_rule()

    def _update_rule(self):
        url = "{}{}{}".format(self.host, "/api/v4/rules/", rule_id)

        payload = {            
            'alternate_content_type': 'asset', # Sets the type of alternate content.
            'alternate_content_id': '062048d702734ca6a38f3e7f8e4f4488' # Replace with the desired asset ID.
        }

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

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

        print(response.json())

Rule().run()

Response:

{
	'@id': '/api/v4/rules/c2eb5a555b9d45b7a43552f65a268075',
	'@type': 'Rule',
	'id': 'c2eb5a555b9d45b7a43552f65a268075',
	'created': '2021-07-01T23:34:38.215Z',
	'owner': 'abc123def456ghi789jkl012mno345pq',
	'external_id': '',
	'audience': '',
	'alternate_content_type': 'asset',
	'alternate_content_id': '062048d702734ca6a38f3e7f8e4f4488',
	'alternate_content_loop': True,
	'all_viewers': True,
	'desc': 'My New Rule'
}

Blackout Configuration

Automate the following blackout-related tasks:

create | retrieve all | retrieve | update | delete

Add Blackout

Adds a blackout configuration to a live channel.

Request

Request syntax:

POST /channels/Live Channel ID/blackouts

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.

Description

Live Channel ID

Required

Identifies a live channel by its system-defined ID.

Request body parameters:

Pass the following request body parameters:

Name	Data Type	Description
blackout_id Required	String	Defines the blackout ID that identifies programming that should be blacked out. This value must be unique across all blackout configurations associated with a live channel. Learn how to tag programming with a blackout ID.
desc	String	Defines the name of the blackout configuration.
external_id	String	Defines the external ID associated with this blackout configuration.
rules	List of string values	Contains the set of blackout rules associated with this blackout configuration. These rules identify audience(s) and the alternate content that should be streamed when programming has been tagged with the blackout ID defined within the blackout_id parameter. Identify each desired blackout rule by its system-defined ID.

Authentication

Pass a digital signature based off of msg.

Learn more.

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 blackout configuration.
@type	String	Returns Blackout.
blackout_id	String	Indicates the blackout ID that identifies programming that should be blacked out. Learn how to tag programming with a blackout ID.
channel	String	Indicates the system-defined ID for the live channel associated with this blackout configuration.
desc	String	Indicates the name of the blackout configuration.
external_id	String	Indicates the external ID associated with this blackout configuration.
id	String	Identifies this blackout configuration by its system-defined ID.
owner	String	Indicates the system-defined ID for the user that owns this blackout configuration.
rules	List of string values	Contains the set of blackout rules associated with this blackout configuration. These rules identify audience(s) and the alternate content that should be streamed when programming has been tagged with the blackout ID defined within the blackout_id parameter. Each value identifies a blackout rule by its system-defined ID.

Sample Request/Response

Call the add_blackout module (Python 3) to add a blackout configuration to a live channel. This module imports names from the api_auth module.

import json, requests
from api_auth import APICredentials, APIParams
channel_id = '02ed9f65570746528e7b3d0628960025' # Replace with the ID for the desired live channel.

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

    def run(self):
        """
        Adds a blackout configuration to a live channel.
        """
        self._create_blackout()

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

        payload = {
            'desc': 'Blackout North America', # Replace with the live channel's name.
            'blackout_id': 'BNA', # Replace with the desired blackout ID.
            'rules': ['abce337d51f04b6da043cc7f28c9fe2f'] # Replace with the ID for the desired blackout rule.
        }

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

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

        print(response.json())

Blackout().run()

Response:

{
	'@id': '/api/v4/channels/02ed9f65570746528e7b3d0628960025/blackouts/f29106a8d8994dd7886c7f8aedab3b77',
	'@type': 'Blackout',
	'id': 'f29106a8d8994dd7886c7f8aedab3b77',
	'blackout_id': 'BNA',
	'channel': '02ed9f65570746528e7b3d0628960025',
	'desc': 'Blackout North America',
	'external_id': '',
	'owner': 'abc123def456ghi789jkl012mno345pq',
	'rules': ['c5ce337d51f04b6da043cc7f28c9fef1']
}

Delete Blackout

Deletes a blackout configuration from a live channel.

Request

Request syntax:

DELETE /channels/Live Channel ID/blackouts/Blackout ID

Define the following variables 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.
Blackout ID Required	Identifies a blackout configuration by its system-defined or external ID. Use the Get Multiple Blackouts endpoint to retrieve a list of blackout configurations and their IDs.

Description

Live Channel ID

Required

Identifies a live channel by its system-defined ID.

Blackout ID

Required

Identifies a blackout configuration by its system-defined or external ID.

Use the Get Multiple Blackouts endpoint to retrieve a list of blackout configurations and their IDs.

Authentication

Pass a digital signature based off of msg.

Learn more.

Response

A successful request returns a 200 OK response that contains the following properties:

Name	Data Type	Description
@id	String	Indicates the relative path to the requested endpoint.
@type	String	Returns Blackout.
message	String	Returns Deleted.

Sample Request/Response

Call the delete_blackout module (Python 3) to delete a blackout configuration from a live channel. This module imports names from the api_auth module.

import json, requests
from api_auth import APICredentials, APIParams
channel_id = 'Hak3zjnPLSW5o0j8GMpzRMsa' # Replace with the ID for the desired live channel.
blackout_id = 'degf8923f093kfd932kd9fa4' # Replace with the ID for the desired blackout configuration.

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

    def run(self):
        """
        Deletes a blackout configuration.
        """
        self._delete_blackout()

    def _delete_blackout(self):
        url = "{}{}{}{}{}".format(self.host, "/api/v4/channels/", channel_id, "/blackouts", blackout_id)
 
        response = requests.delete(
            url, params=APIParams(APICredentials()).get_params({})
        )

        print(response.json())

DeleteBlackout().run()

Response:

{
	'@id': '/api/v4/channels/Hak3zjnPLSW5o0j8GMpzRMsa/blackouts/degf8923f093kfd932kd9fa4',
	'@type': 'Blackout',
	'message': 'Deleted'
}

Get Blackout

Retrieves a blackout configuration associated with a live channel.

Request

Request syntax:

GET /channels/Live Channel ID/blackouts/Blackout ID

Define the following variables 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.
Blackout ID Required	Identifies a blackout configuration by its system-defined or external ID. Use the Get Multiple Blackouts endpoint to retrieve a list of blackout configurations and their IDs.

Description

Live Channel ID

Required

Identifies a live channel by its system-defined ID.

Blackout ID

Required

Identifies a blackout configuration by its system-defined or external ID.

Use the Get Multiple Blackouts endpoint to retrieve a list of blackout configurations and their IDs.

Authentication

Pass a digital signature based off of msg.

Learn more.

Response

A successful request returns a 200 OK response that contains the following properties:

Name	Data Type	Description
@id	String	Indicates the relative path to an endpoint that returns this blackout configuration.
@included	List of dictionaries	Contains the blackout rule associated with this blackout configuration.
@type	String	Returns Blackout.
blackout_id	String	Indicates the blackout ID that identifies programming that should be blacked out. Learn how to tag programming with a blackout ID.
channel	String	Indicates the system-defined ID for the live channel associated with this blackout configuration.
desc	String	Indicates the name of the blackout configuration.
external_id	String	Indicates the external ID associated with this blackout configuration.
id	String	Identifies this blackout configuration by its system-defined ID.
owner	String	Indicates the system-defined ID for the user that owns this blackout configuration.
rules	List of string values	Contains the set of blackout rules associated with this blackout configuration. These rules identify audience(s) and the alternate content that should be streamed when programming has been tagged with the blackout ID defined within the blackout_id parameter. Each value identifies a blackout rule by its system-defined ID.

@included List

The @included list describes the blackout rule associated with this blackout configuration via the following properties:

Name	Data Type	Description
@id	String	Indicates the relative path to an endpoint that returns this rule.
@type	String	Returns Rule.
all_viewers	Boolean	Indicates whether this rule applies to all audiences. Default value: False
alternate_content_id	String	Indicates the alternate content that will be streamed to blacked out viewers by its ID. The alternate_content_type parameter determines the type of ID defined within this parameter. alternate_content_type: asset Asset ID alternate_content_type: channel Live Channel ID alternate_content_type: slicer Live Slicer ID alternate_content_type: slate Conditional blackout slate will be streamed to blacked out viewers. This parameter should be an empty value.
alternate_content_loop	Boolean	Indicates whether alternate content will be looped. Valid values are: True \| False
alternate_content_type	String	Indicates the type of alternate content that will be streamed to blacked out viewers. Valid case-sensitive values are: asset \| channel \| slate \| slicer Identify alternate content through both the alternate_content_id and the alternate_content_type parameters. For example, specify a CMS asset by setting the alternate_content_type parameter to asset and the alternate_content_id parameter to the desired asset ID.
audience	String	all_viewers: false Indicates an audience or superaudience by its system-defined ID. This rule will only be applied to the specified audience when the all_viewers parameter is set to False.
created	String	Indicates the timestamp (UTC) at which the rule was created. Syntax (ISO 8601): YYYY-MM-DDThh:mm:ss.sssZ
desc	String	Indicates the name of the rule.
external_id	String	Indicates the external ID associated with this rule.
id	String	Identifies this rule by its system-defined ID.
owner	String	Indicates the system-defined ID for the user that owns this rule.

Sample Request/Response

Call the get_blackout module (Python 3) to retrieve a blackout configuration. This module imports names from the api_auth module.

import json, requests
from api_auth import APICredentials, APIParams
channel_id = '02ed9f65570746528e7b3d0628960025' # Replace with the ID for the desired live channel.
blackout_id = 'f29106a8d8994dd7886c7f8aedab3b77' # Replace with the ID for the desired blackout configuration.

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

    def run(self):
        self._get_blackout()

    def _get_blackout(self):        
        url = "{}{}{}{}{}".format(self.host, "/api/v4/channels/", channel_id, "/blackouts", blackout_id)

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

        response = requests.get(
            url, params=APIParams(APICredentials()).get_params({}), headers=headers
        )
  
        print(response.json())
  
Blackout().run()

Response:

{
	'@id': '/api/v4/channels/02ed9f65570746528e7b3d0628960025/blackouts/f29106a8d8994dd7886c7f8aedab3b77',
	'@type': 'Blackout',
	'@included': [{
			'@id': '/api/v4/rules/c2eb5a555b9d45b7a43552f65a268075',
			'@type': 'Rule',
			'id': 'c2eb5a555b9d45b7a43552f65a268075',
			'alternate_content_loop': True,
			'owner': 'abc123def456ghi789jkl012mno345pq',
			'alternate_content_type': 'asset',
			'desc': 'My New Rule',
			'all_viewers': True,
			'created': '2019-07-30T17:54:56.290Z',
			'alternate_content_id': '062048d702734ca6a38f3e7f8e4f4488',
			'audience': '',
			'external_id': ''
		}
	],
	'id': 'f29106a8d8994dd7886c7f8aedab3b77',
	'owner': 'abc123def456ghi789jkl012mno345pq',
	'channel': '02ed9f65570746528e7b3d0628960025',
	'blackout_id': 'BNA',
	'desc': 'Blackout North America',
	'external_id': '',
	'rules': ['c2eb5a555b9d45b7a43552f65a268075']
}

Get Multiple Blackouts

Retrieves either all or recently updated blackout configurations associated with a specific live channel.

Request

Request syntax (time period):

GET /channels/Live Channel ID/blackouts?order=Sort Category&page=Page Number&page_size=Items Per Page

Request syntax (recently updated blackout configurations):

GET /channels/Live Channel ID/blackouts?after=Last Modified Time

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.

Description

Live Channel ID

Required

Identifies a live channel by its system-defined ID.

Request query string parameters:

Pass the following optional request query string parameters:

Name	Description
after=Last Modified Time	Recently Updated Only Identifies a point-in-time for retrieving recently updated blackout configurations. The response will only include blackout configurations that were updated after this point-in-time. Specify a timestamp (ISO 8601 - milliseconds; UTC). The specified point-in-time may not exceed 10 minutes into the past. If you specify a point-in-time that is older than 10 minutes, then we will only return audiences that have been updated within the last 10 minutes. Syntax: YYYY-MM-DDThh:mm:ss.sssZ Example: after=2024-01-08T20:31:11.510Z
order=Sort Category	Determines how blackout configurations will be sorted. Valid values are: blackout_id \| created \| desc \| external_id Prepend a dash (-) to return results in reverse order. Example: Sorts blackout configurations from newest to oldest: order=-created
page=Page Number	Filter the response by a specific page. Replace this variable with the desired page. Use the navigation links within the @links object to navigate between pages. Default Value: 1
page_size=Items Per Page	Sets the number of blackout configurations that may be included on each page. The number of items per page determines the number of pages that may be returned. The maximum page size is 40. Default value: 40
include_deleted	to-do:

Authentication

Pass a digital signature based off of msg.

Learn more.

Response

A successful request returns a 200 OK response that contains the following properties:

Name	Data Type	Description
@id	String	Indicates the relative path to the requested endpoint.
@type	String	Returns Collection.
items	List of dictionaries	Contains a list of blackout configurations.
total_items	Integer	Indicates the total number of blackout configurations.

items List

The items list describes each rule configuration via the following properties:

Name	Data Type	Description
@id	String	Indicates the relative path to an endpoint that returns this blackout configuration.
@type	String	Returns Blackout.
blackout_id	String	Indicates the blackout ID that identifies programming that should be blacked out. Learn how to tag programming with a blackout ID.
channel	String	Indicates the system-defined ID for the live channel associated with this blackout configuration.
desc	String	Indicates the name of the blackout configuration.
external_id	String	Indicates the external ID associated with this blackout configuration.
id	String	Identifies this blackout configuration by its system-defined ID.
owner	String	Indicates the system-defined ID for the user that owns this blackout configuration.
rules	List of string values	Contains the set of blackout rules associated with this blackout configuration. These rules identify audience(s) and the alternate content that should be streamed when programming has been tagged with the blackout ID defined within the blackout_id parameter. Each value identifies a blackout rule by its system-defined ID.

Sample Request/Response

Call the get_multiple_blackouts module (Python 3) to retrieve the blackout configurations associated with a live channel. This module imports names from the api_auth module.

import json, requests
from api_auth import APICredentials, APIParams
channel_id = 'Hak3zjnPLSW5o0j8GMpzRMsa' # Replace with the ID for the desired live channel.
blackout_id = 'degf8923f093kfd932kd9fa4' # Replace with the ID for the desired blackout configuration.

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

    def run(self):
        """
        Update a blackout configuration.
        """
        self._update_blackout()

    def _update_blackout(self):
        url = "{}{}{}{}{}".format(self.host, "/api/v4/channels/", channel_id, "/blackouts", blackout_id)

        payload = {            
            'blackout_id': 'NorthAmerica', # Replace with the desired blackout ID.
        }

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

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

        print(response.json())

Blackout().run()

Response:

{
	'@id': '/api/v4/channels/Hak3zjnPLSW5o0j8GMpzRMsa/blackouts',
	'@type': 'Collection',
	'items': [{			
			'@id': '/api/v4/blackouts/4d585f7e0df24e25b14a45410ec836a7',
			'@type': 'Blackout',
			'id': '4d585f7e0df24e25b14a45410ec836a7',
			'blackout_id': 'BSA',
			'channel': 'Hak3zjnPLSW5o0j8GMpzRMsa',
			'desc': 'Blackout South America',
			'external_id': '',
			'owner': 'abc123def456ghi789jkl012mno345pq',
			'rules': ['f34e337d51f04b6da043cc7f28c9fef1']
		}, {
			'@id': '/api/v4/blackouts/309106a8d8994dd7886c7f8aedab3b66',
			'@type': 'Blackout',
			'id': '309106a8d8994dd7886c7f8aedab3b66',
			'blackout_id': 'BNA',
			'channel': 'Hak3zjnPLSW5o0j8GMpzRMsa',
			'desc': 'Blackout North America',
			'external_id': '',
			'owner': 'abc123def456ghi789jkl012mno345pq',
			'rules': ['c5ce337d51f04b6da043cc7f28c9fe46']		
		}
	],
	'total_items': 2
}

Update Blackout

Updates a blackout configuration.

Request

Request syntax:

PATCH /channels/Live Channel ID/blackouts/Blackout ID

Define the following variables 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.
Blackout ID Required	Identifies a blackout configuration by its system-defined or external ID. Use the Get Multiple Blackouts endpoint to retrieve a list of blackout configurations and their IDs.

Description

Live Channel ID

Required

Identifies a live channel by its system-defined ID.

Blackout ID

Required

Identifies a blackout configuration by its system-defined or external ID.

Use the Get Multiple Blackouts endpoint to retrieve a list of blackout configurations and their IDs.

Request body parameters:

Pass the following request body parameters:

Name	Data Type	Description
blackout_id	String	Defines the blackout ID that identifies programming that should be blacked out. This value must be unique across all blackout configurations associated with a live channel. Learn how to tag programming with a blackout ID.
desc	String	Defines the name of the blackout configuration.
external_id	String	Defines the external ID associated with this blackout configuration.
rules	List of string values	Contains the set of blackout rules associated with this blackout configuration. These rules identify audience(s) and the alternate content that should be streamed when programming has been tagged with the blackout ID defined within the blackout_id parameter. Identify each desired blackout rule by its system-defined ID.

Authentication

Pass a digital signature based off of msg.

Learn more.

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 blackout configuration.
@type	String	Returns Blackout.
blackout_id	String	Indicates the blackout ID that identifies programming that should be blacked out. Learn how to tag programming with a blackout ID.
channel	String	Indicates the system-defined ID for the live channel associated with this blackout configuration.
desc	String	Indicates the name of the blackout configuration.
external_id	String	Indicates the external ID associated with this blackout configuration.
id	String	Identifies this blackout configuration by its system-defined ID.
owner	String	Indicates the system-defined ID for the user that owns this blackout configuration.
rules	List of string values	Contains the set of blackout rules associated with this blackout configuration. These rules identify audience(s) and the alternate content that should be streamed when programming has been tagged with the blackout ID defined within the blackout_id parameter. Each value identifies a blackout rule by its system-defined ID.

Sample Request/Response

Call the update_blackout module (Python 3) to update a specific blackout configuration. This module imports names from the api_auth module.

import json, requests
from api_auth import APICredentials, APIParams
channel_id = 'Hak3zjnPLSW5o0j8GMpzRMsa' # Replace with the ID for the desired live channel.
blackout_id = 'degf8923f093kfd932kd9fa4' # Replace with the ID for the desired blackout configuration.

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

    def run(self):
        """
        Update a blackout configuration.
        """
        self._update_blackout()

    def _update_blackout(self):
        url = "{}{}{}{}{}".format(self.host, "/api/v4/channels/", channel_id, "/blackouts", blackout_id)

        payload = {            
            'blackout_id': 'NorthAmerica', # Replace with the desired blackout ID.
        }

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

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

        print(response.json())

Blackout().run()

Response:

{
	'@id': '/api/v4/channels/02ed9f65570746528e7b3d0628960025/blackouts/f29106a8d8994dd7886c7f8aedab3b77',
	'@type': 'Blackout',
	'id': 'f29106a8d8994dd7886c7f8aedab3b77',
	'blackout_id': 'NorthAmerica',
	'channel': '02ed9f65570746528e7b3d0628960025',
	'desc': 'Blackout North America',
	'external_id': '',
	'owner': 'abc123def456ghi789jkl012mno345pq',
	'rules': ['c5ce337d51f04b6da043cc7f28c9fef1']
}