Archive API (ENG)

Archive API (ENG)

INTRODUCTION

This API is used to manage the content within the Archive, actions like add asset, edit asset and delete asset. All calls must be made by supplying the unique token for your organization.

API PATH

/api/archive

API CALLS

ADD ASSET V.2

Creates a new asset in the archive. This call takes meta-data only. Once an asset is successfully created, files can be added by using the addAssetFile action.

REQUEST

Method: GET/POST

Parameters:

Name
Value
Requirement
Info
organizationId
number
Mandatory
Icareus Suite organization identifier
version
string 
Mandatory 
02 - otherwise will default to version 1 
token
string
Mandatory
Secret key of the organization
action
"addAsset"
Mandatory
 
userId
number
Optional
If asset belongs to a specific Icareus Suite user
referenceId
number
Optional
If the asset is linked to an id in an external/3rd party system
groupItemId
number
Mandatory
Use 'getGroups' call to get available group item ids 
groupItemIds
string
Optional
Comma separated string of multiple groupItemIds (e.g. 1234567,12312312,666666) 
languageId
string
Mandatory
fi_FI,en_US, en_UK ...
title
string
Mandatory
Asset's title
description
string
Optional
Asset's description
programName 
string 
Optional 
Asset's program name 
seasonNumber 
number 
Optional 
Asset's season number 
episodeNumber 
number 
Optional 
Asset's episode number 
duration 
number 
Optional 
Asset's duration (seconds) 
releasedYear 
number 
Optional 
Release year of the asset 
director 
string 
Optional 
Director of the asset 
actors 
string 
Optional 
A comma separated list of actors/actresses 
spokenLanguages 
string 
Optional 
A comma separated list of spoken languages in the asset. (i.e. 'fi,en,sv') 
contentRatingIds 
string 
Optional 
A comma separated list of Content Rating ID's. i.e. '1234,1235,1236' 
contentTypeIds 
string 
Optional 
A comma separated list of Content Type ID's. i.e. '4321,4322,4323' 
tags
string
Optional
comma separated tags in one string
publishStart
number
Optional
Timestamp (milliseconds) for when to publish this item. If not given, will set to NOW
publishEnd
number
Optional
Timestamp (milliseconds) for when to un-publish this item. If not give, will never unpublish
videoQuality
number
Optional
Set 1 for HD quality, otherwise the asset will be in SD quality
thumbnailUrl
string
Optional
A valid http image url with extension. Preferred size: 1280x720
coverImageUrl 
string 
Optional 
A valid http image url with extension. Aspect ratio should preferably be that of a DVD cover. 
bannerImageUrl 
string 
Optional 
A valid http image url with extension. 

RESPONSE

{
    "status":"ok",
    "message":"asset added successfully",
    "assetId":"2222"
}

Response (Error):

{
    "status":"error",
    "message":"incorrect organizationId/token pair"
}

Same pattern applies to all acknowledgement calls. Status "ok" means a successful execution of the intended action. Status "error" will have the corresponding error information in the message parameter

UPDATE ASSET V.2

Edit or update an asset's meta data in the archive

REQUEST

Method: GET/POST

Parameters:

Name
Value
Requirement
Info
organizationId
number
Mandatory
Icareus Suite organization identifier
version
string
Mandatory
02 - Otherwise will default to version 1
token
string
Mandatory
Secret key of the organization
action
"updateAssetMeta"
Mandatory
 
assetId
number
Mandatory
Asset identifier
languageId
string
Optional
fi_FI,en_US, en_UK ...
title
string
Optional
New asset title
description
string
Optional
New asset description
groupItemIds
string
Optional
Comma separated string of multiple groupItemIds (e.g. 1234567,12312312,666666) 
programName 
string 
optional 
New asset program name 
seasonNumber 
number 
optional 
New asset season number 
episodeNumber 
number 
optional 
New asset episode number 
duration 
number 
optional 
New asset duration (seconds) 
releasedYear 
number 
Optional 
Release year of the asset 
director 
string 
Optional 
Director of the asset 
actors 
string 
Optional 
A comma separated list of actors/actresses 
spokenLanguages 
string 
Optional 
A comma separated list of spoken languages in the asset. (i.e. 'fi,en,sv') 
contentRatingIds 
string 
Optional 
A comma separated list of Content Rating ID's. i.e. '1234,1235,1236' 
contentTypeIds 
string 
Optional 
A comma separated list of Content Type ID's. i.e. '4321,4322,4323' 
tags
string
Optional
comma separated tags in one string
publishStart
number
Optional
Timestamp (milliseconds) to change the publish date/time
publishEnd
number
Optional
Timestamp (milliseconds) for change the un-publish date/time
thumbnailUrl
string
Optional
A valid http image url with extension. Preferred size: 1280x720
coverImageUrl 
string 
Optional 
A valid http image url with extension. Aspect ratio should preferably be that of a DVD cover. 
bannerImageUrl 
string 
Optional 
A valid http image url with extension. 

