Manuals

UserMedia API Manual

Icecat users have the ability to upload media assets to Icecat endpoints using the UserMedia feature. This manual provides instructions on uploading videos via the UserMedia API and presenting them via Icecat LIVE.

Swagger schema: https://api.icecat.biz/#/UserMedia

1. Initial Setup

All requests are sent to https://bo.icecat.biz/restful/v3/ and SessionType is always Rest.While it is possible to reach API with your programming language or terminal tools like curl and wGet, I would recommend using tools like Insomnia or Postman to work with our data as the requests can be complicated.

2. Authorization

You need to have either a brand or shop type account to use UserMedia API. To initiate data transmission, you must authenticate yourself with the API by obtaining a session key. This session key is required for subsequent requests to ensure proper API authentication. Please, follow point 1.3 from the PUSH API manual.

3. UserMedia API Endpoints

3.1. POST – Add UserMedia Video

Path:

https://bo.icecat.biz/restful/v3/UserMedia/Videos?AccessKey={{_.accessKey}}&SessionType=Rest

Headers:

Content-Type: multipart/form-data

Multipart data:

'Title=My Title'
'LanguageIds=10,1,2'
SourceLink=http://example.com/FunnyElephant.mp4
ProviderUserId=99999

Example:

curl --request POST \
  --url 'https://bo.icecat.biz/restful/v3/UserMedia/Videos?AccessKey={{_.accessKey}}&SessionType=Rest' \
  --header 'Content-Type: multipart/form-data' \
  --header 'accept: application/json' \
  --form 'Title=My Title' \
  --form 'LanguageIds=10,1,2' \
  --form SourceLink=http://example.com/FunnyElephant.mp4 \
  --form ProviderUserId=99999

Variables:

_.accessKey Access key
TitleVideo title
LanguageIdsIDs for your languages. Comma-separated. Refer here: Locales & Language Code Table
SourceLinkLink to your video. Allowed formats: 3gp, avi, flv, m4v, mkv, mov, mp4, mpg, ogg, vob, wmv, webm.
ProviderUserIdID of your Icecat account, contact support@icecat.biz to get yours.

Success response 201:

{
    "Data": {
     "VideoId": 33232080
    }
}

3.2. GET – Receive Video Data by VideoId

Path:

https://bo.icecat.biz/restful/v3/UserMedia/Videos/{{_.videoID}}?AccessKey={{_.accessKey}}&SessionType=Rest

Example:

curl --request GET \
  --url 'https://bo.icecat.biz/restful/v3/UserMedia/Videos/{{_.videoID}}?AccessKey={{_.accessKey}}&SessionType=Rest' \

Variables:

_.accessKeyUser access key
_.videoIdVideo ID, received in p. 3.1.

Success response 200:

{
  "Data": {
 "VideoId": 99999,
 "Title": "My Title",
 "Link": "https://example.icecat.biz//",
 "LanguageIds": [
   2,
   3,
   10
 ],
 "ProviderUserId": 303033,
 "Status": "Done",
 "PreviewImageLink": "https://example.icecat.biz//",
 "PreviewImageLinkTmp": "https://example.icecat.biz//",
 "PreviewThumbLink": "https://example.icecat.biz//",
 "PreviewThumbLinkTmp": "https://example.icecat.biz//",
 "Accesses": [],
 "AgeRatings": []
  }
}

Response is constructed from links to your UserMedia on Icecat servers and additional data.

VideoIdVideo ID
TitleVideo title
LinkLink to the video
LanguageIdsIDs for your languages. Comma-separated. Refer here: Locales & Language Code Table
ProviderUserIdVideo owner’s ID
StatusVideo upload status
PreviewImageLinkLink to video image preview
PreviewImageLinkTmpTemporary link to video image preview
PreviewThumbLinkLink to video image preview in thumbnail format
PreviewThumbLinkTmpTemporary link to video image preview in thumbnail format
AccessesUsers are allowed to update your video
AgeRatingsAge Ratings activated for your videos

