Third-Party Integrations

Please let us know if you would like to see additional functionality.

Use the APIs described in this section to integrate third-party systems (e.g., third-party ad servers).

Please refer to the Client APIs to integrate a media player with our service.

Basic Information

Use the following information to become acquainted with our Third-Party Integration APIs:

RESTful APIs

These APIs follow a simplified version of RESTful conventions. Specifically:
- Only GET and POST HTTP methods are used.
- Parameters are not defined in the request URL.
Programming Language

These APIs are language-agnostic and therefore may be called using any modern programming language.
Authentication

Each request must be signed via your API key.

Learn more.
Request
- Scheme: All requests must use the HTTPs scheme (i.e., https://).
- Domain: All requests must be directed to services.uplynk.com.
- Request Parameters: Each endpoint requires a message, which is an encoded JSON object, and a digital signature to be passed as URL-encoded parameters.
Response

The response is a JSON object. This object always contains an error member that reports an integer. A value of 0 indicates that an error did not occur. If an error occurred, then this JSON object will typically include a msg member that describes the error.

Messages and Signatures

Each endpoint requires the following URL-encoded parameters:

msg: This encoded JSON object identifies your account by user ID (i.e., _owner) and indicates the timestamp (i.e., _timestamp), in seconds (UTC), at which this message was generated. It may also contain any additional parameters specific to the endpoint being requested.

The msg parameter must include _owner and _timestamp.
Where can I find my user ID?
1. Load the User Settings page. How?From the main menu, navigate to Settings | User Settings.
2. Your user ID is listed under the User ID label.
Learn how to encode a message.
sig: This parameter is a digital signature for the msg parameter.

Learn how to sign a message.

Encoding a Message

Encode the msg parameter by:

Constructing a JSON string representation of the request parameters for the endpoint being called.
Compressing the above JSON string using zlib.
Base-64 encoding the above JSON string. This will remove whitespace characters.

Signing a Message

Sign a message by computing the HMAC-SHA256 digest of your secret API key and the msg parameter.

Code Samples

Sample code provided for each endpoint imports the Call() function from the uplynk_api2_auth module. Substitute the values for USER_ID and API_KEY with your own user ID and API key, respectively.

Common API code (Python 3):

import base64, hashlib, hmac, json, time, urllib.parse, zlib
from urllib.request import urlopen

ROOT_URL = 'https://services.uplynk.com'
USER_ID = '1234567890abcdefghijklmnopqrstu' # Replace with your user ID.
API_KEY = '1234567890abcdefghijklmnopqrstuvwxyz1234' # Replace with your API key.

def Call(uri, **msg):
    """Base method for Uplynk API (api2) calls"""
    msg['_owner'] = USER_ID
    msg['_timestamp'] = int(time.time())
    msg = json.dumps(msg)
    msg = zlib.compress(msg.encode(), level=9)
    msg = base64.b64encode(msg).strip()
    sig = hmac.new(API_KEY.encode(), msg, hashlib.sha256).hexdigest()
    body = urllib.parse.urlencode(dict(msg=msg, sig=sig)).encode('utf-8')
    return json.loads(urlopen(ROOT_URL + uri, body).read())

print(Call('/api2/fake', foo='some value', bar=15))

Common API code (Node.js):

const crypto = require("crypto");
const https = require("https");
const querystring = require("querystring");
const zlib = require("zlib");

const ROOT_URL = "services.uplynk.com";
const USER_ID = "1234567890abcdefghijklmnopqrstu"; // Replace with your user ID.
const API_KEY = "1234567890abcdefghijklmnopqrstuvwxyz1234"; // Replace with your API key.

function call(uri, options) {
	let msg = {
		_owner: USER_ID,
		_timestamp: parseInt(Date.now() / 1000),
		...options,
	};
	msg = JSON.stringify(msg);
	msg = zlib.deflateSync(msg, { level: 9 }).toString("base64");
	const sig = crypto.createHmac("sha256", API_KEY).update(msg).digest("hex");
	const body = querystring.stringify({ msg, sig });
	const url = `${ROOT_URL}${uri}?${body}`;
	return post(ROOT_URL, uri, body);
}

function post(host, path, data) {
	return new Promise((resolve, reject) => {
		let respData = "";
		const req = https.request({ host, path, method: "POST" }, (res) => {
			res.on("data", (chunk) => (respData += chunk));
			res.on("end", () => resolve(JSON.parse(respData)));
		});
		req.on("error", (err) => {
			reject(err);
		});
		req.write(data);
		req.end();
	});
}

Common API code (PHP):

<?php
$ROOT_URL = 'https://services.uplynk.com';
$USER_ID = 'c56ea4014685bc74c0a375236cc5a735';
$API_KEY = 'GESKwbpWxQ/QhHFmhTZLLu3rYeNuK4gYrWwlCLnT';

function encode_array($args)
{
  if(!is_array($args)) return false;
  $c = 0;
  $out = '';
  foreach($args as $name => $value)
  {
    if($c++ != 0) $out .= '&';
    $out .= urlencode("$name").'=';
    if(is_array($value))
    {
      $out .= urlencode(serialize($value));
    }else{
      $out .= urlencode("$value");
    }
  }
  return $out . "\n";
}

function Call($uri, $msg=array())
{
    global $ROOT_URL, $USER_ID, $API_KEY;

    $msg['_owner'] = $USER_ID;
    $msg['_timestamp'] = time();
    $msg = json_encode($msg);
    $msg = base64_encode(gzcompress($msg,9));
    $sig = hash_hmac('sha256', $msg, $API_KEY);
    $sig = trim($sig);
    $body = encode_array(array('msg'=>$msg, 'sig'=>$sig));
    $ch = curl_init();
    curl_setopt($ch, CURLOPT_URL, $ROOT_URL . $uri);
    curl_setopt($ch, CURLOPT_POST,1);
    curl_setopt($ch, CURLOPT_POSTFIELDS, $body);
    curl_setopt($ch, CURLOPT_RETURNTRANSFER,1);
    $result = curl_exec($ch);
    curl_close($ch);
    return $result;
}

The Call() helper function prepares the message body and digital signature. Using this helper function, the examples from the Messages and Signatures section can be reduced to:

Sample request (Python 3):

print(Call('/api2/fake', foo='some value', bar=15))

Sample request (Node.js):

(async () => console.log(await call("/api2/fake", { foo: "some value", bar: 15 })))();

Sample request (PHP):

echo Call('/api2/fake', array('foo'=>'some value', 'bar'=>15));

Available APIs

Our third-party integration APIs are organized into the following groups:

Service	Description
Ad	Retrieves information about ads and ad settings.
Asset	Retrieves information and modifies properties on a CMS asset.
Channel	Manipulates and queries information on live linear channels.
Cloud Slicer	Slices and encodes content in the cloud.
Library	Manages shared CMS libraries.
Live Events	Retrieves information and modifies upcoming live events.
Owners	Manages API keys.
Slicer	Find out the last known status information for one or more Live Slicers and retrieve/update a slicing scheduling.
Subowners	Manages subowners associated with your account.
Token	Verifies tokens against a playback URL.