NAV Navbar
shell
  • Getting started
  • Authentication
  • Managing accounts
  • Managing profiles
  • Profile preferences
  • Smart engine
  • Profile development
  • Editorial Lists
  • Main workflow diagrams
  • Additional notes
  • Getting started

    Welcome to CogniK Smart Engine API documentation.

    Our API's objective is to improve your users experience while they are exploring your catalog. By using our recommendation engine, it helps you find out which contents best match your users profiles. This comes with a lot of additional features, to be discovered throughout the documentation.

    To begin with, here are some general information about expected requests format and the response types returned.

    Metadata format

    Our API accepts and produces JSON data. Content-Type and Accept headers must be set accordingly, as described below.

    Header Value
    Content-Type application/json
    Accept application/json

    Request methods

    Every endpoint supports at least one of the four different HTTP verbs:

    Since some devices do not support PUT or DELETE verbs, we have made it easy to fake PUT and DELETE requests using x-http-method-override header.

    Header Value Description
    x-http-method-override PUT Override POST request to PUT
    x-http-method-override DELETE Override POST request to DELETE

    Request headers

    Our API is expecting a x-platform-id header for each request, reading the type of the user's device. Default platform values indicated below can be modified on demand. The header is composed of a mandatory type and an optional detail. They are separated by a slash and can be used to generate accurate analytics (Example: 'mobile/android').

    Header Predefined values
    x-platform-id pc, tablet, mobile, iptv

    Understanding errors

    Example of response to a GET or POST request

    {
      "account_id": "hdjh87kUIokDFkjh90jdh",
      "creation date": 1480978983
    }
    

    Example of response to a PUT or DELETE request

    {
      "response": "Resource has been successfully updated"
    }
    

    Example of response in case of error

    {
      "error": "Authentication issue, please check your APP ID"
    }
    

    Three types of response can be returned, illustrated by examples

    Below are listed the meaning of most common HTTP status codes.

    Code Description Details
    200 Succeed Request has been executed successfully
    400 Bad Request Generic error detailed in response body
    401 Unauthorized Authentication failed or token is missing
    403 Forbidden Access permissions are restrained
    404 Not Found Resource is missing
    405 Method Not Allowed Unexpected method (GET/POST/...) for this request
    406 Not Acceptable Unexpected data format for this request
    409 Conflict Resource already in use
    500 Server Error Something went wrong on our end
    503 Service Unavailable API cannot temporarly be reached

    Authentication

    Our API supports two integration modes:

    Header Value Description
    x-app-token token Access token to CogniK API

    Login

    Logs a user in to our API by providing him with a token for the session. Please note that regular users are granted with a restricted access to resources of their own (account, profiles, etc.).

    curl {base_url}/v1/login/{account_id}
      -X POST 
      -H "Content-Type:application/json" 
      -H "Accept:application/json" 
      -H "x-platform-id:iptv"
      -d '{post_data}' 
    

    HTTP Request

    POST /v1/login/{account_id}

    Parameters description

    Property Type Required Description
    account_id string true account ID

    Example of POST data

    {
      "app_id": "MY_APP_ID",
      "password": "mypassword"
    }
    

    POST data description

    Property Type Required Description
    app_id string true API key
    password string true password used to log in

    Example of HTTP response

    {
      "account_created": true,
    "profile_created": true,
    "account_id": "hdjh87kUIokDFkjh90jdh",
    "token": "0a1z2e3r4t5y6u7i8o" }

    HTTP Response

    Code Description
    200 A temporary access token is returned
    401 Unknown user or wrong password

    Logout

    Logs out the account by revoking the token.

    curl {base_url}/v1/logout
      -X POST 
      -H "x-app-token:0a1z2e3r4t5y6u7i8o" 
      -H "x-platform-id:iptv"
    

    HTTP Request

    POST /v1/logout

    HTTP Response

    Code Description
    200 User has been logged out

    Managing accounts

    Create an account

    An account is created from the data provided in POST data. The account password must be provided in addition to this data.

    curl {base_url}/v1/accounts/{account_id}
      -X POST 
      -H "Content-Type:application/json" 
      -H "Accept:application/json" 
      -H "x-app-token:0a1z2e3r4t5y6u7i8o"
      -H "x-platform-id:iptv"
      -d '{post_data}' 
    

    HTTP Request

    POST /v1/accounts/{account_id}

    Parameters description

    Property Type Required Description
    account_id string true Account ID

    Example of POST data

    {
      "password": "mypassword"
    }
    

    POST data description

    Property Type Required Description
    password string true Account password

    Example of HTTP Response

    {
      "account_id": "hdjh87kUIokDFkjh90jdh",
      "creation date": 1480978983
    }
    

    HTTP Response

    Code Description
    201 Account created
    409 This account is already used

    Get account details

    Provide the account information.

    curl {base_url}/v1/accounts/{account_id}
      -X GET 
      -H "Content-Type:application/json" 
      -H "Accept:application/json" 
      -H "x-app-token:0a1z2e3r4t5y6u7i8o" 
      -H "x-platform-id:iptv"
    

    HTTP Request

    GET /v1/accounts/{account_id}

    Parameters description

    Property Type Required Description
    account_id string true Account ID

    Example of HTTP response

    {
      "account_id": "hdjh87kUIokDFkjh90jdh",
      "creation_date": 1480955412
    }
    

    HTTP Response

    Code Description
    200 Returns account information
    404 Unknown account

    Delete an account

    Delete an account and all associated profiles.

    curl {base_url}/v1/accounts/{account_id}
      -X DELETE
      -H "Content-Type:application/json"
      -H "Accept:application/json"
      -H "x-app-token:0a1z2e3r4t5y6u7i8o"
      -H "x-platform-id:iptv"
    

    HTTP Request

    DELETE /v1/accounts/{account_id}

    Parameters description

    Property Type Required Description
    account_id string true Account ID

    Exemple de réponse HTTP

    {
      "response": "Account hdjh87kUIokDFkjh90jdh and all related profiles have been deleted"
    }
    

    HTTP Response

    Code Description
    200 Account deleted
    404 Unknown account

    Managing profiles

    A limit of one profile per account is set by default, automatically generated at acount creation. Both limit and auto creation settings can be modified on demand.

    Get account profiles

    Get the list of profiles related to a given account.

    curl {base_url}/v1/accounts/{account_id}/profiles
      -X GET
      -H "Content-Type:application/json" 
      -H "Accept:application/json" 
      -H "x-app-token:0a1z2e3r4t5y6u7i8o" 
      -H "x-platform-id:iptv"
    

    HTTP Request

    GET /v1/accounts/{account_id}/profiles

    Parameters description

    Property Type Required Description
    account_id string true Account ID

    Example of HTTP Response

    {
      "size":"2",
      "profiles": [
        {
          "profile_id": "ztnc9g52xvavzuba",
          "account_id": "hdjh87kUIokDFkjh90jdh",
          "creation_date": 1480978983
        },
        {
          "profile_id": "t3k7fgztq6fj2ymt",
          "account_id": "hdjh87kUIokDFkjh90jdh",
          "creation_date": 1480955412
        }
      ]
    }
    

    HTTP Response

    Code Description
    200 Return the list of profiles

    Create a profile

    Create a new profile related to the account. Our API allows you to attach any additional information to the profil which you may find useful, as long as JSON format is valid.

    curl {base_url}/v1/accounts/{account_id}/profiles/{profile_id}
      -X POST 
      -H "Content-Type:application/json" 
      -H "Accept:application/json" 
      -H "x-app-token:0a1z2e3r4t5y6u7i8o" 
      -H "x-platform-id:iptv"
      -d '{post_data}' 
    

    HTTP Request

    POST /v1/accounts/{account_id}/profiles/{profile_id}

    Parameters description

    Property Type Required Description
    account_id string true Account ID
    profile_id string false Profile ID

    Example of POST data

    {
      "genre": "Male",
      "age": 27
    }
    

    POST data description

    Any valid JSON document containing profile information that are relevant to you is accepted.

    Example of HTTP Response

    {
      "profile_id": "t3k7fgztq6fj2ymt",
      "account_id": "hdjh87kUIokDFkjh90jdh", 
      "genre": "Male",
      "age": 27, 
      "creation_date": 1480955412
    }
    

    HTTP Response

    Code Description
    201 Profile created
    400 Too many profiles for this account

    Get a profile

    Get profile information.

    curl {base_url}/v1/accounts/{account_id}/profiles/{profile_id}
      -X GET 
      -H "Content-Type:application/json" 
      -H "Accept:application/json" 
      -H "x-app-token:0a1z2e3r4t5y6u7i8o" 
      -H "x-platform-id:iptv"
    

    HTTP Request

    GET /v1/accounts/{account_id}/profiles/{profile_id}

    Parameters description

    Property Type Required Description
    account_id string true Account ID
    profile_id string true Profile ID

    Example of HTTP Response

    {
      "profile_id": "t3k7fgztq6fj2ymt",
      "account_id": "hdjh87kUIokDFkjh90jdh",
      "creation_date": 1480955412
    }
    

    HTTP Response

    Code Description
    200 Returns profile information
    404 Unknown profile

    Update profile details

    Update profile information. Information provided in PUT data will replace previously saved information.

    curl {base_url}/v1/accounts/{account_id}/profiles/{profile_id}
      -X PUT 
      -H "Content-Type:application/json" 
      -H "Accept:application/json" 
      -H "x-app-token:0a1z2e3r4t5y6u7i8o" 
      -H "x-platform-id:iptv"
      -d '{put_data}' 
    

    HTTP Request

    PUT /v1/accounts/{account_id}/profiles/{profile_id}

    Parameters description

    Property Type Required Description
    account_id string true Account ID
    profile_id string false Profile ID

    Example of PUT data

    {
      "age": 28
    }
    

    PUT data description

    Any valid JSON document containing profile information that are relevant to you is accepted.

    Example of HTTP response

    {
      "response": "Profile t3k7fgztq6fj2ymt has been successfully updated"
    }
    

    HTTP Response

    Code Description
    200 Profile successfully updated
    404 Unknown profile

    Reset a profile

    Reset a given profile along with its preferences.

    curl {base_url}/v1/accounts/{account_id}/profiles/{profile_id}
      -X DELETE 
      -H "Content-Type:application/json" 
      -H "Accept:application/json" 
      -H "x-app-token:0a1z2e3r4t5y6u7i8o" 
      -H "x-platform-id:iptv"
      -H "x-reset-profile:true"
    

    HTTP Request

    DELETE /v1/accounts/{account_id}/profiles/{profile_id}

    Parameters description

    Property Type Required Description
    account_id string true Account ID
    profile_id string true Profile ID

    Example of HTTP Response

    {
      "response": "Profile t3k7fgztq6fj2ymt has been successfully reset"
    }
    

    HTTP Response

    Code Description
    200 Profile successfully reset
    404 Unknown profile

    Delete a profile

    Delete a given profile along with its preferences.

    curl {base_url}/v1/accounts/{account_id}/profiles/{profile_id}
      -X DELETE 
      -H "Content-Type:application/json" 
      -H "Accept:application/json" 
      -H "x-app-token:0a1z2e3r4t5y6u7i8o" 
      -H "x-platform-id:iptv"
    

    HTTP Request

    DELETE /v1/accounts/{account_id}/profiles/{profile_id}

    Parameters description

    Property Type Required Description
    account_id string true Account ID
    profile_id string true Profile ID

    Example of HTTP Response

    {
      "response": "Profile t3k7fgztq6fj2ymt has been successfully deleted"
    }
    

    HTTP Response

    Code Description
    200 Profile successfully removed
    404 Unknown profile

    Profile preferences

    A profile can be given a set of preferences, based on content fiels defined as dimensions. Contents relating to preferences values will then be considered as closer to the profile. In a similar way, a profile can be given a set of dispreferences to move contents away. Preferences can also contain filters to be attached to the profile. Profile filters will be used for any recommendation computed for the profile. It may be used for parental control, or language/country selection, etc.

    You can find more details about filters logic in Additional notes > Understanding filters.

    Get profile preferences

    Get preferences for a given profile.

    curl {base_url}/v1/accounts/{account_id}/profiles/{profile_id}/preferences
      -X GET 
      -H "Content-Type:application/json" 
      -H "Accept:application/json" 
      -H "x-app-token:0a1z2e3r4t5y6u7i8o"
      -H "x-platform-id:iptv"
    

    HTTP Request

    GET /v1/accounts/{account_id}/profiles/{profile_id}/preferences

    Parameters description

    Property Type Required Description
    account_id string true Account ID
    profile_id string true Profile ID

    Example of HTTP Response

    {
      "profile_id": "t3k7fgztq6fj2ymt",
      "account_id": "hdjh87kUIokDFkjh90jdh",
      "creation_date": 1480955412,
      "modif_date": 1480955412,
      "preferences": {
        "movie_genre": ["Comedy","Biopic","Documentary"]
      },
      "dispreferences": {
        "movie_genre": ["Japan"]
      },
      "filters": [
        {
          "filter_type": "exclude",
          "fields": {
            "mpaa": ["nc-17","r"]
          }
        }
      ]  
    }
    

    HTTP Response

    Code Description
    200 Returns profile preferences
    404 Unknown profile

    Update profile preferences

    Profile preferences can be modified at any time. New preferences, dispreferences and filter will override the one previously saved.

    curl {base_url}/v1/accounts/{account_id}/profiles/{profile_id}/preferences
      -X PUT 
      -H "Content-Type:application/json" 
      -H "Accept:application/json" 
      -H "x-app-token:0a1z2e3r4t5y6u7i8o" 
      -H "x-platform-id:iptv"
      -d '{put_data}' 
    

    HTTP Request

    PUT /v1/accounts/{account_id}/profiles/{profile_id}/preferences

    Parameters description

    Property Type Required Description
    account_id string true Account ID
    profile_id string true Profile ID

    Example of PUT data

    {
      "preferences": {
        "movie_genre": ["Comedy","Drama","Thriller"]
      },
      "dispreferences": {
        "country": ["Japan"]
      },
      "filters": [
        {
          "filter_type": "include",
          "fields": {
            "mpaa": ["nc-17","r"],
            "csa_code": "TP"
          }
        },
        {
          "filter_type": "exclude",
          "fields": {
            "explicit_content": true
          }
        }
      ]
    }
    

    PUT data description

    Property Type Required Description
    preferences object false Profile preferences
    dispreferences object false Profile dispreferences (negtive impact)
    filters array false Profile filters (exclusion)

    Example of HTTP response

    {
      "response": "Profile t3k7fgztq6fj2ymt preferences has been successfully updated"
    }
    

    HTTP Response

    Code Description
    200 Preferences successfully updated
    400 Incorrect PUT data
    404 Unknown profile

    Smart engine

    Profile based recommendation

    A profile based recommendation provides a list of recommended contents, based on the profile’s preferences and past usage. The number of returned content items can be specified in the postdata of the standard recommendation request. By default the number of content items is set to 3.

    curl {base_url}/v1/accounts/{account_id}/profiles/{profile_id}/recos
      -X POST 
      -H "Content-Type:application/json" 
      -H "Accept:application/json" 
      -H "x-app-token:0a1z2e3r4t5y6u7i8o"
      -H "x-platform-id:mobile/ios"
      -d '{post_data}' 
    

    HTTP Request

    POST /v1/accounts/{account_id}/profiles/{profile_id}/recos

    Parameters description

    Property Type Required Description
    account_id string true Account ID
    profile_id string true Profile ID

    Example of POST data

    {
      "size": 2
    }
    

    POST data description

    Property Type Required Default Description
    size integer false 3 Number of contents

    Example of HTTP response

    {
      "reco_id": "14186e5e6",
      "from_profile": "t3k7fgztq6fj2ymt",
      "expected_size": 2,
      "size": 2,
      "filtered": false,
      "device_type": "mobile",
      "device_detail": "ios",
      "contents": [
        {
          "uid": "IA2002ChrisWedge",
          "title": "Ice Age",
          "director": "Chris Wedge",
          "movie_genre": [
            "Animation",
            "Comedy"
          ],
          "country": "USA",
          "cast": []
        },
        {
          "uid": "KP2009HaejunLee",
          "title": "Kimssi Pyorugi",
          "director": "Hae-jun Lee",
          "movie_genre": [
            "Romance"
          ],
          "country": "South Korea",
          "cast": [
            "Jae-yeong Jeong",
            "Ryeowon Jung"
          ]
        }
      ],
      "creation_date": 1467302580
    }
    

    HTTP Response

    Body description

    Property Type Optional Description
    reco_id string false Recommendation unique identifier
    from_profile string false Targeted profile
    contents array false Recommended contents
    expected_size int false Asked reco_size
    size int false Number of recommended contents
    filtered bool false True if a filter has been applied
    device_type string false Platform used
    device_detail string true Details on platform used
    creation_date long false Creation timestamp

    Codes description

    Code Description
    201 Return the recommendation computed for the profile
    404 Unknown profile or empty catalog

    Content based recommendation

    A recommendation around related content, prioritizes the recommendation around the current item that the user has just viewed. This endpoint is used to encourage users to discover more related content around what a user has just seen. If you want to fine-tune the reccommendation according to profile history, to exclude contents that the profile already watched for instance, you can simply add the profile ID to POST data.

    curl {base_url}/v1/contents/{content_id}/recos
      -X POST 
      -H "Content-Type:application/json" 
      -H "Accept:application/json" 
      -H "x-app-token:0a1z2e3r4t5y6u7i8o"
      -H "x-platform-id:mobile/ios"
      -d '{post_data}' 
    

    HTTP Request

    POST /v1/contents/{content_id}/recos

    Parameters description

    Property Type Required Description
    content_id string true Content ID

    Example of POST data

    {
      "size": 2,
      "profile_id": "t3k7fgztq6fj2ymt"
    }
    

    POST data description

    Property Type Required Default Description
    size integer false 3 Number of contents
    profile_id string false None Profile ID

    Example of HTTP response

    {
      "reco_id": "14186e5e6",
      "from_content": "DJAT2008JeanBecker",
      "expected_size": 2,
      "size": 2,
      "filtered": false,
      "device_type": "mobile",
      "device_detail": "ios",
      "contents": [
        {
          "uid": "B1996AlbertDupontel",
          "title": "Bernie",
          "director": "Albert Dupontel",
          "movie_genre": [
            "Comedy"
          ],
          "country": "France",
          "cast": [
            "Claude Perron",
            "Albert Dupontel"
          ]
        },
        {
          "uid": "SP2008GabrieleMuccino",
          "title": "Seven Pounds",
          "director": "Gabriele Muccino",
          "movie_genre": [
            "Drama"
          ],
          "country": "USA",
          "cast": [
            "Will Smith", 
            "Rosario Dawson"
          ]
        }
      ],
      "creation_date": 1467302580
    }
    

    HTTP Response

    Body description

    Property Type Optional Description
    reco_id string false Recommendation unique identifier
    from_content string false Targeted content
    contents array false Recommended contents
    expected_size int false Asked reco_size
    size int false Number of recommended contents
    filtered bool false True if a filter has been applied
    device_type string false Platform used
    device_detail string true Details on platform used
    creation_date long false Creation timestamp

    Codes description

    Code Description
    201 Returns computed recommendation

    Collaborative filtering

    Collaborative filtering is a type of recommendation using a different calculation method from the one used by standard recommendation. Instead of considering contents metadata, collaborative filtering relies on actions made by users across the catalog to determine correlations.

    Unlike standard recommendation, which is computed in real time, collaborative filtering calculation is asynchronous. As a consequence, contents added to the catalog will not be recommended until the next day.

    To obtain a recommandation using collaborative filtering, you need to add the pair based_on: user_actions in POST data on standard recommendation requests.

    curl {base_url}/v1/contents/{content_id}/recos
      -X POST 
      -H "Content-Type:application/json" 
      -H "Accept:application/json" 
      -H "x-app-token:0a1z2e3r4t5y6u7i8o"
      -H "x-platform-id:iptv"
      -D {post_data}
    

    Example of POST data

    {
      "based_on": "users_actions",
      "size": 2,
      "profile_id": "Leonard"
    }
    

    Example of HTTP response

    {
      "reco_id": "14186e5e6",
      "from_content": "TSM2007DavidSilverman",
      "expected_size": 2,
      "size": 2,
      "filtered": false,
      "device_type": "iptv",
      "reco_type": "CF_CONTENT",
      "contents": [
        {
          "uid": "SP2016GregTiernan",
          "title": "Sausage Party",
          "director": "Greg Tiernan",
          "movie_genre": [
            "Animation", 
            "Adventure"
          ],
          "country": "USA",
          "cast": [
            "Seth Rogen",
            "Kristen Wiig"
          ]
        },
        {
          "uid": "TLBM2017ChrisMcKay",
          "title": "The LEGO Batman Movie",
          "director": "Chris McKay",
          "movie_genre": [
            "Animation", 
            "Action"
          ],
          "country": "USA",
          "cast": [
            "Will Arnett", 
            "Michael Cera"
          ]
        }
      ],
      "creation_date": 1467302580
    }
    

    HTTP Request

    POST /v1/contents/{content_id}/recos

    Parameters description

    Property Type Required Description
    content_id string true Content ID

    POST data description

    Property Type Required Default Description
    based_on string true None  "users_actions"
    size integer false 3 Number of contents
    profile_id string false None Profile ID

    HTTP response

    Code Description
    201 Returns recommended contents

    Recommendation filters

    Example of POST data sent to recommend only contents of type Drama or Romance, except the one with not appropriate to a young audience

    {
      "size": 2,
      "filters": [
        {
          "filter_type": "include",
          "fields": {
            "genre": ["Drama","Romance"]
          }
        },
        {
          "filter_type": "exclude",
          "fields": {
            "mpaa": ["nc-17","r"]
          }
        }
      ]
    }
    

    In some cases, it can be very usefull to include or exclude a big part of the catalog in some specific recommendations. Filters can be used on every recommandations by adding the filter object to POST data.

    A recommendation filtered by category will generate a recommended list of contents that prioritizes the specified filters in addition to factoring in a user's preferences and past usage.

    POST data description

    Property Type Required Default Description
    size integer false 3 Number of contents
    filters array false None Array containing one or multiple filters

    Profile development

    You can help us learning about profiles by reporting interactions between a profile and a content. Action types can be customized to better fit with your application: we could imagine buy or share actions if it is relevant to the application. To help you get started, a list of actions has been predefined. The API also provide a call to retrieve the actions done by a profile sorted by date.

    Action type Description
    view Profile has started to watch the content
    like Profile has expressed that he likes the content
    dislike Profile has expressed that he dislikes the content
    skip Profile has skipped to another content

    Send an action

    Send an action done by a given profile on a content.

      {base_url}/v1/accounts/{account_id}/profiles/{profile_id}/actions
      -X POST 
      -H "Content-Type:application/json" 
      -H "Accept:application/json" 
      -H "x-app-token:0a1z2e3r4t5y6u7i8o" 
      -H "x-platform-id:mobile/ios"
      -d '{post_data}' 
    

    HTTP Request

    POST /v1/accounts/{account_id}/profiles/{profile_id}/actions

    Parameters description

    Property Type Required Description
    account_id string true Account ID
    profile_id string true Profile ID

    Examples of POST data

    {
      "content_id": "SP2008GabrieleMuccino",
      "reco_id": "447ca7752c534edbb",
      "type": "view",
      "percentage_viewed": 0,
      "duration_viewed": 0
    }
    
    {
      "content_id": "SP2008GabrieleMuccino",
      "reco_id": "447ca7752c534edbb",
      "type": "like",
      "percentage_viewed": 78,
      "duration_viewed": 96
    }
    
    {
      "content_id": "SP2008GabrieleMuccino",
      "reco_id": "447ca7752c534edbb",
      "type": "skip",
      "percentage_viewed": 6,
      "duration_viewed": 7
    }
    

    POST data description

    Property Type Required Description
    profile_id string true Profile responsible for the action
    content_id string true Targeted content
    reco_id string true Recommendation that generated the action
    type string true Action type (view, like, dislike, ...)
    percentage_viewed integer true Percentage of the content viewed
    duration_viewed integer true Duration viewed

    Example of HTTP response

    {
      "profile_id": "t3k7fgztq6fj2ymt",
      "content_id": "SP2008GabrieleMuccino",
      "reco_id": "447ca7752c534edbb",
      "device_type": "mobile",
      "device_detail": "ios",
      "type": "skip",
      "percentage_viewed": 6,
      "duration_viewed": 7,
      "creation_date" : 1480959385
    }
    

    HTTP Response

    Body description

    Property Type Optional Description
    profile_id string false Profile responsible for the action
    content_id string false Targeted content
    reco_id string false Recommendation that generated the action
    type string false Action type (view, like, dislike, ...)
    percentage_viewed integer false Percentage of the content viewed
    duration_viewed integer false Duration viewed
    device_type string false Platform used
    device_detail string true Details on platform used
    creation_date long false Creation timestamp

    Codes description

    Code Description
    200 Action successfully saved
    400 Unknown action type
    404 Unknown recommendation or content

    Delete all actions

    Delete all actions done by a given profile.

      {base_url}/v1/accounts/{account_id}/profiles/{profile_id}/actions
      -X DELETE
      -H "Content-Type:application/json" 
      -H "Accept:application/json" 
      -H "x-app-token:0a1z2e3r4t5y6u7i8o" 
      -H "x-platform-id:iptv"
    

    HTTP Request

    DELETE /v1/accounts/{account_id}/profiles/{profile_id}/actions

    Parameters description

    Property Type Required Description
    account_id string true Account ID
    profile_id string true Profile ID

    HTTP Response

    Code Description
    200 Action has been deleted
    400 Missing parameter
    404 Action not found for given profile

    Editorial Lists

    Get all published editorial list

    Get the list of published editorial lists

    curl {base_url}/v1/lists?page={page}&per_page={per_page}
      -X GET
      -H "Content-Type:application/json" 
      -H "Accept:application/json" 
      -H "x-app-token:0a1z2e3r4t5y6u7i8o" 
      -H "x-platform-id:pc"
    

    HTTP Request

    GET /v1/lists?page={page}&per_page={per_page}

    Parameters description

    Property Type Required Description
    page integer false Page requested
    per_page integer false Number of playlist per page requested

    Example of HTTP Response

    {
      "size": 2,
      "lists_size" : 8,
      "page": 1,
      "per_page": 2,
      "total_pages": 4,
      "lists": [
        {
          "playlist_id": "editorial1",
          "name": "The editorial list n°1",
          "image_url": "http://abf.com/image/editorial1.jpg"
            "order" : 1,
          "influence_reco": true,
          "creation_date":1487116800,
          "modif_date":1487116800
        },
        {
          "playlist_id": "editorial2",
          "name": "The editorial list n°2",
          "image_url": "http://abf.com/image/editorial2.jpg"
          "order" : 2,
          "influence_reco": false,
          "creation_date":1487116800,
          "modif_date":1487116800
        }
      ]
    }
    

    HTTP Response

    Body description

    Property Type Optional Description
    size integer false Number of lists provided in the response
    lists_size integer false Total number of lists available
    page integer true Page number in case of pagination
    per_page integer true Number of contents per page in case of pagination
    total_pages integer true Total number of pages in case of pagination
    lists array false The list of playlist

    Codes description

    Code Description
    200 Returns all published editorial list

    Get published editorial list details

    Get published editorial list details.

    curl {base_url}/v1/lists/{list_id}?page={page}&per_page={per_page}
      -X GET 
      -H "Content-Type:application/json" 
      -H "Accept:application/json" 
      -H "x-app-token:0a1z2e3r4t5y6u7i8o" 
      -H "x-platform-id:pc"
    

    HTTP Request

    GET /v1/lists/{list_id}?page={page}&per_page={per_page}

    Parameters description

    Property Type Required Description
    list_id string true List ID
    page integer false Page requested
    per_page integer false Number of content per page requested

    Example of HTTP Response

    { 
      "playlist_id" : "editorial1", 
      "name" : "The editorial list n°1", 
      "size": 2,
      "contents_size": 10,
      "page": 1,
      "per_page": 2,
      "total_pages": 5,
      "influence_reco" : false, 
      "creation_date" : 1487116800,
      "modif_date" : 1487116800,
      "contents" : [
        {
          "uid":"IA2002ChrisWedge",
          "title":"Ice Age",
          "director":"Chris Wedge",
          "movie_genre":[
            "Animation",
            "Comedy"
          ],
          "country":"USA",
          "cast":[]
        },
        {
          "uid":"KP2009HaejunLee",
          "title":"Kimssi Pyorugi",
          "director":"Hae-jun Lee",
          "movie_genre":[
            "Romance"
          ],
          "country":"South Korea",
          "cast":[
            "Jae-yeong Jeong",
            "Ryeowon Jung"
          ]
        }
      ]
    }
    

    HTTP Response

    Body description

    Property Type Optional Description
    playlist_id string false The Playlist unique ID
    name string false The Playlist name
    size integer false Number of contents provided in the response
    contents_size integer false Total number of contents available
    page integer true Page number in case of pagination
    per_page integer true Number of contents per page in case of pagination
    total_pages integer true Total number of pages in case of pagination
    influence_reco string false Indicate that the list is used to over/under-weight the recommendation
    creation_date long false Creation timestamp
    modif_date long false Last modification timestamp
    contents array false The list of contents

    Codes description

    Code Description
    200 Returns published editorial list details
    404 Unknown editorial list

    Main workflow diagrams

    For a backend to backend integration

    For an application to backend integration

    Additional notes

    Understanding filters

    Example of filter used to consider only films where "genre" is Drama or Romance, and where the "country" is Japan.

    {
      "filter_type": "include",
      "fields": {
        "movie_genre": ["Drama", "Romance"],
        "country": "Japan"
      }
    }
    

    To get further in recommendation customization, multiple API features can be used with filters.

    Filters main rules are:

    Example of filters are available in section Smart engine > Recommendation filters.