---
title: "Experiences"
description: "<p>Experiences help you create different variations of content pages that cater to different sections of your audience. Experiences are also versioned, so that you can make draft changes on an active version of an experience. The following requests allow you to manage the Segmented and A/B Test Experiences within a project.</p>"
url: "https://www.contentstack.com/docs/developers/apis/personalize-management-api/experiences"
product: "Contentstack"
doc_type: "guide"
audience:
  - developers
  - admins
version: "current"
last_updated: "2026-04-24"
---

# Experiences

Experiences help you create different variations of content pages that cater to different sections of your audience. Experiences are also versioned, so that you can make draft changes on an active version of an experience. The following requests allow you to manage the Segmented and A/B Test Experiences within a project.

## Create an Experience

### Create an Experience

**POST** `/experiences`

The Create an Experience request lets you create a new experience in a project. An experience can be either of SEGMENTED or AB\_TEST type. Creating an experience also creates an empty draft version for the configuration.

To configure the permissions for your application via OAuth, include the personalize:manage scope.  
  

##### Create a Segmented Experience:

```
{
  "name": "Australian Users Experience",
  "description": "This is the experience for Australian users.",
  "__type": "SEGMENTED"
}
```

In this example, we create a Segmented Experience. The \_\_type field is used to set the type of the experience. Note that the experience in the response has a latestVersion field pointing to the draft version configuration created along with the experience.

#### Headers

- **authorization** (optional)
  Enter your OAuth token here. Read more: https://www.contentstack.com/docs/developers/developer-hub/contentstack-oauth
- **authtoken** (optional)
  Enter your authtoken here. Read more: https://www.contentstack.com/docs/developers/create-tokens/types-of-tokens#authentication-tokens-authtokens
- **x-project-uid** (required)

#### Sample Response

```json
{
  "shortUid": "1",
  "name": "CTA color test",
  "description": "Test if using a warmer color on the CTA improves conversions",
  "__type": "AB_TEST",
  "tags": [
    "campaign:black-friday",
    "section:homepage"
  ],
  "project": "6887777b3335554698867847",
  "status": "DRAFT",
  "createdBy": "bxxxxxxxxxxxx3",
  "updatedBy": "bxxxxxxxxxxxx6",
  "referredAudiences": [],
  "referredEvents": [],
  "createdAt": "2024-03-13T15:39:51.645Z",
  "updatedAt": "2024-03-13T15:39:51.645Z",
  "uid": "6887777xxxxxxxxx98867841",
  "hasDraft": true,
  "latestVersion": "66d5ad0000000001412ae841",
  "createdByUserName": "Jane Doe",
  "updatedByUserName": "Jane Doe"
}
```

## Get all Experiences

### Get all Experiences

**GET** `/experiences`

The Get all Experiences request fetches the list of all the experiences in a project.

To configure the permissions for your application via OAuth, include the personalize:read or personalize:manage scope.

#### Query Parameters

- **tags[]** (optional)
  Filter experiences by passing a list of tags. Experiences matching at least one of the provided tags are returned (OR semantics).
- **referredEvents[]** (optional)
  Filter experiences by passing a list of event UIDs. The experiences referring to the given events as metrics will be returned.
- **referredAudiences[]** (optional)
  Filter experiences by passing a list of audience UIDs. The experiences referring to the given audiences in its variants (for segmented experiences) or targeting criteria (for A/B test experiences) will be returned.

#### Headers

- **authorization** (optional)
  Enter your OAuth token here. Read more: https://www.contentstack.com/docs/developers/developer-hub/contentstack-oauth
- **authtoken** (optional)
  Enter your authtoken here. Read more: https://www.contentstack.com/docs/developers/create-tokens/types-of-tokens#authentication-tokens-authtokens
- **x-project-uid** (required)

#### Sample Response

