API routes - Channels

Documentation of the principal routes available in the serverside.ai API.

Channels - get schema

GET https://admin.serverside.ai/api/v2/channels/schema

Returns the full channel JSON schema

Headers

Name
Type
Description

x-api-key

string

Your serverside.ai API key

{
    "type": "object",
    "properties": {
        "name": {
            "type": "string",
            "title": "Channel Name"
        },
        "apiKey": {
            "type": "string",
            "title": "API Key"
        },
        "sourceManifestUrl": {
            "type": "string",
            "title": "Source URL"
        },
        "adSlateManifestUrl": {
            "type": "string",
            "default": "",
            "title": "Ad slate URL"
        },
        "profile": {
            "type": "object",
            "title": "Encoding Profile"
        },
        "outputUri": {
            "type": "string",
            "title": "Output URI"
        },
        "type": {
            "type": "string",
            "enum": [
                "hls-live",
                "hls-vod",
                "dash-live",
                "dash-vod",
                "mrss"
            ],
            "title": "Channel type"
        },
        "adSource": {
            "type": "object",
            "title": "Ad Source"
        },
        "adConditioner": {
            "type": "object",
            "title": "Ad Conditioner"
        },
        "state": {
            "type": "string",
            "enum": [
                "disabled",
                "enabled",
                "failed",
                "shutdown"
            ],
            "title": "State"
        }
    },
    "required": [
        "name",
        "sourceManifestUrl",
        "adSlateManifestUrl",
        "adSource"
    ]
}

Channels - get

GET https://admin.serverside.ai/api/v2/channels/

Gets a list of your channels.

Query Parameters

Name
Type
Description

profileHash

string

The profile hash of the channel you want to find

sort

string

Field name to sort by. e.g. 'name'. For descending order, use e.g. '-name'

offset

number

Given the sort, which record to start the returned dataset from. Useful for paging.

limit

number

Max number of records to return

search

object

e.g. 'test'. Fields searched are name, id, titleId. name and id are regex wildcard searches, e.g '*test*', titleId is exact match.

Headers

Name
Type
Description

x-api-key

string

Your serverside.ai API key

[
  {
    "adSlateManifestUrl": "https://utvcdnzgwo2hot2llvudata.blob.core.windows.net/ch5223id76/adslate.m3u8",
    "_id": "<ID>",
    "name": "Test Channel 1",
    "type": "hls-live",
    "state": "disabled",
    "apiKey": "<API KEY>",
    "tenant": "Your Company",
    "sourceManifestUrl": "https://utvcdnzgwo2hot2llvudata.blob.core.windows.net/ch5223id88/ch5223id88_master.m3u8",
    "adSource": {
      "system": "spotx",
      "url": "https://search.spotxchange.com/vast/3.0/123456"
    },
    "adConditioner": {
      "system": "nemo2",
      "apiUrl": "https://staging.serverside.ai/api/v2",
      "apiKey": "<API KEY>"
    },
    "id": "<UUID>",
    "profile": {
      "type": "ams",
      "codecs": [
        {
          "odatatype": "#Microsoft.Media.H264Video",
          "keyFrameInterval": "PT2S",
          "layers": [
            {
              "odatatype": "#Microsoft.Media.H264Layer",
              "profile": "Main",
              "level": "3.1",
              "bufferWindow": "PT5S",
              "bFrames": 3,
              "referenceFrames": 3,
              "adaptiveBFrame": true,
              "frameRate": "24000/1001",
              "label": "320x180",
              "bitrate": 474117,
              "maxBitrate": 474117,
              "width": "320",
              "height": "180"
            },
            {
              "odatatype": "#Microsoft.Media.H264Layer",
              "profile": "Main",
              "level": "3.1",
              "bufferWindow": "PT5S",
              "bFrames": 3,
              "referenceFrames": 3,
              "adaptiveBFrame": true,
              "frameRate": "24000/1001",
              "label": "480x272",
              "bitrate": 760001,
              "maxBitrate": 760001,
              "width": "480",
              "height": "272"
            },
            {
              "odatatype": "#Microsoft.Media.H264Layer",
              "profile": "Main",
              "level": "3.1",
              "bufferWindow": "PT5S",
              "bFrames": 3,
              "referenceFrames": 3,
              "adaptiveBFrame": true,
              "frameRate": "24000/1001",
              "label": "640x360",
              "bitrate": 1127459,
              "maxBitrate": 1127459,
              "width": "640",
              "height": "360"
            },
            {
              "odatatype": "#Microsoft.Media.H264Layer",
              "profile": "Main",
              "level": "3.1",
              "bufferWindow": "PT5S",
              "bFrames": 3,
              "referenceFrames": 3,
              "adaptiveBFrame": true,
              "frameRate": "24000/1001",
              "label": "960x540",
              "bitrate": 2036100,
              "maxBitrate": 2036100,
              "width": "960",
              "height": "540"
            },
            {
              "odatatype": "#Microsoft.Media.H264Layer",
              "profile": "Main",
              "level": "3.1",
              "bufferWindow": "PT5S",
              "bFrames": 3,
              "referenceFrames": 3,
              "adaptiveBFrame": true,
              "frameRate": "24000/1001",
              "label": "1280x720",
              "bitrate": 3148466,
              "maxBitrate": 3148466,
              "width": "1280",
              "height": "720"
            }
          ]
        },
        {
          "odatatype": "#Microsoft.Media.AacAudio",
          "channels": 2,
          "samplingRate": 48000,
          "bitrate": 128000,
          "profile": "AacLc",
          "label": "aacAudio"
        }
      ]
    },
    "createdBy": "API-Key",
    "createdAt": "2019-09-18T11:11:49.565Z",
    "__v": 0
  }
]

