Channels Management API

Introduction

This API is used to manage Linear Channels.

Authorization

All requests made to the following API endpoints require a token.

The token should be provided in the headers as:

Authorization: Bearer <token>

The token should either be a valid user token received via the Login API, or a generated token.

Generated token

A token consists of 40 character long hex value. The value has two different parts:

Current time 32 bits / 8 chars - current timestamp in number of seconds since UNIX Epoch
Signature 128 bits / 32 chars - the MD5 hash of (organizationId + ":" + Current Time + ":" + Secret), where '+' is a string concatenation.

Example

Organization ID: 13509
Current Time: 1622091600000 (27.05.2021 05:00:00 UTC) -> '60af2750'
Secret: 'secret'
Signature: MD5('13509:60af2750:secret') -> 'cdbd38964c61a03f961763f0e25a09c0'
Generated token: 60af2750cdbd38964c61a03f961763f0e25a09c0

API Path: Channels Management

/api/channels/admin

Create Channel

Creates a new Linear Channel.

Request

Method: POST

Query Parameters

Name	Value	Requirement	Info
action	addChannel	Mandatory
organizationId	Number	Mandatory	Suite Organization ID

Body

Name	Data type	Requirement	Info	Default
name	String	Mandatory	Name of the channel	N/A
description	String	Optional	Channel description	""
logicalChannelNumber	Number	Optional	Channel number	0
aspectRatio	String	Optional	One of: "", "4:3", "16:9"	""
primaryLanguage	String	Optional	Primary language, must be a locale code in the form of en_US, fi_FI etc.	"en_US"
audioOnly	Boolean	Optional	Set to true if the channel is an audio only channel.	false
categories	Array	Optional	An array of category ID's that the channel should belong to.	[]
autoRecord	Boolean	Optional	Set to 'true' if the channel should be recorded automatically when it has an incoming stream.	false
quality	Number	Optional	One of: 0 (HD), 1 (SD)	0
isPublic	Boolean	Optional	Whether the channel should be a public or private channel.	true
isExclusive	Boolean	Optional	Whether the channel should be exclusive.	false
locationRestrictions	Array	Optional	An array of location ID's.	[]

Example

Example body content

{
"name": "Channel Example",
"description": "This is just an example.",
"logicalChannelNumber": 1,
"aspectRatio": "16:9",
"primaryLanguage": "fi_FI",
"audioOnly": false,
"categories": [],
"autoRecord": true,
"quality": 1,
"isPublic": true,
"isExclusive": false,
"locationRestrictions": []
}

Example request

curl -i -H Authorization\:\ Bearer\ <user_token or generated_token> -XPOST https\://suiterc.icareus.com/api/channels/admin\?action\=addChannel\&organizationId\=2631609 -d \{'
'\ \"name\"\:\ \"Channel\ Example\"\,'
'\ \"description\"\:\ \"This\ is\ just\ an\ example.\"\,'
'\ \"logicalChannelNumber\"\:\ 1\,'
'\ \"aspectRatio\"\:\ \"16\:9\"\,'
'\ \"primaryLanguage\"\:\ \"fi_FI\"\,'
'\ \"audioOnly\"\:\ false\,'
'\ \"categories\"\:\ \[\]\,'
'\ \"autoRecord\"\:\ true\,'
'\ \"quality\"\:\ 1\,'
'\ \"isPublic\"\:\ true\,'
'\ \"isExclusive\"\:\ false\,'
'\ \"locationRestrictions\"\:\ \[\]'
'\}'
'

Response

A successful response will have the HTTP status code 200 and will contain "status": "ok" in the JSON response.

A failed response will have a non-200 status code and will contain "status": "error" in the JSON response (except in certain cases of internal server errors)

Example of a successful response

