The Smart Recommendations API is a secure REST API that lets you retrieve content recommendations made by an engine that employs machine learning to improve its accuracy.
If you want to use the API for your projects, see how to set up Smart Recommendations. We also recommend using the Smart Recommendations custom element.
Smart Recommendations 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://recommend.kontent.ai/
.
To work with the Smart Recommendations API, send your requests over HTTPS and authenticate using the Authorization
header in the following format: Authorization: Bearer <YOUR_API_KEY>
.
To get your API key for the Smart RecommendAPI ations API, go to Kentico Kontent > Smart Recommendations > Smart Recommendations API key. The API key provide access to a single Kentico Kontent project. You will need different API keys for each of your projects.
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.
Security Scheme Type | HTTP |
---|---|
HTTP Authorization Scheme | bearer |
Bearer format | "Bearer <YOUR_API_KEY>" |
We offer a .NET SDK and JavaScript SDK to easily use the Smart Recommendations API. However, no SDK is required to use the API.
Kentico Kontent returns standard HTTP status codes to indicate the success or failure of a request. In general, status codes in the 2xx
range indicate a successful request, status codes in the 4xx
range indicate errors caused by an incorrect input (for example, providing incorrect API key), and status codes in the 5xx
range indicate an error on our side.
Status code |
Description |
|
The request was not understood. Check your request for a missing required parameter or an invalid query parameter value. |
|
The provided API key is invalid or missing. |
|
The provided API key is invalid for the requested project. |
|
The requested resource doesn't exist. Try checking the resource name for typos. |
|
The requested HTTP method is not supported for the specified resource. Try performing a GET request. |
|
The rate limit for the API has been exceeded. Try your request again after a few seconds as specified in the |
|
Something went wrong on our side. Try your request again after a few seconds and use a retry policy. |
For troubleshooting failed requests, the API provides error messages defined in a consumable format to help you identify and fix the issue.
errors | object The error messages describing the issues found when processing the request. |
type | string Nullable A link specifying the error type. |
title | string Nullable The summary of the error. |
status | integer <int32> Nullable The HTTP status code of the error response. |
detail | string Nullable Additional information about the error. |
instance | string Nullable Additional internal information about the error. |
traceId | string The internal ID of the error. You can use this to debug problems with our support. |
<property_name>* | object |
{- "errors": {
- "visitId": [
- "No white space allowed"
]
}, - "title": "One or more validation errors occurred.",
- "status": 400,
- "traceId": "00-243f900e945668408bdd3bc85165a3f3-08fdfccd8e59164d-00"
}
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.
Aside from giving Smart Recommendations enough data (through tracking) to build an accurate recommendations model, you can influence what recommendations you get. You can use three methods to modify the recommendation process.
You can use these methods together to tune the recommendations you get. Both filtering and boosting rely on the Recombee query language (ReQL). To create correct queries, make sure you're familiar with the properties you can use within the recommendation database.
The Smart Recommendations API exposes several properties of the content items it indexes. This content structure can be used to create custom filters and boosters for your recommendations.
codename | string [ 1 .. 200 ] characters The content item's codename. |
name | string non-empty The content item's name. |
lastupdated | string <timestamp> The date and time of the last change to user-content of the content item converted to milliseconds. The |
type | string The content item's type. |
properties | string <set> The content item's multiple choice and taxonomy elements serialized to an array of name-value pairs. For example, if an indexed item has a Persona taxonomy with the Developer and Owner values selected, these values will be stored in the You can find these filterable properties in the Smart Recommendations UI under Content types to recommend. |
{- "codename": "example_blogpost",
- "name": "Example Blog post",
- "lastupdated": "259200000",
- "type": "string",
- "properties": "[persona=developer,persona=owner]"
}
For example, to filter content tagged with the developer persona, use a ReQL filter query such as \"persona=developer\" in 'properties'
.
You need to escape the ReQL queries correctly. You can combine different filters and use standard AND, OR, and NOT operators. See ReQL documentation for more information.
For example, to favor content updated within the last 30 days, use a ReQL booster query such as if 'lastupdated' >= now() - 259200000 then 2 else 1
. This query makes it twice as likely to recommend items updated in the last 30 days (converted to milliseconds).
The API can still recommend older content if it evaluates it as far more valuable for a specific visitor. However, using a large boost ratio (like 2:1 in the example above) makes this less likely.
You can recommend content to your visitors using two approaches:
In both cases, you need to assign a unique identifier (called visitId
) to each visitor for Smart Recommendations to work correctly.
To take your visitors' location into account, go to Smart Recommendations in Kontent and activate Geolocation. Then, with each recommendation request, include the visitor's IP address.
The API sends the IP address to the IP Geolocation API service and saves the location it gets. The IP address is not stored nor used for any other purpose.
// Specifies geolocation information about a visitor var visitor = new VisitorDetails { // If you enabled Geolocation, provide the visitor's IP address Ip = "192.166.12.4", Referer = "google.com", // If you disabled Geolocation, you can specify location yourself Location = new LocationDetails { City = "Brno", Country = "Czech Republic", Timezone = "CET" } };
You can also get the visitors' location on your own and send the location to the Smart Recommendation API in your own format.
Smart Recommendations API (BETA)
Requests a list of recommendations based on the content item the visitor is viewing. The API returns a list of item codenames. See how to adjust the recommendations you get.
If you're not using Manual tracking, this action will also automatically track a visit for the specific content item.
The recommendation request.
visitId required | string Specifies the user-generated identifier of the specific website visitor or app user. |
currentItemCodename required | string Specifies the viewed content item's codename. |
responseLimit required | integer <int32> >= 1 Specifies the number of recommendations you want to get. |
requestedTypeCodename required | string Specifies a content type's codename, that is, what type of content you want recommended. |
recommendationSettings | object Specifies optional recommendation settings such as filtering, boosting, and scenario selection. |
visitor | object Details about the visitor such as their location and web page they came from. Can also include custom properties. |
List of the recommended item codenames
Bad request
{- "visitId": "visitorId123",
- "currentItemCodename": "example_blogpost",
- "responseLimit": 3,
- "requestedTypeCodename": "blog_post",
- "recommendationSettings": {
- "filter": "\"persona=developer\" in 'properties'",
- "booster": "if 'lastupdated' >= now() - 259200000 then 2 else 1",
- "scenario": "popular"
}, - "visitor": {
- "ip": "192.166.12.4",
- "location": {
- "city": "Brno",
- "country": "Czech Republic",
- "timezone": "CET"
}, - "custom": {
- "persona": "developer"
}
}
}
[- {
- "codename": "example_blog_post_1"
}, - {
- "codename": "example_blog_post_2"
}, - {
- "codename": "example_blog_post_3"
}
]
Smart Recommendations API (BETA)
Requests a list of recommendations based on a search phrase. The API returns a list of item codenames.
The search request for recommendation.
visitId required | string Specifies the user-generated identifier of the specific website visitor or app user. |
query required | string Specifies the search term you're looking for. |
resultCount required | integer <int32> Specifies the number of recommendations you want to get. |
requestedTypeCodename | string Nullable Specifies a content type's codename, that is, what type of content you want recommended. |
Success
Bad request
{- "visitId": "visitorId123",
- "query": "collaboration",
- "resultCount": 3,
- "requestedTypeCodename": "blog_post"
}
[- {
- "codename": "example_blog_post_1"
}, - {
- "codename": "example_blog_post_2"
}, - {
- "codename": "example_blog_post_3"
}
]
To manually track visits, conversions, or partial content views, go to Kentico Kontent > Smart Recommendations and enable Manual tracking.
Make sure you do this after you've adjusted your app because this action disables automatic content visit tracking. With manual tracking is enabled, content visits are no longer tracked automatically.
Smart Recommendations API (BETA)
Stores visitor details in Smart Recommendations. The details can include visitor location, web page they came from, and custom properties.
The endpoint works with both automatic tracking and manual tracking. Call this endpoint when you first encounter a visitor in your app to store information about them.
Details about the visitor such as their location and web page they came from. Can also include custom properties.
visitId required | string Specifies the user-generated identifier of the specific website visitor or app user. |
visitor | object Details about the visitor such as their location and web page they came from. Can also include custom properties. |
Ok
Bad request
{- "visitId": "visitorId123",
- "visitor": {
- "ip": "192.166.12.4",
- "location": {
- "city": "Brno",
- "country": "Czech Republic",
- "timezone": "CET"
}, - "custom": {
- "persona": "developer"
}
}
}
{- "errors": {
- "visitId": [
- "No white space allowed"
]
}, - "title": "One or more validation errors occurred.",
- "status": 400,
- "traceId": "00-243f900e945668408bdd3bc85165a3f3-08fdfccd8e59164d-00"
}
Smart Recommendations API (BETA)
Tracks a standard page visit.
Visit data
visitId required | string Specifies the user-generated identifier of the specific website visitor or app user. |
currentItemCodename required | string The viewed content item's codename. |
Ok
Bad request
{- "visitId": "visitorId123",
- "currentItemCodename": "example_blog_post"
}
{- "errors": {
- "visitId": [
- "No white space allowed"
]
}, - "title": "One or more validation errors occurred.",
- "status": 400,