Contact support
    • Serverside.ai
    • REST API

    Channels: API routes

    Table of Contents

    Overview Channels: GET schema Headers 200 GET channels Query parameters Headers 200 Channels: GET by ID Path parameters Headers 200: The response body is blank if the channel is not found; otherwise, it contains the channel object. Channels: POST Headers Request body 201 422 500: See the "Channels: detailed analysis errors" page for possible errors. Required fields Optional fields Process Errors Example body Channels: PUT Path parameters Headers Request body 200: The update succeeded; the channel is returned in the same format as for POST. 404 422 If the body is empty or lacks required parameters, a response like below is returned. Mandatory fields for update Other fields that can be updated Process Errors Channels: setState Path parameters Request body 200 500: Invalid state sent in the request body, for example, { "state": "rubbish" }. Channels: DELETE Path parameters Headers 200: Returns the number of records deleted (always 0 or 1)

    Overview

    This document describes the channels API, which provides endpoints to create, retrieve, update, enable, and delete streaming channels in the Serverside.ai platform. It also outlines the full channel JSON schema and the required fields for channel configuration.

    Channels: GET schema

    GET  https://mydomain.com/api/v2/channels/schema

    Returns the full channel JSON schema.

    Headers

    Field 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"
    ]
}
     
     

    GET channels

    GET  https://mydomain.com/api/v2/channels/

    Retrieves the list of your channels.

    Query parameters

    Field Type Description
    profileHash string The profile hash of the channel you want to find.
    sort string The field name to sort by, for example, name. For descending order, use -name.
    offset number The index of the first record to return, given the sort order. Useful for paging.
    limit number The maximum number of records to return.
    search object The object containing search terms. Fields searched are name, id, titleId; name and id use regex wildcard searches, for example, *test*, and titleId is an exact match.

    Headers

    Field 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://mydomain.com/api/v2/channels/:id

    Retrieves an individual channel by its ID.

    Path parameters

    FIeld Type Description
    id string The ID of the channel you want to retrieve.

    Headers

    Field Type Description
    x-api-key string Your Serverside.ai API key.

    200: The response body is blank if the channel is not found; otherwise, it contains the channel object.

    {
    "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://mydomain.com/api/v2/channels/

    Creates a channel.

    Headers

    Field Type Description
    x-api-key string Your Serverside.ai API key.

    Request body

    Field Type Description
    state string The state of the channel, either enabled or disabled. Defaults to disabled.
    profile object The encoding profile for the channel. If not provided, an AMS profile is automatically generated by analyzing the manifest.
    sourceManifestUrl string The URL that points to a valid HLS or DASH manifest.
    name string The name of your channel.
    apiKey string The API key that secures the output stream.
    adSlateManifestUrl string The URL for the ad slate manifest. If left blank, it defaults to the appropriate system settings.
    adSource object The ad source object containing system, url, and params. If empty, it defaults to the appropriate system settings.

    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 the "Channels: detailed analysis errors" page for possible errors.

     

     
     

    Required fields

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

    • sourceManifestUrl: the URL that points to a valid HLS or DASH manifest. The Serverside.ai API can automatically detect the type.
    • name: the human-readable name of your channel.
    • adSource: the ad source object containing system, url, and params. Example:
      {
    "system": "spotx", 
    "url": "https://search.spotxchange.com/vast/3.0/123456", 
    "params": {}
 }
    • adSlateManifestUrl: the URL for the ad slate manifest. Example: https://xyxyxyxyxyxyxyyx.blob.core.windows.net/ch1234id99/adslate.m3u8

    Optional fields

    The following optional fields can also be supplied:

    • apiKey: the API key that secures access to the output stream (outputUri), if required,
    • profile: the AMS (Azure Media Services) encoding profile. If not provided, a profile is automatically generated by analyzing the manifest.
    • state: the state of the channel, either enabled or disabled. 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 for the Serverside.ai system to understand. 

    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. 

    If 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 second API (SSAI API), which is connected to a Redis cluster. Only when this step succeeds is the channel 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 via an update call.

    Errors

    Errors from the analysis stage are provided as a JSON representation of all issues found to aid troubleshooting. For more information, see Channels: detailed 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://mydomain.com/api/v2/channels/:id

    Updates the specified channel.

    Path parameters

    Field Type Description
    id string The ID (UUID) of the channel to update.

    Headers

    Field Type Description
    x-api-key string Your Serverside.ai API key.

    Request body

    Field Type Description
    profile object The encoding profile for the channel. If not provided, an AMS profile is automatically generated from the manifest.
    state boolean The state of the channel, which controls whether it is enabled.
    sourceManifestUrl string The URL that points to a valid HLS or DASH manifest.
    name string The name of your channel.
    apiKey string The API key that secures the output stream.
    adSlateManifestUrl string The URL for the ad slate manifest. Defaults to the appropriate system settings if not provided.
    adSource object The ad source object containing system, url, and params. Defaults to the appropriate system settings if empty.

    200: The update succeeded; the channel is returned in the same 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"
}
     
     

    For field details and body example, see Channels: POST.

    Mandatory fields for update

    • sourceManifestUrl
    • adSlateManifestUrl
    • adSource
    • name

    Other fields that can be updated

    • state: the state of the channel, which can be set to enabled or disabled. Other system-only states exist but should be treated as disabled.
    • apiKey
    • profile

    Process

    If no profile is provided, the manifest is re-analyzed during the update. For further details on the analysis, see Channels: POST.

    Errors

    Errors from the analysis stage include a JSON representation of all issues found to aid troubleshooting. For more information, see Channels: detailed analysis errors.

    Channels: setState

    PUT https://mydomain.com/api/v2/channels/setState/:id

    Enables or disables a channel.

    Path parameters

    Field Type Description
    id string The ID (UUID) of the channel.

    Request body

    Field Type Description
    state string The state of the channel, either 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 the request body, for example, { "state": "rubbish" }.

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

    Channels: DELETE

    DELETE  https://mydomain.com/api/v2/channels/:id

    Deletes the specified channel.

    Path parameters

    Field Type Description
    id string The ID (UUID) of the channel.

    Headers

    Name Type Description
    x-api-key string Your Serverside.ai API key.

    200: Returns the number of records deleted (always 0 or 1)

    1
     
     

    RELATED ARTICLES