---
description: Documentation of the principal routes available in the serverside.ai API.
---

# API routes - Channels

## Channels - get schema

<mark style="color:blue;">`GET`</mark> `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 |

{% tabs %}
{% tab title="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"
    ]
}
```
{% endtab %}
{% endtabs %}

## Channels - get

<mark style="color:blue;">`GET`</mark> `https://admin.serverside.ai/api/v2/channels/`

Gets a list of your channels.&#x20;

#### 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 |

{% tabs %}
{% tab title="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
  }
]
```
{% endtab %}
{% endtabs %}

## Channels - get by id

<mark style="color:blue;">`GET`</mark> `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 |

{% tabs %}
{% tab title="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": "user@company.com",
    "createdAt": "2019-09-20T07:56:54.051Z",
    "__v": 0,
    "modifiedAt": "2019-09-20T09:09:33.612Z",
    "modifiedBy": "user@company.com"
}
```
{% endtab %}
{% endtabs %}

## Channels - post

<mark style="color:green;">`POST`</mark> `https://admin.serverside.ai/api/v2/channels/`

Creates a channel.&#x20;

#### 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                                           |

{% tabs %}
{% tab title="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
}
```
{% endtab %}

{% tab title="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'"
        }
    ]
}
```
{% endtab %}

{% tab title="500 See "Detailed channel analysis errors" page for a list of possible errors" %}
```
```
{% endtab %}
{% endtabs %}

#### 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.&#x20;

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

&#x20;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](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

<mark style="color:orange;">`PUT`</mark> `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.                               |

{% tabs %}
{% tab title="200 If the update succeeds, the channel is sent back. Format as for POST." %}
```
```
{% endtab %}

{% tab title="404 " %}
```
{
    "type": "NOT_FOUND",
    "code": 404,
    "message": "Not found",
    "name": "NotFoundError"
}
```
{% endtab %}

{% tab title="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"
}
```
{% endtab %}
{% endtabs %}

#### &#x20;(See [POST ](#channels-post)for field details and body example)

#### Mandatory fields for update

* `sourceManifestUrl`
* `adSlateManifestUrl`&#x20;
* `adSource`
* `name`&#x20;

#### 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`&#x20;
* `profile`&#x20;

#### Process

If no profile is provided, the manifest is re-analyzed on update. See [POST ](#channels-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](detailed-channel-analysis-errors) ).

## Channels - setState

<mark style="color:orange;">`PUT`</mark> `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' |

{% tabs %}
{% tab title="200 " %}
```
{
    "state": "disabled",
    "id": "<CHANNEL_ID>",
    "modifiedBy": "API-Key",
    "modifiedAt": "2020-02-10T16:40:19.486Z",
    "tenant": "Nowtilus GmbH"
}
```
{% endtab %}

{% tab title="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"
}
```
{% endtab %}
{% endtabs %}

## Channels - delete

<mark style="color:red;">`DELETE`</mark> `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 |

{% tabs %}
{% tab title="200 Returns number of records deleted (should always be 0 or 1)" %}
```
1
```
{% endtab %}
{% endtabs %}