{
  "status": "ok",
  "channel": {
    "locationRestrictions": [],
    "isExclusive": false,
    "originAddress": "10.0.10.208",
    "aspectRatio": "16:9",
    "largeIcon": "",
    "isPublic": true,
    "primaryLanguage": "fi_FI",
    "cdnAddress": "suiterc2.icareus.com",
    "smallIcon": "",
    "logicalChannelNumber": 1,
    "serviceId": 12346501,
    "mediumIcon": "",
    "description": "This is just an example.",
    "name": "Channel Example",
    "quality": 1,
    "autoRecord": true,
    "streams": {
      "total": 12,
      "transcoder": 0,
      "items": [
        {
          "preset_name": "SD 576p, 1024x576 (1024kbps)",
          "preset_id": 11508,
          "devices": [
            {
              "protection": "",
              "typeName": "Desktop - Linux",
              "id": 12346512,
              "url": "https://suiterc2.icareus.com/suitelive/12346501/playlist.m3u8"
            },
            {
              "protection": "",
              "typeName": "Desktop - Linux",
              "id": 12346518,
              "url": "https://suiterc2.icareus.com/suitelive/12346501/playlist.m3u8"
            }
          ]
        }, //... and so on
      ],
      "adaptiveItems": [
        {
          "linearDeviceIds": [
            12346502,
            12346503,
            12346504,
            12346505,
            12346506,
            12346507,
            12346508,
            12346509,
            12346510,
            12346511
          ],
          "protection": "",
          "typeName": "Chrome Browser (Windows)",
          "presetNames": "SD 576p, 1024x576 (1024kbps), HD 720p, 1280x720 (2048kbps), Full HD 1080p, 1920x1080 (2560kbps), Audio 96K mp3, Fallback (Master size and bitrate), SD 576p, 1024x576 (1024kbps), HD 720p, 1280x720 (2048kbps), Full HD 1080p, 1920x1080 (2560kbps), Audio 96K mp3, Fallback (Master size and bitrate)",
          "typeId": 3652901,
          "url": "https://suiterc2.icareus.com/suitelive/12346501/playlist.m3u8"
        }, //... and so on
      ],
      "playlist": 0
    },
    "categories": [],
    "ingestUrl": "rtmp://live-eu1.icareus.com:1935/suitelive",
    "streamName": 12346501,
    "audioOnly": false
  }
}

Example of an error response

{
  "errors": {
    "categories": [
      {
        "message": "invalid category ids: 12345 890 ",
        "name": "invalid-value"
      }
    ],
    "primaryLanguage": [
      {
        "message": "finnish is not a valid language id",
        "name": "invalid-value"
      }
    ]
  },
  "status": "error"
}

Update Channel

Updates an existing Linear Channel.

Note: Only fields provided in the request body will be updated.

h3. Request

Method: POST

Query Parameters

Name	Value	Requirement	Info
action	updateChannel	Mandatory
organizationId	Number	Mandatory	Suite Organization ID
channelId	Number	Mandatory	Suite Linear Channel serviceId

Body

Name	Data type	Requirement	Info
name	String	Optional	Name of the channel.
description	String	Optional	Channel description.
logicalChannelNumber	Number	Optional	Channel number.
aspectRatio	String	Optional	One of: "", "4:3", "16:9"
primaryLanguage	String	Optional	Primary language, must be a locale code in the form of en_US, fi_FI etc.
audioOnly	Boolean	Optional	Set to true if the channel is an audio only channel.
categories	Array	Optional	An array of cateogy ID's that the channel should belong to.
autoRecord	Boolean	Optional	Set to true if the channel should be recorded automatically when it has an incoming stream.
quality	Number	Optional	One of: 0 (HD), 1 (SD)
isPublic	Boolean	Optional	Whether the channel should be a public or private channel.
isExclusive	Boolean	Optional	Whether the channel should be exclusive.
locationRestrictions	Array	Optional	An array of location ID's.

Example

Example body content

{
 "description": "Updating the description.",
 "logicalChannelNumber": 69
}

Example request

curl -i -H Authorization\:\ Bearer\ <user_token or generated_token> -XPOST https\://suiterc.icareus.com/api/channels/admin\?action\=updateChannel\&organizationId\=2631609\&channelId\=12346501 -d \{'
'\ \"description\"\:\ \"Updating\ the\ description.\"\,'
'\ \"logicalChannelNumber\"\:\ 69'
'\}'
'

Response

A successful response will have the HTTP status code 200 and will contain "status": "ok" in the JSON response.

A failed response will have a non-200 status code and will contain "status": "error" in the JSON response (except in certain cases of internal server errors).