```json
[
  {
    "shortUid": "1",
    "name": "CTA color",
    "description": "Use a warmer color on the CTA to improve conversion",
    "__type": "AB_TEST",
    "tags": [
      "campaign:black-friday",
      "section:homepage"
    ],
    "project": "6887777b3335554698867847",
    "status": "DRAFT",
    "createdBy": "bxxxxxxxxxxxx3",
    "updatedBy": "bxxxxxxxxxxxx6",
    "referredAudiences": [],
    "referredEvents": [],
    "createdAt": "2024-03-13T15:39:51.645Z",
    "updatedAt": "2024-03-14T17:00:00.000Z",
    "uid": "6887777xxxxxxxxx98867841",
    "hasDraft": true,
    "latestVersion": "66d5ad0000000001412ae841",
    "createdByUserName": "Jane Doe",
    "updatedByUserName": "Jane Doe"
  }
]
```

## Update an Experience

### Update an Experience

**PUT** `/experiences/{uid}`

The Update an Experience request lets you update an existing experience in a project. Note that once an experience of a particular type has been created, the type cannot be changed with this request.

To configure the permissions for your application via OAuth, include the personalize:manage scope.

#### URL Parameters

- **uid** (required)
  Enter the Experience UID to be updated.

#### Headers

- **authorization** (optional)
  Enter your OAuth token here. Read more: https://www.contentstack.com/docs/developers/developer-hub/contentstack-oauth
- **authtoken** (optional)
  Enter your authtoken here. Read more: https://www.contentstack.com/docs/developers/create-tokens/types-of-tokens#authentication-tokens-authtokens
- **x-project-uid** (required)

#### Sample Response

```json
{
  "shortUid": "1",
  "name": "CTA color",
  "description": "Use a warmer color on the CTA to improve conversion",
  "__type": "AB_TEST",
  "tags": [
    "campaign:black-friday",
    "section:homepage"
  ],
  "project": "6887777b3335554698867847",
  "status": "DRAFT",
  "createdBy": "bxxxxxxxxxxxx3",
  "updatedBy": "bxxxxxxxxxxxx6",
  "referredAudiences": [],
  "referredEvents": [],
  "createdAt": "2024-03-13T15:39:51.645Z",
  "updatedAt": "2024-03-14T17:00:00.000Z",
  "uid": "6887777xxxxxxxxx98867841",
  "hasDraft": true,
  "latestVersion": "66d5ad0000000001412ae841",
  "createdByUserName": "Jane Doe",
  "updatedByUserName": "Jane Doe"
}
```

## Get a Single Experience

### Get a Single Experience

**GET** `/experiences/{uid}`

The Get a Single Experience request fetches a specific experience created in your project.

To configure the permissions for your application via OAuth, include the personalize:read scope.

#### URL Parameters

- **uid** (required)
  Enter the Experience UID to be retrieved

#### Headers

- **authorization** (optional)
  Enter your OAuth token here. Read more: https://www.contentstack.com/docs/developers/developer-hub/contentstack-oauth
- **authtoken** (optional)
  Enter your authtoken here. Read more: https://www.contentstack.com/docs/developers/create-tokens/types-of-tokens#authentication-tokens-authtokens
- **x-project-uid** (required)

#### Sample Response

```json
{
  "shortUid": "1",
  "name": "CTA color",
  "description": "Use a warmer color on the CTA to improve conversion",
  "__type": "AB_TEST",
  "tags": [
    "campaign:black-friday",
    "section:homepage"
  ],
  "project": "6887777b3335554698867847",
  "status": "DRAFT",
  "createdBy": "bxxxxxxxxxxxx3",
  "updatedBy": "bxxxxxxxxxxxx6",
  "referredAudiences": [],
  "referredEvents": [],
  "createdAt": "2024-03-13T15:39:51.645Z",
  "updatedAt": "2024-03-14T17:00:00.000Z",
  "uid": "6887777xxxxxxxxx98867841",
  "hasDraft": true,
  "latestVersion": "66d5ad0000000001412ae841",
  "createdByUserName": "Jane Doe",
  "updatedByUserName": "Jane Doe"
}
```