ADD GROUP

Adds a new group item to the account.

REQUEST

Method: GET/POST

Parameters:

Name
Value
Requirement
Info
action
"addGroup"
Mandatory
organizationId
number
Mandatory
Icareus Suite organization identifier
token
string
Mandatory
Secret key of the organization
groupType
string
Mandatory
Value: "Folders"
name
String
Mandatory
name of group
languageId
string
Mandatory
fi_FI,en_US, en_UK ...
parentId
number
Optional
groupItemId of the parent group (if want to add as subgroup)
imageUrl
string
Optional
A valid http image url with image extension. Preferred size: 1280x720 

RESPONSE

{
    "status":"ok",
    "message":"group added",
    "groupItemId":123456
}

GET GROUPS

Get a list of all groups in a single group type.

REQUEST

Method: GET

Parameters:

Name
Value
Requirement
Info
action
"getGroups"
Mandatory
organizationId
number
Mandatory
Icareus Suite organization identifier
token
string
Mandatory
Secret key of the organization
groupTypeId
number
Mandatory
Predefined ID for folders
groupTypeName
string
Mandatory (if groupTypeId not given)
Value: "Folders"
groupItemId
number
Mandatory (if groupTypeId and groupTypeName not given)
Get sub groups of some specific group item
language
string
Optional
fi_FI,en_US, en_UK ...

RESPONSE

{
"status":"ok",
    "groupItems":[
        {
            "id":1,
            "title":"Prison Break",
            "image":"http://itvsuite2.icareus.com/image/image_gallery?img_id=123",
            "groupItems":[
                {
                    "id":11,
                    "title":"Season 1",
                    "groupItems": "[]",
                    "image":"http://itvsuite2.icareus.com/image/image_gallery?img_id=123",
                },
                {
                    "id":12,
                    "title":"Season 2",
                    "groupItems": "[]",
                    "image":"http://itvsuite2.icareus.com/image/image_gallery?img_id=123",
                },
                {
                    "id":13,
                    "title":"Season 3",
                    "groupItems": "[]",
                    "image":"http://itvsuite2.icareus.com/image/image_gallery?img_id=123",
                }
            ]
        },
        {
            "id":2,
            "title":"Lost",
            "image":"http://itvsuite2.icareus.com/image/image_gallery?img_id=123",
            "groupItems":[
                {
                    "id":21,
                    "title":"Season 1",
                    "groupItems": "[]",
                    "image":"http://itvsuite2.icareus.com/image/image_gallery?img_id=123",
                },
                {
                    "id":22,
                    "title":"Season 2",
                    "groupItems": "[]",
                    "image":"http://itvsuite2.icareus.com/image/image_gallery?img_id=123",
                },
                {
                    "id":23,
                    "title":"Season 3",
                    "groupItems": "[]",
                    "image":"http://itvsuite2.icareus.com/image/image_gallery?img_id=123",
                }
            ]
        }
    ]
 
 
}

UPDATE GROUP

Updates a group item to the account.

REQUEST

Method: GET/POST

Parameters:

Name
Value
Requirement
Info
action
"updateGroup"
Mandatory
organizationId
number
Mandatory
Icareus Suite organization identifier
groupItemId
number
Mandatory
ID of group item
token
string
Mandatory
Secret key of the organization
name
String
Mandatory
name of group
languageId
string
Mandatory
fi_FI,en_US, en_UK ...
imageUrl
string
Optional
A valid http image url with image extension. Preferred size: 1280x720

RESPONSE

{
    "status":"ok",
    "message":"group updated",
    "groupItemId":123456
}

DELETE GROUP

Delete a group item from the account.

REQUEST

Method: GET/POST

Parameters:

Name
Value
Requirement
Info
action
"deleteGroup"
Mandatory
organizationId
number
Mandatory
Icareus Suite organization identifier
groupItemId
number
Mandatory
ID of group item
token
string
Mandatory
Secret key of the organization