Channels - get by id

GET https://admin.serverside.ai/api/v2/channels/:id

Gets an individual channel by its id.

Path Parameters

Name
Type
Description

id

string

The id of the channel you want.

Headers

Name
Type
Description

x-api-key

string

Your serverside.ai API Key

{
    "adSlateManifestUrl": "https://utvcdnzgwo2hot2llvudata.blob.core.windows.net/ch5223id76/adslate.m3u8",
    "_id": "<Number>",
    "name": "Test Channel",
    "type": "hls-live",
    "state": "enabled",
    "apiKey": "<API KEY>",
    "tenant": "Another New Company",
    "sourceManifestUrl": "https://utvcdnzgwo2hot2llvudata.blob.core.windows.net/ch5223id88/ch5223id88_master.m3u8",
    "adSource": {
        "system": "spotx",
        "url": "https://search.spotxchange.com/vast/3.0/123456"
    },
    "adConditioner": {
        "system": "nemo2",
        "apiUrl": "http://localhost:3000/api/v2"
    },
    "id": "<UUID>",
    "outputUri": "https://staging-live.serverside.ai/hls/60a7d00e-15b4-42fe-b146-249ba846bdb5/master.m3u8?api-key=fc963fca-6838-47fc-8aaf-5c265f90aaba",
    "profile": {
        "type": "ams",
        "codecs": [
            {
                "odatatype": "#Microsoft.Media.H264Video",
                "keyFrameInterval": "PT2S",
                "layers": [
                    {
                        "odatatype": "#Microsoft.Media.H264Layer",
                        "profile": "Main",
                        "level": "3.1",
                        "bufferWindow": "PT5S",
                        "bFrames": 3,
                        "referenceFrames": 3,
                        "adaptiveBFrame": true,
                        "frameRate": "24000/1001",
                        "label": "320x180",
                        "bitrate": 474117,
                        "maxBitrate": 474117,
                        "width": "320",
                        "height": "180"
                    },
                    {
                        "odatatype": "#Microsoft.Media.H264Layer",
                        "profile": "Main",
                        "level": "3.1",
                        "bufferWindow": "PT5S",
                        "bFrames": 3,
                        "referenceFrames": 3,
                        "adaptiveBFrame": true,
                        "frameRate": "24000/1001",
                        "label": "480x272",
                        "bitrate": 760001,
                        "maxBitrate": 760001,
                        "width": "480",
                        "height": "272"
                    },
                    {
                        "odatatype": "#Microsoft.Media.H264Layer",
                        "profile": "Main",
                        "level": "3.1",
                        "bufferWindow": "PT5S",
                        "bFrames": 3,
                        "referenceFrames": 3,
                        "adaptiveBFrame": true,
                        "frameRate": "24000/1001",
                        "label": "640x360",
                        "bitrate": 1127459,
                        "maxBitrate": 1127459,
                        "width": "640",
                        "height": "360"
                    },
                    {
                        "odatatype": "#Microsoft.Media.H264Layer",
                        "profile": "Main",
                        "level": "3.1",
                        "bufferWindow": "PT5S",
                        "bFrames": 3,
                        "referenceFrames": 3,
                        "adaptiveBFrame": true,
                        "frameRate": "24000/1001",
                        "label": "960x540",
                        "bitrate": 2036100,
                        "maxBitrate": 2036100,
                        "width": "960",
                        "height": "540"
                    },
                    {
                        "odatatype": "#Microsoft.Media.H264Layer",
                        "profile": "Main",
                        "level": "3.1",
                        "bufferWindow": "PT5S",
                        "bFrames": 3,
                        "referenceFrames": 3,
                        "adaptiveBFrame": true,
                        "frameRate": "24000/1001",
                        "label": "1280x720",
                        "bitrate": 3148466,
                        "maxBitrate": 3148466,
                        "width": "1280",
                        "height": "720"
                    }
                ]
            },
            {
                "odatatype": "#Microsoft.Media.AacAudio",
                "channels": 2,
                "samplingRate": 48000,
                "bitrate": 128000,
                "profile": "AacLc",
                "label": "aacAudio"
            }
        ]
    },
    "createdBy": "user@company.com",
    "createdAt": "2019-09-20T07:56:54.051Z",
    "__v": 0,
    "modifiedAt": "2019-09-20T09:09:33.612Z",
    "modifiedBy": "user@company.com"
}