## Delete an Experience

### Delete an Experience

**DELETE** `/experiences/{uid}`

The Delete an Experience request lets you delete an existing experience in a project.

To configure the permissions for your application via OAuth, include the personalize:manage scope.

#### URL Parameters

- **uid** (required)
  Enter the Experience UID to be deleted

#### Headers

- **authorization** (optional)
  Enter your OAuth token here. Read more: https://www.contentstack.com/docs/developers/developer-hub/contentstack-oauth
- **authtoken** (optional)
  Enter your authtoken here. Read more: https://www.contentstack.com/docs/developers/create-tokens/types-of-tokens#authentication-tokens-authtokens
- **x-project-uid** (required)

#### Sample Response

```json
The experience was deleted successfully
```

## Create an Experience Version

### Create an Experience Version

**POST** `/experiences/{uid}/versions`

The Create an Experience Version request lets you create a new version of an experience in a project.

Creating a new version allows you to modify the configuration of an existing active version. A version can be created with a DRAFT or ACTIVE status. A new version cannot be created if a DRAFT version already exists, in which case you can only modify the existing DRAFT version.

To configure the permissions for your application via OAuth, include the personalize:manage scope.  
  

##### Create a Segmented Experience version:

```
{
  "status": "DRAFT",
  "variants": [
    {
      "__type": "SegmentedVariant",
      "name": "Australian Continent Visitors",
      "shortUid": "0",
      "audiences": [
        "388888800000000087654321",
        "399999900000000044444444"
      ],
      "audienceCombinationType": "OR"
    }
  ]
}
```

In this example, we create a new DRAFT version of our segmented experience. We want to target the entire Australian continent instead of just the country, and accordingly, we also target one more audience in the variant and change the audienceCombinationType. The short UID refers to the existing variant's short UID so that we can update it.  
  

##### Create an active version:

```
{
  "status": "ACTIVE",
  "variants": [
    {
      "__type": "ABTestVariant",
      "name": "Control",
      "shortUid": "0",
      "trafficDistribution": 33.33
    },
    {
      "__type": "ABTestVariant",
      "name": "Purple",
      "shortUid": "1",
      "trafficDistribution": 33.33
    },
    {
      "__type": "ABTestVariant",
      "name": "Red",
      "trafficDistribution": 33.33
    }
  ],
  "variantSplit": "EQUALLY_SPLIT",
  "metrics": [
    {
      "__type": "Primary",
      "event": "244444400000000087654321",
      "name": "Click on CTA"
    }
  ],
  "targeting": {
    "audience": {
      "audiences": [
        "155555500000000012345678"
      ],
      "audienceCombinationType": "AND"
    }
  }
}
```

The example here is the same A/B test, however, instead of creating a DRAFT version, we're activating the version instantly. The changes in the version are instantly reflected and the existing version is ARCHIVED.

#### URL Parameters

- **uid** (required)
  Enter the Experience UID to version

#### Headers

- **authorization** (optional)
  Enter your OAuth token here. Read more: https://www.contentstack.com/docs/developers/developer-hub/contentstack-oauth
- **authtoken** (optional)
  Enter your authtoken here. Read more: https://www.contentstack.com/docs/developers/create-tokens/types-of-tokens#authentication-tokens-authtokens
- **x-project-uid** (required)

#### Sample Response

