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:

GET requests fetch information about an object
POST requests create objects
PUT requests update objects
DELETE requests delete objects

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

In case of GET or POST request, the full object is returned
In case of PUT or DELETE request, a confirmation message is returned
In case something wrong happened, an information message is returned in addition to the HTTP status code

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:

Backend to backend: A fixed token will be provided at an early stage of the project. This token grants you access to all API requests no matter the user. This token is mandatory and must be provided in the HTTP header x-app-token for every requests.
Application to backend mode: Each user must log in to CogniK using an API key, provided at an early stage of the project, and a password. A dedicated token, valid for a certain period of time, will be generated for each user. This token is mandatory and must be provided in the HTTP header x-app-token for every requests. After using the API, the user must eventually log out.

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

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:

A filter is represented as a JSON object. It can be an inclusion or an exclusion filter. It can contain one or multiple fields.
A field can have one or multiples value to apply on. Each value must be consistent with contents metadata (case and type).
A logical OR is applied between each value of a filter whereas a logical AND is applied between each defined filters.

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