Channels - post

POST https://admin.serverside.ai/api/v2/channels/

Creates a channel.

Headers

Name
Type
Description

x-api-key

string

Your serverside.ai API key

Request Body

Name
Type
Description

state

string

'enabled' or 'disabled'. Defaults to 'disabled'

profile

object

An appropriate encoding profile. If not provided, an AMS profile is automatically generated by analyzing the manifest.

sourceManifestUrl

string

URL that points to a valid HLS or DASH manifest

name

string

The name of your channel

apiKey

string

Any API key that secures the output stream

adSlateManifestUrl

string

Defaulted from the appropriate system settings if blank

adSource

object

{system, url, params} Defaulted from the appropriate system settings if empty

{
    "adSlateManifestUrl": "https://utvcdnzgwo2hot2llvudata.blob.core.windows.net/ch5223id76/adslate.m3u8",
    "_id": "<id>",
    "name": "Test Channel 3",
    "type": "hls-live",
    "state": "disabled",
    "apiKey": "<API KEY>",
    "tenant": "Your Company",
    "sourceManifestUrl": "https://utvcdnzgwo2hot2llvudata.blob.core.windows.net/ch5223id88/ch5223id88_master.m3u8",
    "adSource": {
        "system": "spotx",
        "url": "https://search.spotxchange.com/vast/3.0/123456"
    },
    "adConditioner": {
        "system": "nemo2",
        "apiUrl": "https://staging.serverside.ai/api/v2",
        "apiKey": "<API KEY>"
    },
    "id": "<UUID>",
    "profile": {
        "type": "ams",
        "codecs": [
            {
                "odatatype": "#Microsoft.Media.H264Video",
                "keyFrameInterval": "PT2S",
                "layers": [
                    {
                        "odatatype": "#Microsoft.Media.H264Layer",
                        "profile": "Main",
                        "level": "3.1",
                        "bufferWindow": "PT5S",
                        "bFrames": 3,
                        "referenceFrames": 3,
                        "adaptiveBFrame": true,
                        "frameRate": "24000/1001",
                        "label": "320x180",
                        "bitrate": 474117,
                        "maxBitrate": 474117,
                        "width": "320",
                        "height": "180"
                    },
                    {
                        "odatatype": "#Microsoft.Media.H264Layer",
                        "profile": "Main",
                        "level": "3.1",
                        "bufferWindow": "PT5S",
                        "bFrames": 3,
                        "referenceFrames": 3,
                        "adaptiveBFrame": true,
                        "frameRate": "24000/1001",
                        "label": "480x272",
                        "bitrate": 760001,
                        "maxBitrate": 760001,
                        "width": "480",
                        "height": "272"
                    },
                    {
                        "odatatype": "#Microsoft.Media.H264Layer",
                        "profile": "Main",
                        "level": "3.1",
                        "bufferWindow": "PT5S",
                        "bFrames": 3,
                        "referenceFrames": 3,
                        "adaptiveBFrame": true,
                        "frameRate": "24000/1001",
                        "label": "640x360",
                        "bitrate": 1127459,
                        "maxBitrate": 1127459,
                        "width": "640",
                        "height": "360"
                    },
                    {
                        "odatatype": "#Microsoft.Media.H264Layer",
                        "profile": "Main",
                        "level": "3.1",
                        "bufferWindow": "PT5S",
                        "bFrames": 3,
                        "referenceFrames": 3,
                        "adaptiveBFrame": true,
                        "frameRate": "24000/1001",
                        "label": "960x540",
                        "bitrate": 2036100,
                        "maxBitrate": 2036100,
                        "width": "960",
                        "height": "540"
                    },
                    {
                        "odatatype": "#Microsoft.Media.H264Layer",
                        "profile": "Main",
                        "level": "3.1",
                        "bufferWindow": "PT5S",
                        "bFrames": 3,
                        "referenceFrames": 3,
                        "adaptiveBFrame": true,
                        "frameRate": "24000/1001",
                        "label": "1280x720",
                        "bitrate": 3148466,
                        "maxBitrate": 3148466,
                        "width": "1280",
                        "height": "720"
                    }
                ]
            },
            {
                "odatatype": "#Microsoft.Media.AacAudio",
                "channels": 2,
                "samplingRate": 48000,
                "bitrate": 128000,
                "profile": "AacLc",
                "label": "aacAudio"
            }
        ]
    },
    "createdBy": "API-Key",
    "createdAt": "2019-09-18T12:20:49.373Z",
    "__v": 0
}