3.3. PATCH – Update Title for Video by ID

Path:

https://bo.icecat.biz/restful/v3/UserMedia/Videos/{{_.videoID}}?AccessKey={{_.accessKey}}&Sess
ionType=Rest

Body:

{
    "Title": "My new Title"
}

Example:

curl --request PATCH \
  --url 'https://bo.icecat.biz/restful/v3/UserMedia/Videos/{{_.videoID}}?AccessKey={{_.accessKey}}&SessionType=Rest' \
  --header 'Content-Type: application/json' \
  --data '{
 "Title": "My new title"
}'

Variables:

_.accessKeyUser access key
_.videoIdVideo ID, received in p. 3.1.

Success response 200:

{
    "Data": {}
}

3.4. DELETE – Delete Video By ID

Path:

https://bo.icecat.biz/restful/v3/UserMedia/Videos/{{_.videoID}}?AccessKey={{_.accessKey}}&SessionType=Rest

Example:

curl --request DELETE \
  --url 'https://bo.icecat.biz/restful/v3/UserMedia/Videos/{{_.videoID}}?AccessKey={{_.accessKey}}&SessionType=Rest'

Variables:

_.accessKeyUser access key
_.videoIdVideo ID, received in p. 3.1.

Success response 200: Returns an ID of the deleted Video.

{
    "Data": {
     "VideoId": 332079
    }
}

3.5. GET – Receive all UserMedia Videos

Path:

https://bo.icecat.biz/restful/v3/UserMedia/Videos?AccessKey={{_.accessKey}}&SessionType=Rest

Example:

curl --request GET \
  --url 'https://bo.icecat.biz/restful/v3/UserMedia/Videos?AccessKey={{_.accessKey}}&SessionType=Rest' \

Variables:

_.accessKeyUser access key

Success response 200: Method returns all Videos stored on Icecat.

4. Languages

Please check the IDs for Icecat Languages here: Locales & Language Code

4.1. POST – Add language to Video

Path:

https://bo.icecat.biz/restful/v3/UserMedia/Videos/{{_.videoID}}/Languages?AccessKey={{_.accessKey}}&SessionType=Rest

Example:

curl --request POST \
  --url 'https://bo.icecat.biz/restful/v3/UserMedia/Videos/{{_.videoID}}/Languages?AccessKey={{_.accessKey}}&SessionType=Rest' \
  --data '{
  "LanguageId": 3
}'

Body:

{
  "LanguageId": 3
}

Variables:

_.accessKeyUser access key
_.videoIdVideo ID, received in p. 3.1.
LanguageIdIDs of the languages for your video. Locales & Language Code

Success response 200: Returns ID of activated languages.

{
    "Data": {
     "LanguageId": 3
    }
}

4.2. GET – Receive Video Data with Language by ID

Path:

https://bo.icecat.biz/restful/v3/UserMedia/Videos/{{_.videoID}}?AccessKey={{_.accessKey}}&SessionType=Rest&Metadata%5B%5D=Languages

Example:

curl --request GET \
  --url 'https://bo.icecat.biz/restful/v3/UserMedia/Videos/{{_.videoID}}?AccessKey={{_.accessKey}}&SessionType=Rest&Metadata%5B%5D=Languages' \

Variables:

_.accessKeyUser access key
_.videoIdVideo ID, received in p. 3.1.
Metadata[]Metadata you want to receive. Can be Languages or Age Ratings.

Success response 200:

{
    "Data": {
     "VideoId": 0,
     "Title": "",
     "Link": "",
     "LanguageIds": [
      2,
      3,
      10
     ],
     "ProviderUserId": 0,
     "Status": "Done",
     "PreviewImageLink": "",
     "PreviewImageLinkTmp": "",
     "PreviewThumbLink": "",
     "PreviewThumbLinkTmp": "",
     "Accesses": [],
     "AgeRatings": []
    },
    "Metadata": {
     "Languages": [
      {
       "LanguageId": 2,
       "ShortCode": "NL"
      },
      {
       "LanguageId": 3,
       "ShortCode": "FR"
      },
      {
       "LanguageId": 10,
       "ShortCode": "BR"
      }
     ]
    }
}

