Sitecore API catalog/Agent API/Experiments

Experiments

The Experiments API lets create A/B/n tests on components on a page and update an existing experiment.

Operations

Create an A/B/n test on a component

Request

Creates a new A/B/n test for a specific component on a page. This allows you to compare two or more variants of the component and determine which one performs better.

Security
HTTPBearer
Headers
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
site_idstring(Site Id)required

The unique identifier of the site.

Example:"site_123"
page_idstring(Page Id)required

The unique identifier of the page that includes the component to A/B/n test.

Example:"3f2504e0-4f89-11d3-9a0c-0305e82c3301"
component_idstring(Component Id)required

The unique identifier of the component to A/B/n test.

Example:"d290f1ee-6c54-4b01-90e6-d701748f0851"
namestring(Name)required

The name of the A/B/n test.

Example:"Hero Banner Experiment"
goal_typestring(GoalType)required

How the A/B/n test evaluates the performance of its variants:

  • pageViewGoal - measures the number of page views.
  • bouncersGoal - measures the number of bounces.
  • exitsGoal - measures the number of exits.
Enum:"pageViewGoal""bouncesGoal""exitsGoal"
variantsArray of objects(Variants)required

A list of variants to use for the A/B/n test. Traffic splits must sum to 100 and exactly one variant must be marked as control.

languagestring or null(Language)
Example:"en"
Any of:

The language code for the A/B/n test.

string
targeted_pagesArray of strings(Targeted Pages)

A list of page paths where you want to track the A/B/n test goal.

Example:
[]
curl -i -X POST \
  https://edge-platform.sitecorecloud.io/stream/ai-agent-api/api/v1/experiments/flows \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>' \
  -H 'Content-Type: application/json' \
  -H 'x-sc-job-id: job-1234' \
  -d '{
    "site_id": "site_123",
    "page_id": "3f2504e0-4f89-11d3-9a0c-0305e82c3301",
    "language": "en",
    "component_id": "d290f1ee-6c54-4b01-90e6-d701748f0851",
    "name": "Hero Banner Experiment",
    "goal_type": "pageViewGoal",
    "targeted_pages": [],
    "variants": [
      {
        "name": "Variant A",
        "is_control": false,
        "traffic_split": 50
      }
    ]
  }'

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 (A/B/n test or personalization) was last modified.

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:"COMPONENT"
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 the 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.

Array of any
variantsArray of objects or null(Variants)
Any of:

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

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 (A/B/n test or personalization).

sampleSizeConfigFlowDefinitionSampleSizeConfigV2 (object) or null
Any of:

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

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 an A/B experiment.

Example:"EXPERIMENT"
Value:"EXPERIMENT"
trafficobject(ExperimentTraffic)

The traffic distribution configuration for the A/B/n test.

goalsExperimentGoalModel (object) or null
Any of:

The goals tracked for the experiment, keyed by goal identifier.

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": "COMPONENT",
  "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": "EXPERIMENT",
  "traffic": {
    "type": "simpleTraffic",
    "weightingAlgorithm": "USER_DEFINED",
    "modifiedAt": "2023-01-01T00:00:00Z",
    "allocation": 100,
    "coupled": false,
    "splits": [ … ]
  },
  "goals": {
    "property1": { … },
    "property2": { … }
  }
}