cs-icon.svg

Personalize Edge APIBETA

x.x.1Run in Swagger

Introduction

Overview

The Personalize Edge API enables real-time, dynamic interactions closer to the end user by utilizing edge computing infrastructure to retrieve your personalized content and display it to your visitors on your digital properties.

This documentation provides information on endpoints, operations, parameters, and responses for the Contentstack Personalize Edge API. The API allows you to set and manage user attributes, get manifest, and track events for your Personalize project.

Base URL

For Personalize Edge API

  • AWS US (North America, or NA): https://personalize-edge.contentstack.com
  • AWS Europe (EU): https://eu-personalize-edge.contentstack.com
  • Azure North America (Azure NA): https://azure-na-personalize-edge.contentstack.com
  • Azure Europe (Azure EU): https://azure-eu-personalize-edge.contentstack.com
  • GCP North America (GCP NA): https://gcp-na-personalize-edge.contentstack.com

Authentication

The Personalize Edge API does not require any authentication since it is used on the public facing digital properties.

Headers

Some endpoints require x-cs-personalize-user-uid and x-project-uid headers for user and project identification.

For Project User UID, and Project UID
  • Pass the Personalize User’s UID against the x-cs-personalize-user-uid parameter as header.
  • Pass the Project’s UID against the x-project-uid parameter as header for project-based APIs.

Note: When trying out POST/PUT calls, for Project UID, you need to mandatorily pass Content-Type:application/json in the Header.

How to Get Project UID

To retrieve the project UID, perform the steps given below:

  1. Navigate to Personalize > your preferred project.
  2. Click the Settings icon in the left navigation panel.
  3. In the General tab, under Project Details, you will find the 24-character project UID.Personalize Management API - Get Project UID.png
  4. Click the Copy icon to copy the project UID to your clipboard which will be used for the API calls.
How to get Personalize User’s UID

To retrieve the user’s UID, perform the steps given below:

  1. Run the Get Manifest API request without a User UID.
  2. From the Response Headers, copy your x-cs-personalize-user-uid: 60******-****-****-****-**********50Personalize Edge API - Get User UID.png

API Conventions

  • Currently, the base URL for Personalize Edge API is available for all the regions and can be found in the Base URL section.
  • Personalize Edge API supports GET/POST/PATCH verbs or methods.
  • URL paths are written in lower case.
  • Query parameters and JSON fields use camel casing.
  • The success/failure status of an operation is determined by the HTTP status it returns. Additional information is included in the HTTP response body.

Errors

If there is something wrong with the API request, Contentstack returns an error.

Personalize uses conventional, standard HTTP status codes for errors, and returns a JSON body containing details about the error. In general, codes in the 2xx range signify success. The codes in the 4xx range indicate error, mainly due to information provided (for example, a required parameter or field was omitted). Lastly, codes in the 5xx range mean that there is something wrong with our servers; it is very rare though.

Let’s look at the error code and their meanings.

HTTP status codeDescription
400 Bad RequestThe request was incorrect or corrupted.
401 Unauthorized UserThe user is not authorized.
403 Forbidden ErrorThe page or resource that is being accessed is forbidden.
404 Not FoundThe requested page or resource could not be found.
500 Internal Server ErrorThe server is malfunctioning and is not specific on what the problem is.
502 Bad Gateway ErrorA server received an invalid response from another server.
504 Gateway Timeout ErrorA server did not receive a timely response from another server that it was accessing while attempting to load the web page or fill another request by the browser.

Note: The error codes that we get in the JSON response are not HTTP error codes but are custom Contentstack error codes that are used for internal purposes.

Using OpenAPI Files

Contentstack provides the OpenAPI files of the Contentstack’s Personalize Edge APIs that you can use to try out Contentstack APIs on any OpenAPI platform such as Swagger. You can download the OpenAPI JSON file of the Personalize Management API and open it on Swagger Editor to start using it.

To use Contentstack Personalize Management APIs with Swagger, perform the following steps:

  1. Download the JSON file from the above endpoints and go to Swagger Editor.
  2. On the Swagger Editor page, click File, and select the Import file option.
  3. Open any API request and click the Try it out button. Clicking this button will unlock the fields for you to add the values for x-cs-personalize-user-uid and x-project-uid.
  4. Open any API request and click the Try it out button. Clicking this button will unlock the fields.
  5. Click Execute to run the API request.

API Reference

Events

Events let you capture and monitor every interaction made by a user. In Contentstack Personalize, there are two types of events: Impressions and Conversions.

Impressions: Impressions are a way to count how many times users see specific content on your website.

Conversions: A conversion is an event that signifies a positive user action, such as adding a product to the cart, making a purchase, or scrolling to the end of a page. Conversions are essential for measuring the success of your A/B tests.

Track Events

Track Events

Track Events

The Track Events request lets you trigger events, and track either impressions for the experiences created in a project or conversions for your A/B Test experiences.

For Impressions, it accepts experienceShortUid, variantShortUid and type (i.e. IMPRESSION)

For Custom Event, it accepts eventKey and type (i.e. EVENT)

Note: For Custom Events, the eventKey created in the Events module needs to be specified in the API request.

Manifest

Manifest is a list of all active experiences and the corresponding variants in those experiences activated for the current user.

Get Manifest

Get Manifest

Get Manifest

The Get Manifest request fetches all the active variants for experiences in a project.

Active variants are returned as a list of experiences in the Response body with the Experience Short UID and Active Variant Short UID for each item in the list.

The list also reflects the order of the priority for each of the experiences, the items in the response higher up in the list have the higher priority.

If you run the API call without the user UID, it automatically generates a random user UID, which you can use for other subsequent calls.

Note: A variant will be null when the experience is disabled or when the user does not satisfy the criteria for any variant.

User Attributes

User attributes are key-value pairs that represent the characteristics, behaviors, or preferences of visitors interacting with your website or application. These attributes can be used to create distinct audience segments for targeted content delivery and personalized user experiences.

Set and Update User Attributes

Set and Update User Attributes

Set and Update User Attributes

The Set and Update User Attributes request lets you create and update custom attributes in a project.

Attributes created / updated with this API call needs to have a corresponding custom attribute created in the Attributes module with the same key.

The above request:

- Creates new attributes for the user if they do not already exist.

- Updates existing attributes with the provided values. In case of an attribute conflict (existing attribute has a value), and the new value takes precedence during the update.

- Only the specified key:value pairs for the attributes will be updated, and the non-specified values remain unchanged.

Merge User Attributes

Merge User Attributes

Merge User Attributes

The Merge User Attributes request lets you merge attributes using the source (anonymous user) and target (custom user) UIDs in a project.

You would want to use this API request, when an anonymous user logs in and converts into a known user of your digital property, and merge the attribute details of the anonymous user (source) into the known user (target).

Note: In case of conflict in attributes set against the source UID and target UID, the attribute value for the source UID is given precedence.

Was this article helpful?
^

Sample Request

Response
Body
PrettyRaw