4.3. DELETE – Remove Language from Video

Path:

https://bo.icecat.biz/restful/v3/UserMedia/Videos/{{_.videoID}}/Languages/{{ _.languageID }}?AccessKey={{_.accessKey}}&SessionType=Rest

Example:

curl --request DELETE \
  --url 'https://bo.icecat.biz/restful/v3/UserMedia/Videos/{{_.videoID}}/Languages/{{ _.languageID }}?AccessKey={{_.accessKey}}&SessionType=Rest' \

Variables:

_.accessKeyUser access key
_.videoIdVideoID, received in p. 3.1.
LanguageIdIDs of the languages for your video. Locales & Language Code

Success response 200:

{
    "Data": {}
}

5. Accesses

With accesses you can assign users to edit your UserMedia. You can only allow shop users to get access to your videos.

5.1. POST – Add an access for Video

Path:

https://bo.icecat.biz/restful/v3/UserMedia/Videos/{{_.videoID}}/Accesses?AccessKey={{ _.accessKey }}&SessionType=Rest

Body:

{
  "AuthorizedUserId": {{_.userID}},
  "UserReference": "My-team-lead"
}

Example:

curl --request POST \
  --url 'https://bo.icecat.biz/restful/v3/UserMedia/Videos/332080/Accesses?AccessKey={{ _.accessKey }}&SessionType=Rest' \
  --data '{
  "AuthorizedUserId": {{_.userID}},
  "UserReference": "My-team-lead"
}'

Variables:

_.accessKeyUser access key
_.videoIdVideo ID, received in p. 3.1.
_.userIDID of a shop user you would like to grant access to. Please contact support@icecat.biz.
UserReferenceShort description for your access. Please do not use white-spaces.

Success response 201:

{
    "Data": {
     "AccessId": 0,
     "AuthorizedUserId": 0,
     "UserReference": "My-team-lead"
    }
}

5.2. PATCH – Update UserReference by AccessId

Path:

https://bo.icecat.biz/restful/v3/UserMedia/Videos/{{_.videoID}}/Accesses/{{_.accessId}}?AccessKey={{ _.accessKey }}&SessionType=Rest

Body:

{
    "UserReference": "My-ex-team-lead"
}

Example:

curl --request PATCH \
  --url 'https://bo.icecat.biz/restful/v3/UserMedia/Videos/{{_.videoID}}/Accesses/{{ _.accessId }}?AccessKey={{ _.accessKey }}&SessionType=Rest' \
 --data '{
 "UserReference": "My-ex-team-lead"
}'

Variables:

_.accessKeyUser access key
_.videoIdVideo ID, received in p. 3.1.
_.accessIdAccess ID, received in p. 5.1.
UserReferenceShort description for your access. Please do not use white-spaces.

Success response 200:

{
    "Data": {
     "AccessId": 9060198,
     "AuthorizedUserId": 110865,
     "UserReference": "My-ex-team-lead"
    }
}

5.3. DELETE – Remove Access by AccessId

Path:

https://bo.icecat.biz/restful/v3/UserMedia/Videos/{{_.videoID}}/Accesses/{{_.accessId}}?AccessKey={{ _.accessKey }}&SessionType=Rest

Example:

curl --request DELETE \
  --url 'https://bo.icecat.biz/restful/v3/UserMedia/Videos/{{_.videoID}}/Accesses/{{_.accessId}}?AccessKey={{ _.accessKey }}&SessionType=Rest' \

Variables:

_.accessKeyUser access key
_.videoIdVideo ID, received in p. 3.1.
_.accessIdAccess ID, received in p. 5.1.

Success response 200:

{
    "Data": {}
}

6. Age Ratings

Age Ratings are additional labels to mark which audience the video is available for. They display minimum age requirements for the content.

6.1. GET – Receive Age Ratings Dictionary

Path:

https://bo.icecat.biz/restful/v3/UserMedia/Videos/{{_.videoID}}?AccessKey={{_.accessKey}}&SessionType=Rest&Metadata%5B%5D=AgeRatings

Example:

curl --request GET \
  --url 'https://bo.icecat.biz/restful/v3/UserMedia/Videos/{{_.videoID}}?AccessKey={{_.accessKey}}&SessionType=Rest&Metadata%5B%5D=AgeRatings'

Variables:

_.accessKeyUser access key
_.videoIdVideo ID, received in p. 3.1.
Metadata[]Metadata you want to receive. Can be Languages or Age Ratings.

Response returns all information about each Age Rating provider.

AgeRatingIdID of the Age Rating provider.
AgeRatingAge Rating provider name.
AgeRatingValuesEach provider has its own system of ratings and this array contains all possible values.
AgeRatingDescriptorsDescription of content that appears in video which can affect Age Rating.

6.2. POST – Add Age Rating to Video by ID

Path:

https://bo.icecat.biz/restful/v3/UserMedia/Videos/{{ _.videoID }}/AgeRatings?AccessKey={{_.accessKey}}&SessionType=Rest

Body:

{
  "AgeRatingId": 1,
  "AgeRatingValueId": 2,
  "AgeRatingDescriptorIds": [
 2
  ]
}

Example:

curl --request POST \
  --url 'https://bo.icecat.biz/restful/v3/UserMedia/Videos/{{ _.videoID }}/AgeRatings?AccessKey={{_.accessKey}}&SessionType=Rest' \
  --header 'Content-Type: application/json' \
  --data ' {
  "AgeRatingId": 1,
  "AgeRatingValueId": 2,
  "AgeRatingDescriptorIds": [
    2
  ]
}'

Variables:

_.accessKeyUser access key
_.videoIdVideo ID, received in p. 3.1.
AgeRatingId, AgeRatingValueId, AgeRatingDescriptorIdsRefer to Age Ratings Dictionary, received in p.6.1.

Success response 201:

{
    "Data": {
     "AgeRatingId": 1
    }
}

6.3. PATCH – Update AgeRatingValue by AgeRatingId

Path:

https://bo.icecat.biz/restful/v3/UserMedia/Videos/{{ _.videoID }}/AgeRatings/{{ _.ageRatingId }}?AccessKey={{_.accessKey}}&SessionType=Rest

Body:

{
  "AgeRatingValueId": 3
}

Example:

curl --request PATCH \
  --url 'https://bo.icecat.biz/restful/v3/UserMedia/Videos/{{ _.videoID }}/AgeRatings/{{ _.ageRatingId }}?AccessKey={{_.accessKey}}&SessionType=Rest' \
  --header 'Content-Type: application/json' \
  --data '{
  "AgeRatingValueId": 3
}'

Variables:

_.accessKeyUser access key
_.videoIdVideo ID, received in p. 3.1.
_.ageRatingId, AgeRatingValueIdRefer to Age Ratings Dictionary, received in p.6.1.

Success response:

{
    "Data": {}
}

6.4. DELETE – Remove Age Rating from video by ID

Path: 

https://bo.icecat.biz/restful/v3/UserMedia/Videos/{{ _.videoID }}/AgeRatings/{{ _.ageRatingId }}?AccessKey={{_.accessKey}}&SessionType=Rest

Example:

curl --request DELETE \
  --url 'https://bo.icecat.biz/restful/v3/UserMedia/Videos/{{ _.videoID }}/AgeRatings/{{ _.ageRatingId }}?AccessKey={{_.accessKey}}&SessionType=Rest' \

Variables:

_.accessKeyUser access key
_.videoIdVideo ID, received in p. 3.1.
_.ageRatingIdRefer to Age Ratings Dictionary, received in p.6.1.

Success response 200:

{
    "Data": {}
}

7. Age Ratings Descriptors

AgeRatingDescriptor is a label that shows additional information about provocative content that is not suited for minors. For example, “Drugs” or “Sex” are the descriptors in PEGI rating.