Required Fields

The minimum information required to create a channel using the serverside.ai API is:

  • sourceManifestUrl - URL that points to a valid HLS or DASH manifest. The serverside.ai API can automatically detect which.

  • name - A human-readable name for your channel.

  • adSource - e.g.

{
    "system": "spotx", 
    "url": "https://search.spotxchange.com/vast/3.0/123456", 
    "params": {}
 }
  • adSlateManifestUrl – e.g. https://xyxyxyxyxyxyxyyx.blob.core.windows.net/ch1234id99/adslate.m3u8

Optional fields

The following optional fields can also be supplied:

  • apiKey – this is the API Key that secures access to the output stream, i.e. outputUri – if any such key is required.

  • profile - an AMS (Azure Media Services) encoding profile is automatically generated by analyzing the manifest if not provided.

  • state - defaults to 'disabled'

Process

First, the manifest is checked.

A 500 - 'Manifest Invalid' error will be reported if:

  • The manifest cannot be found

  • It is not a valid HLS or DASH manifest

  • Its content is not correctly formatted so that the serverside.ai system can understand it

A 400 - 'No URL for the external system defined' error will be reported if:

  • The system that provides the ad server information is not defined

  • The system that provides the ad server information is incorrectly defined

Assuming this first check succeeds, the manifest is then analyzed, and the corresponding (AMS) profile, adSlateManifestUrl and adSource are generated (if not provided). adConditioner and outputUri are always automatically generated. These additional parameters are required to actually create the channel.

The channel is initially persisted using a 2nd API (SSAI API) which is connected to a REDIS cluster. Only when this step succeeds is the channel then written to the serverside.ai data store.

A channel is created in a `disabled` state and must be deliberately enabled, either in the Serverside.ai app or by an update call.

Errors

Errors from the analysis stage contain a JSON representation of all errors found in the analysis, to help in troubleshooting (See Detailed channel analysis errors ).

