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

200

{
    "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

200

[
  {
    "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

200 If the channel is not found, the response body is blank, else similar to the below response.

{
    "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": "[e-mail]",
    "createdAt": "2019-09-20T07:56:54.051Z",
    "__v": 0,
    "modifiedAt": "2019-09-20T09:09:33.612Z",
    "modifiedBy": "[e-mail]"
}

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

201

{
    "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
}

422

{
    "name": "ValidationError",
    "message": "Parameters validation error!",
    "code": 422,
    "type": "VALIDATION_ERROR",
    "data": [
        {
            "keyword": "required",
            "dataPath": "",
            "schemaPath": "#/required",
            "params": {
                "missingProperty": "name"
            },
            "message": "should have required property 'name'"
        }
    ]
}

500 See "Detailed channel analysis errors" page for a list of possible errors

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.

200 If the update succeeds, the channel is sent back. Format as for POST.

404

{
    "type": "NOT_FOUND",
    "code": 404,
    "message": "Not found",
    "name": "NotFoundError"
}

422 If the body is empty or lacks required parameters, a response like below is returned.

{
    "type": "VALIDATION_ERROR",
    "code": 422,
    "message": "Parameters validation error!",
    "data": [
        {
            "keyword": "required",
            "dataPath": "",
            "schemaPath": "#/required",
            "params": {
                "missingProperty": "name"
            },
            "message": "should have required property 'name'"
        }
    ],
    "name": "ValidationError"
}

(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'

200

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

500 Invalid state sent in body, e.g. { "state": "rubbish" }

{
    "type": "ERR_SSAI_API",
    "code": 500,
    "message": "SSAI API update error",
    "data": "The \"body\" body parameter is invalid ({\"state\":\"rubbish\"}) \nJSON Schema validation error. \nData path: \"/state\" \nSchema path: \"/properties/state/type\" \nNo enum match for: \"rubbish\"",
    "name": "MoleculerError"
}

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

200 Returns number of records deleted (should always be 0 or 1)

1