RESPONSE

{
    "status":"ok",
    "message":"group deleted"
}

ADD ASSET

Creates a new asset in the archive. This call takes meta-data only. Once an asset is successfully created, files can be added by using the addAssetFile action.

REQUEST

Method: GET/POST

Parameters:

Name
Value
Requirement
Info
organizationId
number
Mandatory
Icareus Suite organization identifier
token
string
Mandatory
Secret key of the organization
action
"addAsset"
Mandatory
 
userId
number
Optional
If asset belongs to a specific Icareus Suite user
referenceId
number
Optional
If the asset is linked to an id in an external/3rd party system
groupItemId
number
Mandatory
Use 'getGroups' call to get available group item ids 
groupItemIds
string
Optional
Comma separated string of multiple groupItemIds (e.g. 1234567,12312312,666666) 
languageId
string
Mandatory
fi_FI,en_US, en_UK ...
title
string
Mandatory
Asset's title
description
string
Optional
Asset's description
programName 
string 
Optional 
Asset's program name 
seasonNumber 
number 
Optional 
Asset's season number 
episodeNumber 
number 
Optional 
Asset's episode number 
duration 
number 
Optional 
Asset's duration (seconds) 
tags
string
Optional
comma separated tags in one string
publishStart
number
Optional
Timestamp (milliseconds) for when to publish this item. If not given, will set to NOW
publishEnd
number
Optional
Timestamp (milliseconds) for when to un-publish this item. If not give, will never unpublish
videoQuality
number
Optional
Set 1 for HD quality, otherwise the asset will be in SD quality
thumbnailUrl
string
Optional
A valid http image url with extension. Preferred size: 1280x720

It is possible to specify encoded title and description for an asset. Base64 encoding should be used. The set of parameters is the same, except the following fields.

Name
Value
Requirement
Info
action
"addAssetEncoded"
Mandatory
 
title
string
Mandatory
Asset's title (Base64 encoding)
description
string
Optional
Asset's description (Base64 encoding)

RESPONSE

{
    "status":"ok",
    "message":"asset added successfully",
    "assetId":"2222"
}

Response (Error):

{
    "status":"error",
    "message":"incorrect organizationId/token pair"
}

Same pattern applies to all acknowledgement calls. Status "ok" means a successful execution of the intended action. Status "error" will have the corresponding error information in the message parameter

ADD ASSET FILE - VIA HTTP MULTIPART POST

Adds a file for an asset. The file is a part of API request.

REQUEST

MUST be a multipart/form-data request

Parameters:

Name
Value
Requirement
Info
organizationId
number
Mandatory
Icareus Suite organization identifier
token
string
Mandatory
Secret key of the organization
action
"addAssetFile"
Mandatory
 
assetId
number
Mandatory
Asset identifier
userId
number
Mandatory
Icareus Suite user identifier
uploadFile
file
Mandatory
Asset file
callbackUrl
string
Optional
Encoded URL that needs to be called once the file is uploaded and encoded. 
The url is called using GET request. It may contain some query string parameters. 
Icareus Suite will add one more parameter that is "status". Currently supported values are "success" and "error".
presetId
number
Optional
If the file is already encoded with a specific preset, 0 otherwise.

RESPONSE

{
    "message":"file successfully added for asset 290079",
    "status":"ok"
}

ADD ASSET FILE - VIA FILE ON LOCAL FILESYSTEM

Adds a file for an asset. The file is specified in the fileUrl request parameter.

REQUEST

Method: POST

Parameters:

Name
Value
Requirement
Info
organizationId
number
Mandatory
Icareus Suite organization identifier
token
string
Mandatory
Secret key of the organization
action
"addAssetFile"
Mandatory
 
assetId
number
Mandatory
Asset identifier
userId
number
Mandatory
Icareus Suite user identifier
fileUrl
string
Mandatory
Encoded file URL. Currently, only local file system urls are supported. 
The 'liferay' user should be able to access the file. Example: file:///mnt/upload/clips/movie.mp4
callbackUrl
string
Optional
Encoded URL that needs to be called once the file is uploaded and encoded. 
The url is called using GET request. It may contain some query string parameters. 
Icareus Suite will add one more parameter that is "status". Currently supported values are "success" and "error".
presetId
number
Optional
If the file is already encoded with a specific preset, 0 otherwise.

RESPONSE

