Skip navigation

Recommendation API

The Recommendation API is a secure REST API that provides access to recommendations made by an engine that employs machine learning to improve its accuracy.

Introduction

Premium feature

The Recommendation API requires an Enterprise plan.

Recommendation API is in Beta

This feature is in beta and its behavior may change in the future.

Use the API to provide personalized recommendations to your users.

The base URL for all requests is https://recommendations.kontent.ai/api.

The API makes recommendations based on a specific content type. Read Personalizing content with smart recommendations to learn more including how to set up access to the API.

Authentication

Requests to the Recommendation API must be authenticated.

Bearer

This API uses OAuth 2.0 bearer token (API key) to authorize requests. Requests with an incorrect or missing Authorization header will fail with an error.

To get your API key for the API, go to Kentico Kontent -> Project settings -> API keys. The API keys provide access to a single Kentico Kontent project. You will need different API keys for each of your projects.

Security scheme type: HTTP
HTTP Authorization Scheme bearer
Bearer format "Bearer <YOUR_API_KEY>"

Errors

Kentico Kontent returns standard HTTP status codes to indicate success or failure of a request. In general, codes in the 2xx range indicate a successful request, codes in the 4xx range indicate errors caused by an incorrect input (for example, providing incorrect API key), and codes in the 5xx range indicate an error on our side.

Error codes summary

Status code

Description

400 Bad Request

The request was not understood. Check your request for a missing required parameter or an invalid query parameter value.

401 Unauthorized

The provided API key is invalid or missing.

403 Forbidden

The provided API key is invalid for the requested project.

404 Not Found

The requested resource doesn't exist. Try checking the resource name for typos.

405 Method Not Allowed

The requested HTTP method is not supported for the specified resource. Try performing a GET request.

500 Internal Server Error

Something went wrong on our side. Try the request again in a few minutes, or contact us.

Resolving errors

For troubleshooting failed requests, the API provides error messages defined in a consumable format to help you identify and fix the issue.

If you cannot identify and resolve an issue with your API call, you can contact us with the response status and the request ID you get in the error response.

Recommended items

Learn about recommending content to your visitors in Personalizing content with smart recommendations.

Tracking

Requesting a recommendation will track a default interaction between the visitor and content (a visit), but you can also log visitor–content interactions yourself. See how to track events.

Track a conversion Beta

post /track/conversion
See full URL

Recommendation API

https://recommendations.kontent.ai/api/track/conversion

A conversion is similar to a user visit but has a higher value.

Authorizations:
query Parameters
contentItemId
required
string
Example: contentItemId=item_codename_0

The codename of the currently visited content item.

visitId
required
string
Example: visitId=visitor01

The ID of the current user.

Request Body schema: application/json

A Caller info object contains additional information about the user for whom you're requesting recommendations. It can be filled up completely by the API user, in which case provided information is stored in the recommendation system to further improve its performance, or if an IP address is provided, the geolocation data will be filled up automatically by the system.

Note: The IP address is not being stored anywhere in the system.

city
string

The visitor's city.

country
string

The visitor's country.

ip
string

The visitor's IP address.

Note: This data is not persistent.

mobile
boolean

Determines whether the user is using a mobile device.

referer
string

The source of the visitor's visit.

sourceApp
string

Identification of the application tracking the visitor.

Responses

200

OK

Request samples

application/json
Copy
Expand all Collapse all
{
  • "ip": "127.0.0.1",
  • "sourceApp": "web"
}

Track a visit Beta

post /track/visit
See full URL

Recommendation API

https://recommendations.kontent.ai/api/track/visit

Logs a visit for a specific content item.

Authorizations:
query Parameters
contentItemId
required
string
Example: contentItemId=item_codename_0

The codename of the currently visited content item.

visitId
required
string
Example: visitId=visitor01

The ID of the current user.

Request Body schema: application/json

A Caller info object contains additional information about the user for whom you're requesting recommendations. It can be filled up completely by the API user, in which case provided information is stored in the recommendation system to further improve its performance, or if an IP address is provided, the geolocation data will be filled up automatically by the system.

Note: The IP address is not being stored anywhere in the system.

city
string

The visitor's city.

country
string

The visitor's country.

ip
string

The visitor's IP address.

Note: This data is not persistent.

mobile
boolean

Determines whether the user is using a mobile device.

referer
string

The source of the visitor's visit.

sourceApp
string

Identification of the application tracking the visitor.

Responses

200

OK

Request samples

application/json
Copy
Expand all Collapse all
{
  • "ip": "127.0.0.1",
  • "sourceApp": "web"
}

Track view of portion of content Beta

post /track/portionview
See full URL

Recommendation API

https://recommendations.kontent.ai/api/track/portionview

Tracks a user viewing a portion of content (multiple subsequent portion views are joined and the value is maximized).

Authorizations:
query Parameters
contentItemId
required
string
Example: contentItemId=item_codename_0

The codename of the currently visited content item.

portionPercentage
required
integer <int32>
Example: portionPercentage=20

The percentage of the page the user has seen.

visitId
required
string
Example: visitId=visitor01

The ID of the current user.

Request Body schema: application/json

A Caller info object contains additional information about the user for whom you're requesting recommendations. It can be filled up completely by the API user, in which case provided information is stored in the recommendation system to further improve its performance, or if an IP address is provided, the geolocation data will be filled up automatically by the system.

Note: The IP address is not being stored anywhere in the system.

city
string

The visitor's city.

country
string

The visitor's country.

ip
string

The visitor's IP address.

Note: This data is not persistent.

mobile
boolean

Determines whether the user is using a mobile device.

referer
string

The source of the visitor's visit.

sourceApp
string

Identification of the application tracking the visitor.

Responses

200

OK

Request samples

application/json
Copy
Expand all Collapse all
{
  • "ip": "127.0.0.1",
  • "sourceApp": "web"
}