Channels - get schema
GET https://admin.serverside.ai/api/v2/channels/schema
Returns the full channel JSON schema
Name Type Description Your serverside.ai API key
200
Copy {
"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 The profile hash of the channel you want to find
Field name to sort by. e.g. 'name'. For descending order, use e.g. '-name'
Given the sort, which record to start the returned dataset from. Useful for paging.
Max number of records to return
e.g. 'test'. Fields searched are name, id, titleId. name and id are regex wildcard searches, e.g '*test*', titleId is exact match.
Name Type Description Your serverside.ai API key
200
Copy [
{
"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 The id of the channel you want.
Name Type Description Your serverside.ai API Key
200 If the channel is not found, the response body is blank, else similar to the below response.
Copy {
"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.
Name Type Description Your serverside.ai API key
Request Body
Name Type Description 'enabled' or 'disabled'. Defaults to 'disabled'
An appropriate encoding profile. If not provided, an AMS profile is automatically generated by analyzing the manifest.
URL that points to a valid HLS or DASH manifest
Any API key that secures the output stream
Defaulted from the appropriate system settings if blank
{system, url, params} Defaulted from the appropriate system settings if empty
201 422 500 See "Detailed channel analysis errors" page for a list of possible errors
Copy {
"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
}
Copy {
"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'"
}
]
} 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.
Copy {
"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
Copy {
"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 (uuid) of the channel to update
Name Type Description Your serverside.ai API key
Request Body
Name Type Description An appropriate encoding profile. If nto provided, an AMS profile is automatically generated from the manifest
Controls whether the channel is enabled
URL that points to a valid HLS or DASH manifest
Any API key that secures the output stream
Defaulted from the appropriate system settings if not provided
{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 422 If the body is empty or lacks required parameters, a response like below is returned.
Copy {
"type": "NOT_FOUND",
"code": 404,
"message": "Not found",
"name": "NotFoundError"
}
Copy {
"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
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'
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
Request Body
200 500 Invalid state sent in body, e.g. { "state": "rubbish" }
Copy {
"state": "disabled",
"id": "<CHANNEL_ID>",
"modifiedBy": "API-Key",
"modifiedAt": "2020-02-10T16:40:19.486Z",
"tenant": "Nowtilus GmbH"
}
Copy {
"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 Your serverside.ai API key
200 Returns number of records deleted (should always be 0 or 1)