{
    "message":"file successfully added for asset 290079",
    "status":"ok"
}

ADD ASSET FILE - VIA HTTP(S) FILE URL

Adds a file for an asset. The file is specified in the fileUrl request parameter.

REQUEST

Method: GET/POST

Parameters:

Name
Value
Requirement
Info
organizationId
number
Mandatory
Icareus Suite organization identifier
token
string
Mandatory
Secret key of the organization
action
"addAssetFileUrl"
Mandatory
 
assetId
number
Mandatory
Asset identifier
userId
number
Mandatory
Icareus Suite user identifier
fileUrl
string
Mandatory
Encoded file URL 
presetId
number
Optional
If the file is already encoded with a specific preset, 0 otherwise.

RESPONSE

{
    "message":"file successfully added for asset 290079",
    "status":"ok"
}

UPDATE ASSET

Edit or update an asset's meta data in the archive

REQUEST

Method: GET/POST

Parameters:

Name
Value
Requirement
Info
organizationId
number
Mandatory
Icareus Suite organization identifier
token
string
Mandatory
Secret key of the organization
action
"updateAssetMeta"
Mandatory
 
assetId
number
Mandatory
Asset identifier
languageId
string
Optional
fi_FI,en_US, en_UK ...
title
string
Optional
New asset title
description
string
Optional
New asset description
groupItemIds
string
Optional
Comma separated string of multiple groupItemIds (e.g. 1234567,12312312,666666) 
programName 
string 
optional 
New asset program name 
seasonNumber 
number 
optional 
New asset season number 
episodeNumber 
number 
optional 
New asset episode number 
duration 
number 
optional 
New asset duration (seconds) 
tags
string
Optional
comma separated tags in one string
publishStart
number
Optional
Timestamp (milliseconds) to change the publish date/time
publishEnd
number
Optional
Timestamp (milliseconds) for change the un-publish date/time
thumbnailUrl
string
Optional
A valid http image url with extension. Preferred size: 1280x720

UPDATE ASSET FILE

Updates a file for an asset.

REQUEST

MUST be a multipart/form-data request

Parameters:

Name
Value
Requirement
Info
organizationId
number
Mandatory
Icareus Suite organization identifier
token
string
Mandatory
Secret key of the organization
action
"updateAssetFile"
Mandatory
 
assetId
number
Mandatory
Asset identifier
fileId
number
Mandatory
Asset file identifier
file
file
Mandatory
Asset file
master
boolean
Optional
If left out, the file will not be set as the master file for that asset
presetId
number
Optional
If the file is already encoded with a specific preset

RESPONSE

{
    "status":"ok",
    "message":"asset successfully updated",
    "assetId":"2222"
}

UPDATE ASSET FILE URL

Updates a file URL for an asset.

REQUEST

Method: POST

Parameters:

Name
Value
Requirement
Info
organizationId
number
Mandatory
Icareus Suite organization identifier
token
string
Mandatory
Secret key of the organization
action
"updateAssetFileUrl"
Mandatory
 
assetId
number
Mandatory
Asset identifier
fileId
number
Mandatory
Asset file identifier
fileUrl
string 
Mandatory
Encoded file URL
master
boolean
Optional
If left out, the file will not be set as the master file for that asset
presetId
number
Optional
If the file is already encoded with a specific preset

RESPONSE

{
    "status":"ok",
    "message":"asset successfully updated",
    "assetId":"2222"
}

DELETE ASSET

Delete an asset from the archive

REQUEST

Parameters:

Name
Value
Requirement
Info
organizationId
number
Mandatory
Icareus Suite organization identifier
token
string
Mandatory
Secret key of the organization
action
"deleteAsset"
Mandatory
 
assetId
number
Mandatory
Asset identifier

RESPONSE

{
    "status":"ok",
    "message":"Successfully deleted asset"
}

NOTE: THIS CALL WILL ALSO UNPUBLISH THE ASSET FROM ALL DEVICES IT IS PUBLISHED TO

GET ALL GROUPS BY TYPE

Difference between this and getGroups is that this will also fetch hidden groups. With this you can't use to fetch groups under certain groupId. This will always return all groups.

REQUEST

Method: GET
Parameters:
Name
Value
Requirement
Info
organizationId
number
Mandatory
Icareus Suite organization identifier
token
string
Mandatory
Secret key of the organization
action
"getAllGroupsByType"
Mandatory

