End-to-end guide for creating Contentstack Personalize experiences (Segmented and A/B Test) via the Management API. Covers audience creation, experience version configuration, variant-to-audience mapping, variant group linkage, entry variant content creation, publishing, and activation. Use when setting up Personalize experiences, connecting CDP audiences to Contentstack content variants, or automating experience configuration that the MCP tools cannot handle alone.
Two separate APIs are involved, each with its own auth:
| API | Base URL | Auth Header |
|---|---|---|
| Personalize Management | https://personalize-api.contentstack.com | authtoken: <user_authtoken> + x-project-uid: <project_uid> |
| CMA (Content Management) | https://api.contentstack.io/v3 | authorization: <management_token> + api_key: <stack_api_key> |
The Personalize API does not accept management tokens. You need a user authtoken (from POST /v3/user-session with email/password) or an OAuth token with personalize:manage scope.
Regional base URLs exist for both APIs (EU, Azure, GCP, AU). See docs.
1. Create audiences Personalize API POST /audiences
2. Create experience Personalize API POST /experiences
3. Configure version Personalize API PUT /experiences/{uid}/versions/{versionUid}
(add variants + map audiences)
4. Link variant group to CT CMA API PUT /v3/variant_groups/{group_uid}
5. Create entry variants CMA API PUT /v3/content_types/{ct}/entries/{entry}/variants/{variant_uid}
6. Publish variants CMA API POST /v3/bulk/publish
7. Activate experience Personalize API PUT /experiences/{uid}/versions/{versionUid} (status: ACTIVE)
8. Set priority Personalize API PUT /experiences-priority
Steps 1-3 use the Personalize Management API. Steps 4-6 use the CMA. Steps 7-8 return to the Personalize API.
| Action | API | Endpoint |
|---|---|---|
| Create/list/delete audiences | Personalize | POST/GET/DELETE /audiences |
| Create/list/delete experiences | Personalize | POST/GET/DELETE /experiences |
| Configure version (variants + audiences) | Personalize | PUT /experiences/{uid}/versions/{versionUid} |
| Link variant group to content type | CMA | PUT /v3/variant_groups/{uid} |
| Create entry variant content | CMA | PUT /v3/content_types/{ct}/entries/{entry}/variants/{variant_uid} |
| Bulk publish variants | CMA | POST /v3/bulk/publish |
| Activate/pause experience | Personalize | PUT /experiences/{uid}/versions/{versionUid} with status |
| Set experience priority | Personalize | PUT /experiences-priority |
| Create events/attributes | Personalize | POST /events, POST /attributes |
The Contentstack MCP (@contentstack/mcp) exposes create_experience, get_all_experiences, and update_experience, but these are metadata-only (name, description, type). The MCP does not expose:
Use the REST APIs directly (via curl) for these operations.
Lytics-synced audiences have 32-char hex UIDs that the audiences field rejects ("not a valid ObjectId"). Use lyticsAudiences instead:
{
"__type": "SegmentedVariant",
"name": "My Variant",
"audiences": [],
"lyticsAudiences": ["<32-char-lytics-uid>"],
"audienceCombinationType": "OR"
}
The experience response also separates them: referredLyticsAudiences vs referredAudiences.
Audiences must exist → before experience version can reference them
Experience must exist → before version can be configured
Version must have variants → before CMS syncs variant group + variant UIDs
Variant group must be linked → before entry variants can be created for that CT
to the content type
Entry variants must exist → before they can be published
Variants should be published → before activating the experience
After step 3 (configuring the version), Personalize auto-syncs a variant group and variant UIDs to the CMS. Read the experience via GET /experiences/{uid} to find:
_cms.variantGroup — the variant group UID_cms.variants — map of shortUid → variantUid (e.g., {"0": "csXXX", "1": "csYYY"})POST /audiences
x-project-uid: <project_uid>