7.1. POST – Add Age Rating Descriptor to Video

Path:

https://bo.icecat.biz/restful/v3/UserMedia/Videos/{{ _.videoID }}/AgeRatings/{{ _.ageRatingID }}/Descriptors?AccessKey={{_.accessKey}}&SessionType=Rest

Body:

{
  "AgeRatingDescriptorId": 7
}

Example:

curl --request POST \
  --url 'https://bo.icecat.biz/restful/v3/UserMedia/Videos/{{ _.videoID }}/AgeRatings/{{ _.ageRatingID }}/Descriptors?AccessKey={{_.accessKey}}&SessionType=Rest' \
  --data '{
  "AgeRatingDescriptorId": 7
}'

Variables:

_.accessKeyUser access key
_.videoIdVideo ID, received in p. 3.1.
_.ageRatingId, AgeRatingDescriptorIdRefer to Age Ratings Dictionary, received in p.6.1.

Success response 201:

{
    "Data": {
     "AgeRatingDescriptorId": 7
    }
}

7.2. DELETE – Remove Age Descriptor from Video

Path:

https://bo.icecat.biz/restful/v3/UserMedia/Videos/{{ _.videoID }}/AgeRatings/{{ _.ageRatingID }}/Descriptors/{{ _.ageRatingDescriptorID }}?AccessKey={{_.accessKey}}&SessionType=Rest

Example:

curl --request DELETE \
  --url 'https://bo.icecat.biz/restful/v3/UserMedia/Videos/{{ _.videoID }}/AgeRatings/{{ _.ageRatingID }}/Descriptors/{{ _.ageRatingDescriptorID }}?AccessKey={{_.accessKey}}&SessionType=Rest' \

Variables:

_.accessKeyUser access key
_.videoIdVideo ID, received in p. 3.1.
_.ageRatingId, _.ageRatingDescriptorIDRefer to Age Ratings Dictionary, received in p.6.1.

Success response 200:

{
    "Data": {}
}

8. Errors

Error codeError messageResolution
400Some of the parameters are not valid or were not inputted. See returned message for detailsCheck your input method.
400HTTP method GET is not described in the swagger schema.Change HTTP method to HTTPS.
401Your AccessKey is not valid any moreRenew your AccessKey with Session/ endpoint.
403You are not assigned to this content!Check the Video accesses with UserMedia/Videos/{{_.videoID}} endpoint.
500This should never happen!Report such cases to support@icecat.biz

9. UserMedia API with Icecat LIVE JS AP

To retrieve videos uploaded through the UserMedia API using Icecat LIVE JS API, you will need to include two essential parameters in your request code:

UserReferenceUser references code. This is a user identifier that helps to search loaded video into the Icecat system.
ProviderIdUser identifier of the owner of an uploaded video in Icecat system (the same as ProviderUserId).

These two parameters are required for showing the user’s videos into live html.

Age gating is activated by default, however it is possible to disable it by adding videoAgeGatingDisabled: true parameter. Please see an example below.

9.1. Granular call + UserMedia

Videos uploaded via UserMedia API can be requested via Granular call to be included among other containers. For this you need to include a ‘videos’ container to the call, UserReference and ProviderId are also required. The request works with any identifier combinations, Smart call and Multilingual request. Please refer to the Granular Call manual for more info.

Granular call with UserMedia API parameters – Brand + MPN:

<!DOCTYPE html>
<html>
  <head></head>
  <body>
    <div id="сontainer1"></div>
    <div id="сontainer2"></div>
    <script>
      window.addEventListener('liveload', function () {
        IcecatLive.getDatasheet(
          {
            gallery: '#сontainer1',
            videos: '#сontainer2',
          },
          {
            Brand: 'Philips',
            PartCode: 'DS8900/10',
            UserName: 'shop_user',
            UserReference: 'user_code',
            ProviderId: 1,
          },
          'en'
        );
      });
    </script>
    <script src="https://live.icecat.biz/js/live-current-2.js" async></script>
  </body>