groupTypeId
number
Optional*
Group Type Id. Either groupTypeId or groupTypeName must be given.
groupTypeName
string
Optional*
Group Type (folders, series)
showHidden
boolean
Optional
If true will return also hidden groups
getAssetCount
boolean
Optional
Will count the amount of assets in each group.
Doesn't count assets in child groups.
This value is shown with key "assetCount"
languageId
String
Optional
fi_FI,en_US, en_UK ...

RESPONSE

Is same as in getGroups, but with inclusion of assetCount.
  1. {
  2.     "status":"ok",
  3.     "groupItems":[
  4.         {
  5.             "id":1,
  6.             "assetCount": 9,
  7.             "title":"Prison Break",
  8.             "image":"http://itvsuite2.icareus.com/image/image_gallery?img_id=123",
  9.             "groupItems":[
  10.                 {
  11.                     "id":11,
  12.                     "assetCount": 1,
  13.                     "title":"Season 1",
  14.                     "groupItems": "[]",
  15.                     "image":"http://itvsuite2.icareus.com/image/image_gallery?img_id=123",
  16.                 },
  17.                 {
  18.                     "id":12,
  19.                     "assetCount": 2,
  20.                     "title":"Season 2",
  21.                     "groupItems": "[]",
  22.                     "image":"http://itvsuite2.icareus.com/image/image_gallery?img_id=123",
  23.                 },
  24.                 {
  25.                     "id":13,
  26.                     "assetCount": 0,
  27.                     "title":"Season 3",
  28.                     "groupItems": "[]",
  29.                     "image":"http://itvsuite2.icareus.com/image/image_gallery?img_id=123",
  30.                 }
  31.             ]
  32.         }
  33.     ]

GET ASSETS

This return all assets from the user. This is almost the same as the getAssets with Publishing API, but this will include hidden groups in groupItems and groupItemIds lists. Will also always return both published and unpublished assets.

REQUEST

Method: GET
Parameters:
Name
Value
Requirement
Info
organizationId
number
Mandatory
Icareus Suite organization identifier
token
string
Mandatory
Secret key of the organization
action
"getAssets"
Mandatory

series
boolean
Optional
Asset will have series it belong in the result
podcasts
boolean
Optional
Asset will have podcasts groups it belongs in the result
groupItemId
string
Optional
List of group ID's separated by comma.
Special: If you set this to "nogroups" this will fetch all the assets that doesn't belong to any of the groups.
languageId
string
Optional
fi_FI,en_US, en_UK ...

RESPONSE

Same as in Publishing API's getAssets.

GET SUBTITLE ASSET

Path: /api/archive
Request
Method: GET/POST
Parameters:

Name
Value
Requirement
Info
action
getSubtitle
Mandatory

organizationId
number
Mandatory
Icareus Suite organization id
token
string
Mandatory
Secret key of the organization
userId
number
Mandatory
Icareus Suite user id. User must belong to Organization (with the exception of system admins)
subtitleId
number
Mandatory
Id of the Subtitle Asset to get

Response

Please note that the API will always return HTTP Status 200. See the "status" key of the response JSON to see whether the call was successful or not.

Success

A successful response will contain status ok and the newly created/updated subtitle object.
  1. {
  2.     "status": "ok",
  3.     "subtitle": {
  4.         "fileId": 4368904,
  5.         "id": 4368901,
  6.         "title": "Subtitle test 4",
  7.         "linkedAssetIds": "",
  8.         "description": "fourth subtitle test",
  9.         "languageId": "en_US",
  10.         "fileUrl": "https://suiterc.icareus.com/s3files/10154/2631617/505101.vtt/1.0.vtt"
  11.     }
  12. }

Error

Error response will contain status error and a message+errorCode
  1. {
  2.     "message": "Invalid organizationId",
  3.     "status": "error",
  4.     "errorCode": 14
  5. }

GET SUBTITLE ASSETS

Fetch all / multiple subtitle assets for the specified Organization.
Path: /api/archive
Request
Method: GET/POST
Parameters:
Response
Please note that the api will always return HTTP Status 200. See the "status" key of the response JSON to see whether the call was successful or not.
Success
A successful response will contain status ok.
Error
Error response will contain status error and a message+errorcode

GET SUBTITLE ASSETS

Fetch all / multiple subtitle assets for the specified Organization.
Path: /api/archive
Request
Method: GET/POST
Parameters:

Name
Value
Requirement
Info
action
getSubtitles
Mandatory

organizationId
number
Mandatory
Icareus Suite organization id
token
string
Mandatory
Secret key of the organization
userId
number
Mandatory
Icareus Suite user id. User must belong to organization.
start
number
Optional
Starting index for getting subtitle assets.
end
number
Optional
Ending index for getting subtitles. I.e. start=0&end=2 will fetch the first two subtitles.

Response

Please note that the api will always return HTTP Status 200. See the "status" key of the response JSON to see whether the call was successful or not.

Success

A successful response will contain status ok.
  1. {
  2.     "subtitles": [
  3.         {
  4.             "fileId": 4368704,
  5.             "id": 4368701,
  6.             "title": "Subtitle test",
  7.             "linkedAssetIds": "",
  8.             "description": "this is just a test",
  9.             "languageId": "en_US",
  10.             "fileUrl": "https://suiterc.icareus.com/s3files/10154/2631617/504901.vtt/1.0.vtt"
  11.         },
  12.         {
  13.             "fileId": 4368804,
  14.             "id": 4368801,
  15.             "title": "Subtitle test 2",
  16.             "linkedAssetIds": "",
  17.             "description": "this is just another test",
  18.             "languageId": "en_US",
  19.             "fileUrl": "https://suiterc.icareus.com/s3files/10154/2631617/505001.vtt/1.0.vtt"
  20.         }
  21.     ],
  22.     "status": "ok"
  23. }

Error

Error response will contain status error and a message+errorcode
  1. {
  2.     "message": "Invalid organizationId",
  3.     "status": "error",
  4.     "errorCode": 14
  5. }


ADD / UPDATE SUBTITLE ASSET

Adds (or updates if the id of an existing subtitle asset is provided) a new subtitle asset for the specified Organization. Subtitle file needs to be added with a separate call after the initial asset creation.
Path: /api/archive
Request
Method: GET/POST
Parameters:

Name
Value
Requirement
Info
action
saveSubtitle
Mandatory

organizationId
number
Mandatory
Icareus Suite Organization id
token
string
Mandatory
Secret key of the organization
userId
number
Mandatory
Icareus Suite User id. User must belong to Organization.
title
string
Mandatory if creating new subtitle
Title of the subtitle asset. Only mandatory if creating a new subtitle. Otherwise optional.
description
string
Optional
Description of the subtitle asset.
assetId
number
Optional
Suite video asset id. If provided, the subtitle asset will be linked to this asset.
subtitleId
number
Optional
If provided, the call will update the existing subtitle asset instead of creating a new one.

Response

Please note that the api will always return HTTP Status 200. See the "status" key of the response JSON to see whether the call was successful or not.

Success

A successful response will contain status ok.
  1. {
  2.     "status": "ok",
  3.     "subtitle": {
  4.         "fileId": 4368904,
  5.         "id": 4368901,
  6.         "title": "Subtitle test 4",
  7.         "linkedAssetIds": "",
  8.         "description": "fourth subtitle test",
  9.         "languageId": "en_US",
  10.         "fileUrl": "https://suiterc.icareus.com/s3files/10154/2631617/505101.vtt/1.0.vtt"
  11.     }
  12. }

Error

Error response will contain status error and a message+errorcode
  1. {
  2.     "message": "Invalid organizationId",
  3.     "status": "error",
  4.     "errorCode": 14
  5. }

Links a subtitle asset to a video asset.
Path: /api/archive
Request
Method: GET/POST
Parameters:

Name
Value
Requirement
Info
action
linkSubtitle
Mandatory

organizationId
number
Mandatory
Icareus Suite Organization id
token
string
Mandatory
Secret key of the Organization
userId
number
Mandatory
Icareus Suite userId. User must be part of the Organization.
subtitleId
number
Mandatory
Id of the subtitle asset
assetId
number
Mandatory
Id of the video asset

Response

Please note that the api will always return HTTP Status 200. See the "status" key of the response JSON to see whether the call was successful or not.

Success

A successful response will contain status ok.
  1. {
  2.     "status": "ok",
  3.    "message": "linking successful",
  4.     "subtitle": {
  5.         "fileId": 4368904,
  6.         "id": 4368901,
  7.         "title": "Subtitle test 4",
  8.         "linkedAssetIds": "12345",
  9.         "description": "fourth subtitle test",
  10.         "languageId": "en_US",
  11.         "fileUrl": "https://suiterc.icareus.com/s3files/10154/2631617/505101.vtt/1.0.vtt"
  12.     }
  13. }

Error

Error response will contain status error and a message+errorcode
  1. {
  2.     "message": "Invalid organizationId",
  3.     "status": "error",
  4.     "errorCode": 14
  5. }

Removes the link between a subtitle asset and a video asset.
Path: /api/archive
Request
Method: GET/POST
Parameters:

Name
Value
Requirement
Info
action
unlinkSubtitle
Mandatory

organizationId
number
Mandatory
Icareus Suite Organization id
token
string
Mandatory
Secret key of the Organization
userId
number
Mandatory
Icareus Suite userId. User must be part of Organization.
subtitleId
number
Mandatory
Id of the subtitle asset
assetId
number
Mandatory
Id of the video asset

Response

Please note that the api will always return HTTP Status 200. See the "status" key of the response JSON to see whether the call was successful or not.

Success

A successful response will contain status ok.
  1. {
  2.     "status": "ok",
  3.    "message": "linking successful",
  4.     "subtitle": {
  5.         "fileId": 4368904,
  6.         "id": 4368901,
  7.         "title": "Subtitle test 4",
  8.         "linkedAssetIds": "12345",
  9.         "description": "fourth subtitle test",
  10.         "languageId": "en_US",
  11.         "fileUrl": "https://suiterc.icareus.com/s3files/10154/2631617/505101.vtt/1.0.vtt"
  12.     }
  13. }

Error

Error response will contain status error and a message+errorcode
  1. {
  2.     "message": "Invalid organizationId",
  3.     "status": "error",
  4.     "errorCode": 14
  5. }

Add subtitle file to a subtitle asset

Adds a subtitle (.vtt) file to a subtitle asset.
Path: /api/archive
Method: POST
This should be a multipart request! (Content-Type: multipart/form-data)

Name
Value
Requirement
Info
action
addSubtitleFile
Mandatory

organizationId
number
Mandatory
Icareus Suite Organization ID
token
string
Mandatory
Secret key of the Organization
userId
number
Mandatory
Icareus Suite user id. User must be part of the Organization.
subtitleId
number
Mandatory
Icareus Suite subtitle asset ID.
The .vtt file should be provided as form-data with the field name subtitleFile

Response

Please note that the api will always return HTTP status 200. See the "status" key of the response JSON to see whether the call was successful or not.

Success

A successful response will contain status ok.
  1. {
  2.     "status": "ok",
  3.     "subtitle": {
  4.         "fileId": 4368904,
  5.         "id": 4368901,
  6.         "title": "Subtitle test 4",
  7.         "linkedAssetIds": "12345",
  8.         "description": "fourth subtitle test",
  9.         "languageId": "en_US",
  10.         "fileUrl": "https://suiterc.icareus.com/s3files/10154/2631617/505101.vtt/1.0.vtt"
  11.     }
  12. }

Error

Error response will contain status error and a message+errorcode
  1. {
  2.     "message": "Invalid organizationId",
  3.     "status": "error",
  4.     "errorCode": 14
  5. }

Delete Subtitle Asset

Deletes an individual subtitle asset by it's ID.
Path: /api/archive
Method: GET or POST

Parameters


Name
Value
Requirement
Info
action
deleteSubtitle
Mandatory

organizationId
number
Mandatory
Icareus Suite Organization ID
token
string
Mandatory
Secret key of the organization
userId
number
Mandatory
Icareus Suite user id. User must belong to organization.
subtitleId
number
Mandatory
Icareus Suite subtitle asset ID. (the subtitle asset to delete)

Response

Please note that the api will always return HTTP status 200. See the "status" key of the response JSON to see whether the call was successful or not.

Success

  1. {
  2.     "status": "ok",
  3. }

Error

Error response will contain status error and a message+errorcode
  1. {
  2.     "message": "Invalid organizationId",
  3.     "status": "error",
  4.     "errorCode": 14
  5. }

Update Asset Thumbnail Image

This action allows you to upload a thumbnail image to an asset.

Path

/api/archive

Request

Method: POST
Parameters:

Name
Value
Requirement
Description
action
updateAssetThumbnail
Mandatory

organizationId
Number
Mandatory
Icareus Suite Organization ID
token
String
Mandatory
Secret key of the Organization.
assetId
Number
Mandatory
ID of the asset you wish to add image files for.
userId
Number
Mandatory
Icareus Suite User ID.

Form Data

In order to upload image and add them to the asset, the image file needs to be included in the request form-data.

assetImage: This image file will be set as the thumbnail image of the asset.

Example

  1. curl --location -XPOST 'https://suiterc.icareus.com/api/archive?action=updateAssetThumbnail&organizationId=<ORGANIZATION-ID>&assetId=<ASSET-ID>&userId=<USER-ID>&token=<ORGANIZATION-SECRET>' \
  2. -H 'Content-Type: multipart/form-data' \
  3. -F 'assetImage=@"/path/to/image/thumbnail.jpg"'

Response

The response will always have the HTTP Status Code 200 (except in some cases where there is an internal server error, in these cases the status code can be 50x).

Successful response will contain "status": "ok" along with an "asset": {} object containing all the asset data (including updated image).

Unsuccessful response will contain "status": "error".

Update Asset Cover Image

This action allows you to upload a cover image to an asset.

Path

/api/archive

Request

Method: POST
Parameters:

Name
Value
Requirement
Description
action
updateAssetCover
Mandatory

organizationId
Number
Mandatory
Icareus Suite Organization ID
token
String
Mandatory
Secret key of the Organization.
assetId
Number
Mandatory
ID of the asset you wish to add image files for.
userId
Number
Mandatory
Icareus Suite User ID.

Form Data

In order to upload image and add them to the asset, the image file needs to be included in the request form-data.

assetImage: This image file will be set as the cover image of the asset.

Example

  1. curl --location -XPOST 'https://suiterc.icareus.com/api/archive?action=updateAssetCover&organizationId=<ORGANIZATION-ID>&assetId=<ASSET-ID>&userId=<USER-ID>&token=<ORGANIZATION-SECRET>' \
  2. -H 'Content-Type: multipart/form-data' \
  3. -F 'assetImage=@"/path/to/image/thumbnail.jpg"'

Response

The response will always have the HTTP Status Code 200 (except in some cases where there is an internal server error, in these cases the status code can be 50x).

Successful response will contain "status": "ok" along with an "asset": {} object containing all the asset data (including updated image).

Unsuccessful response will contain "status": "error".

Update Asset Banner Image

This action allows you to upload a banner image to an asset.

Path

/api/archive

Request

Method: POST
Parameters:

Name
Value
Requirement
Description
action
updateAssetBanner
Mandatory

organizationId
Number
Mandatory
Icareus Suite Organization ID
token
String
Mandatory
Secret key of the Organization.
assetId
Number
Mandatory
ID of the asset you wish to add image files for.
userId
Number
Mandatory
Icareus Suite User ID.

Form Data

In order to upload image and add them to the asset, the image file needs to be included in the request form-data.

assetImage: This image file will be set as the banner image of the asset.

Example

  1. curl --location -XPOST 'https://suiterc.icareus.com/api/archive?action=updateAssetBanner&organizationId=<ORGANIZATION-ID>&assetId=<ASSET-ID>&userId=<USER-ID>&token=<ORGANIZATION-SECRET>' \
  2. -H 'Content-Type: multipart/form-data' \
  3. -F 'assetImage=@"/path/to/image/thumbnail.jpg"'

Response

The response will always have the HTTP Status Code 200 (except in some cases where there is an internal server error, in these cases the status code can be 50x).

Successful response will contain "status": "ok" along with an "asset": {} object containing all the asset data (including updated image).

Unsuccessful response will contain "status": "error".






    

    • Related Articles
      • 

    • Arkisto (Archive) API (FI)
      JOHDANTO Tätä API-rajapintaa käytetään arkiston sisällön hallintaan, kuten sisällön lisäämiseen, sisällön muokkaamiseen ja sisällön poistamiseen. Kaikki kutsut on tehtävä antamalla organisaatiosi yksilöllinen tunnus. API POLKU (PATH) /api/archive 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 ...
      • 

    • OEMBED API (ENG)
      INTRODUCTION This API is used to query for oEmbed objects for video page URL(s) on Icareus Suite sites. Note Suite oEmbed API only supports JSON responses for now API PATH /api/oembed API GET OEMBED OBJECT REQUEST /api/oembed Parameters: Name Value ...
      • 

    • Devices API (ENG)
      INTRODUCTION Devices API is used to register devices to the server and get device specific information/configurations from the server. API PATH /api/devices It is recommended to use POST request. Latest version: 02 API METHODS REGISTER A DEVICE ...
      • 

    • 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 ...
      •