Example of a successful response

{
  "status": "ok",
  "channel": {
    "isExclusive": false,
    "locationRestrictions": [],
    "originAddress": "10.0.10.208",
    "aspectRatio": "16:9",
    "largeIcon": "",
    "isPublic": true,
    "primaryLanguage": "fi_FI",
    "cdnAddress": "suiterc2.icareus.com",
    "smallIcon": "",
    "logicalChannelNumber": 69,
    "serviceId": 12346501,
    "mediumIcon": "",
    "description": "Updating the description.",
    "name": "Channel Example",
    "quality": 1,
    "autoRecord": true,
    "streams": {
      "total": 12,
      "transcoder": 0,
      "items": [
        {
          "preset_name": "SD 576p, 1024x576 (1024kbps)",
          "preset_id": 11508,
          "devices": [
            {
              "protection": "",
              "typeName": "Desktop - Linux",
              "id": 12346512,
              "url": "https://suiterc2.icareus.com/suitelive/12346501/playlist.m3u8"
            },
            {
              "protection": "",
              "typeName": "Desktop - Linux",
              "id": 12346518,
              "url": "https://suiterc2.icareus.com/suitelive/12346501/playlist.m3u8"
            }
          ]
        }, //... and so on
      ],
      "adaptiveItems": [
        {
          "linearDeviceIds": [
            12346502,
            12346503,
            12346504,
            12346505,
            12346506,
            12346507,
            12346508,
            12346509,
            12346510,
            12346511
          ],
          "protection": "",
          "typeName": "Chrome Browser (Windows)",
          "presetNames": "SD 576p, 1024x576 (1024kbps), HD 720p, 1280x720 (2048kbps), Full HD 1080p, 1920x1080 (2560kbps), Audio 96K mp3, Fallback (Master size and bitrate), SD 576p, 1024x576 (1024kbps), HD 720p, 1280x720 (2048kbps), Full HD 1080p, 1920x1080 (2560kbps), Audio 96K mp3, Fallback (Master size and bitrate)",
          "typeId": 3652901,
          "url": "https://suiterc2.icareus.com/suitelive/12346501/playlist.m3u8"
        }, //... and so on
      ],
      "playlist": 0
    },
    "categories": [],
    "ingestUrl": "rtmp://live-eu1.icareus.com:1935/suitelive",
    "streamName": 12346501,
    "audioOnly": false
  }
}

Example of an error response

{
  "errors": {
    "name": [
      {
        "message": "minimum length: 1",
        "name": "invalid-value"
      }
    ]
  },
  "status": "error"
}

Delete Channel

Delete a Linear Channel.

Request

Method: POST

Query Parameters

Name	Value	Requirement	Info
action	deleteChannel	Mandatory
organizationId	Number	Mandatory	Suite Organization ID
channelId	Number	Mandatory	Suite Linear Channel serviceId

Example

Example request

curl -i -H Authorization\:\ Bearer\ <user_token or generated_token> -XPOST https\://suiterc.icareus.com/api/channels/admin\?action\=deleteChannel\&organizationId\=2631609\&channelId\=12346701

Response

A successful response will have the HTTP status code 200 and will contain "status": "ok" in the JSON response.

A failed response will have a non-200 status code and will contain "status": "error" in the JSON response (except in certain cases of internal server errors).

Example of a successful response

{
  "message": "12346701",
  "status": "ok"
}

Example of an error response

{
  "message": "invalid-channel-id",
  "status": "error"
}

GET Channel

Get information of a Linear Channel.

Request

Method: GET

Query Parameters

Name	Value	Requirement	Info
action	getChannel	Mandatory
organizationId	Number	Mandatory	Suite Organization ID
channelId	Number	Mandatory	Suite Linear Channel serviceId

Example

Example request

curl -i -H Authorization\:\ Bearer\ <user_token or generated_token> -XGET https\://suiterc.icareus.com/api/channels/admin\?action\=getChannel\&organizationId\=2631609\&channelId\=12346001

Response

A successful response will have the HTTP status code 200 and will contain "status": "ok" in the JSON response.