Example body

{
    "sourceManifestUrl": "https://fdgfdgfdgfdgfgdfgf.blob.core.windows.net/ch1234id99/ch1234id99_master.m3u8",
    "name": "Test Channel",
    "state": "enabled",
    "adSlateManifestUrl": "https://fdgfdgfdgfdgfgdfgf.blob.core.windows.net/ch1234id99/adslate.m3u8",
    "adSource": {
        "system": "spotx",
        "url": "https://search.spotxchange.com/vast/3.0/249832"
    },
    "profile": {
        "type": "ams",
        "codecs": [
            {
                "odatatype": "#Microsoft.Media.H264Video",
                "keyFrameInterval": "PT2S",
                "layers": [                   
                    {
                        "odatatype": "#Microsoft.Media.H264Layer",
                        "profile": "Main",
                        "level": "3.1",
                        "bufferWindow": "PT5S",
                        "bFrames": 3,
                        "referenceFrames": 3,
                        "adaptiveBFrame": true,
                        "frameRate": "24000/1001",
                        "label": "960x540",
                        "bitrate": 2036100,
                        "maxBitrate": 2036100,
                        "width": "960",
                        "height": "540"
                    },
                    {
                        "odatatype": "#Microsoft.Media.H264Layer",
                        "profile": "Main",
                        "level": "3.1",
                        "bufferWindow": "PT5S",
                        "bFrames": 3,
                        "referenceFrames": 3,
                        "adaptiveBFrame": true,
                        "frameRate": "24000/1001",
                        "label": "1280x720",
                        "bitrate": 3148466,
                        "maxBitrate": 3148466,
                        "width": "1280",
                        "height": "720"
                    }
                ]
            },
            {
                "odatatype": "#Microsoft.Media.AacAudio",
                "channels": 2,
                "samplingRate": 48000,
                "bitrate": 128000,
                "profile": "AacLc",
                "label": "aacAudio"
            }
        ]
    },
}

Channels - put

PUT https://admin.serverside.ai/api/v2/channels/:id

Updates the specified channel.

Path Parameters

Name
Type
Description

id

string

id (uuid) of the channel to update

Headers

Name
Type
Description

x-api-key

string

Your serverside.ai API key

Request Body

Name
Type
Description

profile

object

An appropriate encoding profile. If nto provided, an AMS profile is automatically generated from the manifest

state

boolean

Controls whether the channel is enabled

sourceManifestUrl

string

URL that points to a valid HLS or DASH manifest

name

string

The name of your channel

apiKey

string

Any API key that secures the output stream

adSlateManifestUrl

string

Defaulted from the appropriate system settings if not provided

adSource

object

{system, url, params}. Defaulted from the appropriate system settings if empty.

(See POST for field details and body example)

Mandatory fields for update

  • sourceManifestUrl

  • adSlateManifestUrl

  • adSource

  • name

Other fields that can be updated

  • state - can be set to 'enabled' or 'disabled' There exist further states but they are set by the system only, and should be considered as equivalent to 'disabled'

  • apiKey

  • profile

Process

If no profile is provided, the manifest is re-analyzed on update. See POST for further details on the analysis.

Errors

Errors from the analysis stage contain a JSON representation of all errors found in the analysis, to help in troubleshooting (See Detailed channel analysis errors ).

Channels - setState

PUT https://admin.serverside.ai/api/v2/channels/setState/:id

Enables or disables a channel.

Path Parameters

Name
Type
Description

id

string

The channel's id (uuid)

Request Body

Name
Type
Description

state

string

'disabled' or 'enabled'

{
    "state": "disabled",
    "id": "<CHANNEL_ID>",
    "modifiedBy": "API-Key",
    "modifiedAt": "2020-02-10T16:40:19.486Z",
    "tenant": "Nowtilus GmbH"
}

Channels - delete

DELETE https://admin.serverside.ai/api/v2/channels/:id

Deletes the specified channel.

Path Parameters

Name
Type
Description

id

string

The channel's id (uuid)

Headers

Name
Type
Description

x-api-key

string

Your serverside.ai API key

1

Last updated