```json
{
  "uid": "9888888xxxxxxxxx89102123",
  "experienceUid": "688777700000000098867841",
  "__type": "AB_TEST",
  "variants": [
    {
      "__type": "ABTestVariant",
      "name": "Control",
      "shortUid": "0",
      "trafficDistribution": 33.33
    },
    {
      "__type": "ABTestVariant",
      "name": "Purple",
      "shortUid": "1",
      "trafficDistribution": 33.33
    },
    {
      "__type": "ABTestVariant",
      "name": "Red",
      "trafficDistribution": 33.33,
      "shortUid": "2"
    }
  ],
  "variantSplit": "EQUALLY_SPLIT",
  "metrics": [
    {
      "__type": "Primary",
      "event": "244444400000000087654321",
      "name": "Click on CTA"
    }
  ],
  "targeting": {
    "audience": {
      "audiences": [
        "155555500000000012345678"
      ],
      "audienceCombinationType": "AND"
    }
  },
  "status": "DRAFT",
  "createdAt": "2024-03-15T15:39:51.645Z",
  "updatedAt": "2024-03-15T15:39:51.645Z",
  "createdBy": "bxxxxxxxxxxxx3",
  "updatedBy": "bxxxxxxxxxxxx3",
  "createdByUserName": "Jane Doe",
  "updatedByUserName": "Jane Doe"
}
```

## Get all Experience Versions

### Get all Experience Versions

**GET** `/experiences/{uid}/versions`

The Get all Experience Versions request fetches the list of all the versions for a given Experience.

The list of versions is sorted by the createdAt date.

To configure the permissions for your application via OAuth, include the personalize:read or personalize:manage scope.

#### URL Parameters

- **uid** (required)
  Enter the Experience UID to version

#### Headers

- **authorization** (optional)
  Enter your OAuth token here. Read more: https://www.contentstack.com/docs/developers/developer-hub/contentstack-oauth
- **authtoken** (optional)
  Enter your authtoken here. Read more: https://www.contentstack.com/docs/developers/create-tokens/types-of-tokens#authentication-tokens-authtokens
- **x-project-uid** (required)

#### Sample Response

```json
[
  {
    "uid": "9888888xxxxxxxxx89102123",
    "experienceUid": "688777700000000098867841",
    "__type": "AB_TEST",
    "variants": [
      {
        "__type": "ABTestVariant",
        "name": "Control",
        "shortUid": "0",
        "trafficDistribution": 33.33
      },
      {
        "__type": "ABTestVariant",
        "name": "Purple",
        "shortUid": "1",
        "trafficDistribution": 33.33
      },
      {
        "__type": "ABTestVariant",
        "name": "Red",
        "trafficDistribution": 33.33,
        "shortUid": "2"
      }
    ],
    "variantSplit": "EQUALLY_SPLIT",
    "metrics": [
      {
        "__type": "Primary",
        "event": "244444400000000087654321",
        "name": "Click on CTA"
      }
    ],
    "targeting": {
      "audience": {
        "audiences": [
          "155555500000000012345678"
        ],
        "audienceCombinationType": "AND"
      }
    },
    "status": "DRAFT",
    "createdAt": "2024-03-15T15:39:51.645Z",
    "updatedAt": "2024-03-15T15:39:51.645Z",
    "createdBy": "bxxxxxxxxxxxx3",
    "updatedBy": "bxxxxxxxxxxxx3",
    "createdByUserName": "Jane Doe",
    "updatedByUserName": "Jane Doe"
  }
]
```

## Update an Experience Version

### Update an Experience Version

**PUT** `/experiences/{uid}/versions/{versionUid}`

The Update an Experience Version request lets you update an existing version of an Experience. After creating an Experience initially, an empty draft version is already created, and you can update it to modify the configuration of the Experience. Once the configuration is ready, you can activate the version by updating the status to ACTIVE. Any existing active version's status will change to ARCHIVED. You can also PAUSE an active version with this request.

To configure the permissions for your application via OAuth, include the personalize:manage scope.  
  

##### Update a Segmented Experience version:

```
{
  "status": "DRAFT",
  "variants": [
    {
      "__type": "SegmentedVariant",
      "name": "Australian Visitors",
      "audiences": [
        "388888800000000087654321"
      ],
      "audienceCombinationType": "AND"
    }
  ]
}
```

In this example, we update the configuration for the Segmented Experience created previously. We're creating a variant for the visitors from Australia, with the variant targeted to the Australian audience. Notice that the shortUid is skipped for the new variant as it will be generated on the server side.  
  