</html>

The same request with Age gating disabled:

<!DOCTYPE html>
<html>
  <head></head>
  <body>
    <div id="сontainer1"></div>
    <div id="сontainer2"></div>
    <script>
      window.addEventListener('liveload', function () {
        IcecatLive.getDatasheet(
          {
            gallery: '#сontainer1',
            videos: '#сontainer2',
          },
          {
            Brand: 'Philips',
            PartCode: 'DS8900/10',
            UserName: 'shop_user',
            UserReference: 'user_code',
            ProviderId: 1,
  videoAgeGatingDisabled: true,
          },
          'en'
        );
      });
    </script>
    <script src="https://live.icecat.biz/js/live-current-2.js" async></script>
  </body>
</html>

9.2. Icecat Live API for Granular call of UserMedia API with only media assets

Users can request videos uploaded via UserMedia API exclusively without requesting any specific product or data containers using Icecat Live. ProviderId and UserReference parameters are required.

<!DOCTYPE html>
<html>

<head></head>

<body>
  <div id="сontainer"></div>
  <script>
 window.addEventListener('liveload', function () {
   IcecatLive.getUnlinkedVideos(
     '#сontainer',
     {
       shopname: 'shop_user',
       UserReference: 'user_code',
       ProviderId: 1,
     },
     'en'
   );
 });
  </script>
  <script src="https://live.icecat.biz/js/live-current-2.js" async></script>
</body>

</html>

9.3. Icecat Live API for Regular call of UserMedia API

The Regular call of datasheet + UserMedia API parameters – Brand + MPN (can also be used with Icecat ID based, EAN-based calls, and Smart call):

<!DOCTYPE html>
<html>
  <head></head>
  <body>
    <div id="container"></div>
    <script>
      window.addEventListener('liveload', function () {
        window.IcecatLive.getDatasheet(
          '#container',
          {
            Brand: 'Philips',
            PartCode: 'DS8900/10',
            UserName: 'shop_user',
            UserReference: 'user_code',
            ProviderId: 1,
          },
          'en'
        );
      });
    </script>
    <script src="https://live.icecat.biz/js/live-current-2.js" async></script>
  </body>
</html>

Read further: Manuals, , , ,

Icecat is a global leader in product content syndication, helping brands, manufacturers, distributors, and retailers deliver enriched and consistent product information across multiple platforms. Trusted by 40,000+ e-commerce brands, Icecat helps turn browsers into buyers.

icecat

Icecat is a global leader in product content syndication, helping brands, manufacturers, distributors, and retailers deliver enriched and consistent product information across multiple platforms. Trusted by 40,000+ e-commerce brands, Icecat helps turn browsers into buyers.

Share
Published by
icecat
Tags: IcecatmanualPIMproduct content
2 years ago

Recent Posts

Icecat Release Notes 246: Expanding Content Value, Data Freshness, and Platform Efficiency

In this release, we focused on strengthening Icecat’s core value pillars: richer content experiences, more…

8 hours ago

MAXHUB Joins Icecat to Strengthen Product Data Distribution in the ProAV Channel

MAXHUB, a global provider of collaborative display and communication solutions, has joined the Icecat ecosystem…

1 day ago

Meta’s Latest Layoffs Raise a Bigger Question: Is AI Replacing Jobs, or Reshaping Them?

Another wave of layoffs at Meta Platforms is making headlines. But beyond the numbers, the…

5 days ago

Icecat Hexagon Release Notes – March 2026

Icecat Hexagon is Icecat’s internal platform for connecting retailers, Akeneo users, and marketplaces like Mirakl.…

7 days ago

Wakuli’s 2025 Progress Report Shows What a Different Coffee Industry Can Look Like

Today, Wakuli publishes its 2025 Progress Report, offering a closer look at how the company…

1 week ago

Advancing EAA Compliance Across Icecat Core and Icecat Studio

The European Accessibility Act (EAA) establishes new requirements to ensure that digital products and services…

1 week ago