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