Skip navigation

Smart Recommendations API

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.

Introduction

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

Authentication

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.

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.

Security Scheme Type HTTP
HTTP Authorization Scheme bearer
Bearer format "Bearer <YOUR_API_KEY>"

SDK

We offer a .NET SDK and JavaScript SDK to easily use the Smart Recommendations API. However, no SDK is required to use the API.

Errors

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.

HTTP status 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.

429 Too Many Requests

The rate limit for the API has been exceeded. Try your request again after a few seconds as specified in the Retry-After header.

5xx Internal Error or Service Unavailable

Something went wrong on our side. Try your request again after a few seconds and use a retry policy.

Resolving errors

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
Copy
Expand all Collapse all
{}

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.

Adjust the recommendations you get

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.

  1. Filtering – Lets you filter your content items by their taxonomy or multiple choice elements. In the recommendation database, these elements are converted to a set of properties you can use for filtering. For example, you can filter items tagged with the developer persona. Tip: You can find the properties in the Smart Recommendations UI under Content types to recommend.
  2. Boosting – Lets you boost certain content items to make them more prominent and more likely to be recommended. For example, you can boost items updated in the last week or month.
  3. Scenario selection – Lets you choose the scenario used for sorting the recommendations. The API recognizes the following scenarios:
    • Similar – the engine recommends content most similar to what the user is viewing at the moment.
    • Popular – the engine sorts the recommendations by popularity.
    • Default – the engine combines the scenarios above and sorts recommendations by similarity and popularity.

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.

Properties to query by

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.

Structure of items in recommendation database

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 lastupdated property can be used for boosting newer content, filtering for only new items, and so on.

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 properties property as [persona=developer,persona=owner].

You can find these filterable properties in the Smart Recommendations UI under Content types to recommend.

Copy
Expand all Collapse all
{
  • "codename": "example_blogpost",
  • "name": "Example Blog post",
  • "lastupdated": "259200000",
  • "type": "string",
  • "properties": "[persona=developer,persona=owner]"
}

Filtering

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.

Boosting

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.

Recommend content

You can recommend content to your visitors using two approaches:

  1. Recommend based on the content item they are viewing right now. This approach also supports filtering and boosting.
  2. Recommend based on a search phrase.

In both cases, you need to assign a unique identifier (called visitId) to each visitor for Smart Recommendations to work correctly.

Regional recommendations with geolocation

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.

  • C#
// 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.

Recommend content based on visited content Beta

post/recommend/items
See full URL

Smart Recommendations API (BETA)

https://recommend.kontent.ai/api/v2/recommend/items

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.

Authorizations:
Request Body schema: application/json

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.

Responses

200

List of the recommended item codenames

400

Bad request

Request samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "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":
    {}
}

Response samples

Content type
application/json
Copy
Expand all Collapse all
[
  • {
    • "codename": "example_blog_post_1"
    },
  • {
    • "codename": "example_blog_post_2"
    },
  • {
    • "codename": "example_blog_post_3"
    }
]

Recommend content based on a search phrase Beta

post/search/items
See full URL

Smart Recommendations API (BETA)

https://recommend.kontent.ai/api/v2/search/items

Requests a list of recommendations based on a search phrase. The API returns a list of item codenames.

Authorizations:
Request Body schema: application/json

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.

Responses

200

Success

400

Bad request

Request samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "visitId": "visitorId123",
  • "query": "collaboration",
  • "resultCount": 3,
  • "requestedTypeCodename": "blog_post"
}

Response samples

Content type
application/json
Copy
Expand all Collapse all
[
  • {
    • "codename": "example_blog_post_1"
    },
  • {
    • "codename": "example_blog_post_2"
    },
  • {
    • "codename": "example_blog_post_3"
    }
]

Track interactions manually

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.

Track visitor details Beta

post/track/visitor
See full URL

Smart Recommendations API (BETA)

https://recommend.kontent.ai/api/v2/track/visitor

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.

Authorizations:
Request Body schema: application/json

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.

Responses

200

Ok

400

Bad request

Request samples

Content type
application/json
Copy
Expand all Collapse all
{}

Response samples

Content type
application/json
Copy
Expand all Collapse all
{}

Track a visit Beta

post/track/visit
See full URL

Smart Recommendations API (BETA)

https://recommend.kontent.ai/api/v2/track/visit

Tracks a standard page visit.

Authorizations:
Request Body schema: application/json

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.

Responses

200

Ok

400

Bad request

Request samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "visitId": "visitorId123",
  • "currentItemCodename": "example_blog_post"
}

Response samples

Content type
application/json
Copy
Expand all Collapse all
{}