##### Activate a version:

```
{
  "status": "ACTIVE",
  "variants": [
    {
      "__type": "ABTestVariant",
      "name": "Control",
      "trafficDistribution": 50
    },
    {
      "__type": "ABTestVariant",
      "name": "Purple",
      "trafficDistribution": 50
    }
  ],
  "variantSplit": "EQUALLY_SPLIT",
  "metrics": [
    {
      "__type": "Primary",
      "event": "244444400000000087654321",
      "name": "Click on CTA"
    }
  ]
}
```

Activating a version is done by updating the status to ACTIVE. Any existing active version will be ARCHIVED following the activation of a new version.  
  

##### Pause a version:

```
{
  "status": "PAUSED",
  "variants": [
    {
      "__type": "ABTestVariant",
      "name": "Control",
      "trafficDistribution": 50
    },
    {
      "__type": "ABTestVariant",
      "name": "Purple",
      "trafficDistribution": 50
    }
  ],
  "variantSplit": "EQUALLY_SPLIT",
  "metrics": [
    {
      "__type": "Primary",
      "event": "244444400000000087654321",
      "name": "Click on CTA"
    }
  ]
}
```

Pausing a version is achieved by updating the status to PAUSED. Once paused, the experience does not match any variants and will return null in the Manifest API. You can also re-activate the version again by updating it with the ACTIVE status.

#### URL Parameters

- **versionUid** (required)
  Enter the Experience Version UID
- **uid** (required)
  Enter the Experience UID to version

#### Headers

- **authorization** (optional)
  Enter your OAuth token here. Read more: https://www.contentstack.com/docs/developers/developer-hub/contentstack-oauth
- **authtoken** (optional)
  Enter your authtoken here. Read more: https://www.contentstack.com/docs/developers/create-tokens/types-of-tokens#authentication-tokens-authtokens
- **x-project-uid** (required)

#### Sample Response

```json
{
  "uid": "9888888xxxxxxxxx89102123",
  "experienceUid": "688777700000000098867841",
  "__type": "AB_TEST",
  "variants": [
    {
      "__type": "ABTestVariant",
      "name": "Control",
      "trafficDistribution": 50,
      "shortUid": "0"
    },
    {
      "__type": "ABTestVariant",
      "name": "Purple",
      "trafficDistribution": 50,
      "shortUid": "1"
    }
  ],
  "variantSplit": "EQUALLY_SPLIT",
  "metrics": [
    {
      "__type": "Primary",
      "event": "244444400000000087654321",
      "name": "Click on CTA"
    }
  ],
  "status": "DRAFT",
  "createdAt": "2024-03-13T15:39:51.645Z",
  "updatedAt": "2024-03-14T15:39:51.645Z",
  "createdBy": "bxxxxxxxxxxxx3",
  "updatedBy": "bxxxxxxxxxxxx3",
  "createdByUserName": "Jane Doe",
  "updatedByUserName": "Jane Doe"
}
```

## Delete an Experience Version

### Delete an Experience Version

**DELETE** `/experiences/{uid}/versions/{versionUid}`

The Delete an Experience Version request lets you discard the draft version of an Experience. Attempting to delete an ACTIVE, PAUSED or ARCHIVED version will return an error.

To configure the permissions for your application via OAuth, include the personalize:manage scope.

#### URL Parameters

- **versionUid** (required)
  Enter the Experience Version UID
- **uid** (required)
  Enter the Experience UID to version

#### Headers

- **authorization** (optional)
  Enter your OAuth token here. Read more: https://www.contentstack.com/docs/developers/developer-hub/contentstack-oauth
- **authtoken** (optional)
  Enter your authtoken here. Read more: https://www.contentstack.com/docs/developers/create-tokens/types-of-tokens#authentication-tokens-authtokens
- **x-project-uid** (required)

#### Sample Response

```json
The Experience Version was deleted successfully
```