A failed response will have a non-200 status code and will contain "status": "error" in the JSON response (except in certain cases of internal server errors).

Example of a successful response

A successful response will contain the same data as the channel creation and channel update calls.

Example of an error response

{
  "message": "invalid-channel-id",
  "status": "error"
}

GET Channels

Get a list of all the channels of a given Organization.

Request

Method: GET

Query Parameters

Name	Value	Requirement	Info
action	getChannels	Mandatory
organizationId	Number	Mandatory	Suite Organization ID

Example

Example request

curl -i -H Authorization\:\ Bearer\ <user_token or generated_token> -XGET https\://suiterc.icareus.com/api/channels/admin\?action\=getChannels\&organizationId\=2631609\

Response

A successful response will have the HTTP status code 200 and will contain "status": "ok" in the JSON response.

A failed response will have a non-200 status code and will contain "status": "error" in the JSON response (except in certain cases of internal server errors).

Example of a successful response

A successful response will contain "status": "ok", "channels": []

Where the channels array is a list of objects similar to those returned by the channel creation and channel update calls.

Example of an error response

{
  "message": "invalid-organization-id",
  "status": "error"
}

Upload channel icon

Upload a channel icon to an existing Linear Channel.

Note: Request must be of type multipart/form-data

h3. Request

Method: POST

Query Parameters

Name	Value	Requirement	Info
action	addChannelIcon	Mandatory
organizationId	Number	Mandatory	Suite Organization ID
channelId	Number	Mandatory	Suite Linear Channel serviceId

Multipart/form-data

Name	Value	Requirement	Info
channelIcon	Image File	Mandatory	The image file you wish to upload.

Example

Example request

curl --location -XPOST 'https://suiterc.icareus.com/api/channels/admin?action=addChannelIcon&organizationId=2631609&channelId=12346001' \
-H 'Content-Type: multipart/form-data' \
-H 'Authorization: Bearer <user_token or generated_token>' \
-F 'channelIcon=@"/path/to/Pictures/wizard.gif"'

Response

A successful response will have the HTTP status code 200 and will contain "status": "ok" in the JSON response.

A failed response will have a non-200 status code and will contain "status": "error" in the JSON response (except in certain cases of internal server errors).

Example of a successful response

A successful response will contain the same data as the channel creation and channel update calls.

Example of an error response

{
  "message": "invalid-channel-id",
  "status": "error"
}

Related Articles
Introduction to EPG Management
General Icareus Playout EPG Server is used to broadcast the TV program information and to generate the necessary service information. It provides many different ways to ingest the EPG/EIT data. Each EPG source can be managed based on the settings ...
Introduction to Channels and Live Streaming
Introduction Icareus Suite's Channels Management provides tools for service administrators to manage the channels and live streaming. Channels are the streams of video content that can be everything from TV channels to web cam streams. Each ...
Adding new Channels
FEATURES Icareus Suite's Channel Management Details -sheet is used for managing single channel configuration or adding a new Channel. The parameters that are used with channels are e.g.: # Parameter Comments Mandatory 1 ORGANIZATION ID ...
Account Management API (ENG)
INTRODUCTION The API is used to manage Icareus Suite users and organisations. USE CASES Adding sub organization API Calls flow to add sub organization: Create an organization Add User Assign User Assign User role API PATH /delegate/account API ...
Analytics API (ENG)
INTRODUCTION This API stores video access/usage statistics for the linear channels and vod items. API PATH /api/analytics API METHODS ADDING NEW RECORD Adds a new analytics record of either on-demand video usage or linear channel viewing statistics ...

Channels Management API

Channels Management API

Introduction

Authorization

Generated token

Example

API Path: Channels Management

Create Channel

Request

Query Parameters

Body

Example

Response

Update Channel

Query Parameters

Body

Example

Response

Delete Channel

Request

Query Parameters

Example

Response

GET Channel

Request

Query Parameters

Example

Response

GET Channels

Request

Query Parameters

Example

Response

Upload channel icon

Query Parameters

Multipart/form-data

Example

Response

Related Articles

Introduction to EPG Management

Introduction to Channels and Live Streaming

Adding new Channels

Account Management API (ENG)

Analytics API (ENG)