Personalization

Sitecore API catalog/Agent API/Personalization

Personalization

The Personalization API lets you create personalized variants for different audiences by showing targeted content based on certain conditions.

Operations

Create a personalization variant

Request

Creates a new personalization variant of a page, enabling you to define targeting rules for different audiences.

Security

HTTPBearer

Path

pageIdstring(Pageid)required

The unique identifier of the page for which to create a personalization version. To get this ID, use List pages of a site.

Example:3f2504e0-4f89-11d3-9a0c-0305e82c3301

x-sc-job-idany(X-Sc-Job-Id)

A unique identifier for the job, used to trace, audit, and revert actions performed by an AI agent through the Agent API.

Example:job-1234

Bodyapplication/jsonrequired

namestring(Name)required

The name of the personalization rule.

Example:"Summer Sale Personalization"

variant_namestring(Variant Name)required

The name of the personalization variant.

Example:"Summer Sale Variant"

audience_namestring(Audience Name)required

The name of the audience for the personalization rule.

Example:"Returning Customers"

condition_groupsArray of objects(Condition Groups)required

List of condition groups with their conditions

languagestring or null(Language)

Example:"en"

Any of:

The language code for the personalization rule, or null for default.

string

curl -i -X POST \
  https://edge-platform.sitecorecloud.io/stream/ai-agent-api/api/v2/personalization/3f2504e0-4f89-11d3-9a0c-0305e82c3301/versions \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>' \
  -H 'Content-Type: application/json' \
  -H 'x-sc-job-id: job-1234' \
  -d '{
    "name": "Summer Sale Personalization",
    "language": "en",
    "variant_name": "Summer Sale Variant",
    "audience_name": "Returning Customers",
    "condition_groups": [
      {
        "union_type": "AND",
        "conditions": [
          {
            "condition_template_id": "3f2504e0-4f89-11d3-9a0c-0305e82c3301",
            "condition_params": {
              "timeOnSite": "30"
            }
          }
        ]
      }
    ]
  }'

Responses

Successful response

Bodyapplication/json

clientKeystring(Clientkey)

The client key associated with the flow definition (A/B/n test or personalization).

Example:"pers12345"

hrefstring or null(Href)

Example:"https://www.example.com/flow-definition"

Any of:

The URL of the flow definition (A/B/n test or personalization).

string

refstring(Ref)

A reference identifier for the flow definition (A/B/n test or personalization).

Example:"FlowDefinition-12345"

namestring(Name)

The name of the flow definition (A/B/n test or personalization).

Example:"User Registration Flow"

modifiedByRefstring or null(Modifiedbyref)

Example:"User-67890"

Any of:

A reference identifier for the user who last modified the flow definition (A/B/n test or personalization).

string

modifiedAtstring or null(Modifiedat)

Example:"2025-01-15T10:30:00Z"

Any of:

The timestamp when the flow definition was last modified (A/B/n test or personalization).

string

revisioninteger or null(Revision)

Example:2

Any of:

The revision number of the flow definition (A/B/n test or personalization).

integer

archivedboolean(Archived)

Whether the flow definition (A/B/n test or personalization) is archived.

Example:false

friendlyIdstring(Friendlyid)

A user-friendly identifier for the flow definition (A/B/n test or personalization).

Example:"user_registration_flow"

typestring(Type)

The type of the flow definition (A/B/n test or personalization).

Example:"EMBEDDED"

channelsArray of strings or null(Channels)

Any of:

A list of channels associated with the flow definition (A/B/n test or personalization), such as web or mobile.

Array of strings

triggersArray of any or null(Triggers)

Any of:

A list of triggers for the flow definition (A/B/n test or personalization), or null if none.

Array of any

tagsArray of any or null(Tags)

Any of:

A list of tags associated with the flow definition (A/B/n test or personalization), or null if none.

Array of any

businessProcessstring or null(Businessprocess)

Example:"user_registration"

Any of:

The business process associated with the flow definition (A/B/n test or personalization).

string

siteIdstring(Siteid)

The unique identifier of the site associated with A/B/n test or personalization.

Example:"site_123"

transpiledVariantsArray of any or null(Transpiledvariants)

Any of:

A list of transpiled variants for the flow definition (A/B/n test or personalization), or null if none. variantId is typically in transpiledVariants[].tasks[].input.template as serialized JSON.

Array of any

variantsArray of any or null(Variants)

Any of:

A list of variants for the flow definition (A/B/n test or personalization), or null if none.

Array of any

statusstring(Status)

The current status of the flow definition (A/B/n test or personalization).

Example:"DRAFT"

scheduleFlowDefinitionSchedule (object) or null

Any of:

The schedule configuration for the flow definition (A/B/n test or personalization).

revisionsFlowDefinitionRevisions (object) or null

Any of:

Links to the revisions of the flow definition.

sampleSizeConfigFlowDefinitionSampleSizeConfigV2 (object) or null

Any of:

The sample size configuration for the flow definition.

notificationEnabledboolean or null(Notificationenabled)

Any of:

Whether notifications are enabled for the flow definition (A/B/n test or personalization).

boolean

subtypestring(Subtype)

The subtype of the flow definition (A/B/n test or personalization), identifying it as a personalization experience.

Example:"EXPERIENCE"

Value:"EXPERIENCE"

trafficobject(ExperienceTrafficV2)

The traffic distribution configuration for the personalization experience.

dashboardLinksArray of any or null(Dashboardlinks)

Any of:

A list of dashboard links for the experience, or null if none.

Array of any

Response

{
  "clientKey": "pers12345",
  "href": "https://www.example.com/flow-definition",
  "ref": "FlowDefinition-12345",
  "name": "User Registration Flow",
  "modifiedByRef": "User-67890",
  "modifiedAt": "2025-01-15T10:30:00Z",
  "revision": 2,
  "archived": false,
  "friendlyId": "user_registration_flow",
  "type": "EMBEDDED",
  "channels": [
    "string"
  ],
  "triggers": [
    null
  ],
  "tags": [
    null
  ],
  "businessProcess": "user_registration",
  "siteId": "site_123",
  "transpiledVariants": [
    { … }
  ],
  "variants": [],
  "status": "DRAFT",
  "schedule": {
    "type": "simpleSchedule",
    "startDate": "2023-01-01T00:00:00Z"
  },
  "revisions": {
    "href": "https://www.example.com/flow-definition/revisions"
  },
  "sampleSizeConfig": {
    "baseValue": 0.5,
    "minimumDetectableDifference": 0.1,
    "confidenceLevel": 0.95,
    "sampleSize": 0
  },
  "notificationEnabled": true,
  "subtype": "EXPERIENCE",
  "traffic": {
    "type": "audienceTraffic",
    "weightingAlgorithm": "USER_DEFINED",
    "modifiedAt": "2023-01-01T00:00:00Z",
    "splits": [ … ]
  },
  "dashboardLinks": [
    null
  ]
}