> ## Documentation Index
> Fetch the complete documentation index at: https://docs.kameleoon.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Create a multivariate experiment
> Create a multivariate test (MVT) experiment and set custom traffic allocation using the Automation API.
## Goal
Create a multivariate test (MVT) experiment with multiple sections and variations, then set custom (non-equal) traffic allocation across those variations.
When you create an MVT experiment with `POST /experiments`, Kameleoon always applies equal traffic allocation to every variation and resets any submitted `locked` value to `false`, regardless of the values you submit in `mvtAllocationSettings`. To set custom traffic allocation, follow the three-step flow in this tutorial: create the experiment, retrieve the generated IDs, then update the allocation with a `PATCH` request.
For an overview of MVT concepts (sections, variations, and combinations) and how to configure traffic allocation in the Kameleoon app, read [Set up multivariate tests](/user-manual/experimentation/web-experimentation/advanced-experiment-types/setting-up-multivariate-tests).
## Requirements
* `access token`
The Automation API requires an access token.
Retrieve the token programmatically by following the instructions in the [obtaining an access token section](/developer-docs/apis/automation-api-rest/get-started/get-started#1-obtain-an-access-token).
* `siteId`
Retrieve the `siteId` directly in code with the `siteCode` by calling [the get a site by code endpoint](/api-reference/site/get-a-site-by-code), or find it in the app by following the steps in [Create a new experiment](/developer-docs/apis/automation-api-rest/tutorials/experiments/create-a-new-experiment#requirements).
## Key concepts
### The reference variation
Kameleoon automatically adds one reference variation to each section you submit. The reference appears in the response as `variationId: "0"` within that section's allocation entries.
If you submit your own variation named `Original`, Kameleoon creates it as a separate, additional variation. It doesn't identify or replace the generated reference. Only submit an explicit `Original` variation if you intend to test two distinct baseline variations in the same section.
### Client-submitted IDs are temporary
The `sectionId` and variation `id` values you submit in `mvtVariations` only link entries within that single request: they connect each `mvtAllocationSettings` allocation entry to the correct section and variation before Kameleoon generates permanent IDs. Use any integers that are convenient for you.
Kameleoon discards the submitted values and replaces them with its own generated `sectionId` and `variationId` values. Use the generated values (returned in the response and by a later `GET` request) for every subsequent request. The response doesn't include the variation names you submitted, only the generated IDs. If you need to confirm which generated ID corresponds to which submitted name, check the experiment in the Kameleoon app.
### Section IDs versus combination IDs
Kameleoon generates two distinct sets of IDs for an MVT experiment:
* **Section and variation IDs** identify one variation within one section. Use these in `mvtAllocationSettings.sectionsAllocations`.
* **Combination IDs** identify one full combination of variations, one per section, shown to exposed visitors. Kameleoon generates every possible combination as the Cartesian product of all sections' variations (including the reference in each section) and returns the combination IDs in the top-level `variations` array and as keys in the `deviations` map. Use these in `mvtAllocationSettings.combinationsAllocations`.
Both `sectionsAllocations` and `combinationsAllocations` use the same allocation item structure (`allocationPart`, `checked`, `locked`, `sectionId`, `variationId`), so choose only one method:
* Populate `sectionsAllocations` to allocate traffic by individual variation within each section. Kameleoon derives each combination's share from the section-level values.
* Populate `combinationsAllocations` to allocate traffic directly to specific combinations.
Because combination IDs don't exist until Kameleoon generates them, you can't populate `combinationsAllocations` in the creation request. Retrieve the generated combination IDs with a `GET` request, then set `combinationsAllocations` in a follow-up `PATCH` request, following the same pattern used for `sectionsAllocations` in this tutorial.
## Steps
### 1. Create the experiment
**Endpoint:**
```
POST https://api.kameleoon.com/experiments
```
| Name | Type | Description |
| ------------------------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
| `baseURL` | String | URL of the page to load in the graphic editor. |
| `name` | String | Experiment name. |
| `siteId` | Integer | The project's `siteId`. |
| `type` | String | Set to `MVT` for a multivariate test. |
| `mvtVariations` | Array | The sections and variations to create. Each entry needs a temporary `sectionId`, a `sectionName`, and a `variations` array of `{id, name}` objects. |
| `mvtAllocationSettings` | Object | Traffic allocation settings. Kameleoon accepts this object on creation but always applies equal allocation, regardless of the values you submit here. |
| `trafficAllocationMethod` | String | Set to `MANUAL` to control traffic allocation yourself instead of using an automated method. |
**Example:**
```bash theme={null}
curl -L -X POST 'https://api.kameleoon.com/experiments' \
-H 'Content-Type: application/json' \
-H 'Accept: */*' \
-H 'Authorization: Bearer ' \
--data-raw '{
"baseURL": "https://test-site.fr/",
"name": "MVT_1",
"siteId": 29353,
"type": "MVT",
"trafficAllocationMethod": "MANUAL",
"mvtVariations": [
{
"sectionId": 1,
"sectionName": "Button color",
"variations": [
{"id": 1, "name": "Red"},
{"id": 2, "name": "Blue"}
]
},
{
"sectionId": 2,
"sectionName": "Button wording",
"variations": [
{"id": 1, "name": "Buy now"},
{"id": 2, "name": "Shop now"}
]
}
],
"mvtAllocationSettings": {
"exposedPart": 0.8,
"sectionsAllocations": [
{"allocationPart": 0.6, "checked": true, "locked": true, "sectionId": 1, "variationId": "0"},
{"allocationPart": 0.25, "checked": true, "locked": true, "sectionId": 1, "variationId": "1"},
{"allocationPart": 0.15, "checked": true, "locked": true, "sectionId": 1, "variationId": "2"},
{"allocationPart": 0.5, "checked": true, "locked": true, "sectionId": 2, "variationId": "0"},
{"allocationPart": 0.3, "checked": true, "locked": true, "sectionId": 2, "variationId": "1"},
{"allocationPart": 0.2, "checked": true, "locked": true, "sectionId": 2, "variationId": "2"}
],
"combinationsAllocations": []
}
}'
```
**Response (abridged):**
```json theme={null}
{
"id": 404811,
"siteId": 29353,
"name": "MVT_1",
"type": "MVT",
"status": "draft",
"trafficAllocationMethod": "MANUAL",
"variations": [1351297, 1351298, 1351299, 1351300, 1351301, 1351302, 1351303, 1351304, 1351305],
"mvtAllocationSettings": {
"exposedPart": 0.8,
"sectionsAllocations": [
{"variationId": "1351294", "sectionId": 4451, "allocationPart": 0.33333334, "locked": false, "checked": true},
{"variationId": "1351293", "sectionId": 4451, "allocationPart": 0.33333334, "locked": false, "checked": true},
{"variationId": "0", "sectionId": 4451, "allocationPart": 0.33333334, "locked": false, "checked": true},
{"variationId": "1351296", "sectionId": 4452, "allocationPart": 0.33333334, "locked": false, "checked": true},
{"variationId": "1351295", "sectionId": 4452, "allocationPart": 0.33333334, "locked": false, "checked": true},
{"variationId": "0", "sectionId": 4452, "allocationPart": 0.33333334, "locked": false, "checked": true}
],
"combinationsAllocations": []
}
}
```
Notice that Kameleoon generated new `sectionId` and `variationId` values (`4451`, `4452`, `1351293`-`1351296`), added a reference variation (`variationId: "0"`) to each section, and replaced the submitted allocation with an equal `0.33333334` share, resetting `locked` to `false`. Kameleoon preserves `exposedPart` as submitted. Continue to the next step to set the allocation you want.
### 2. Retrieve the generated IDs
If you didn't capture the generated IDs from the create response, retrieve them with a `GET` request.
**Endpoint:**
```
GET https://api.kameleoon.com/experiments/{experimentId}
```
**Example:**
```bash theme={null}
curl -L -X GET 'https://api.kameleoon.com/experiments/404811' \
-H 'Authorization: Bearer '
```
The response contains the same `mvtAllocationSettings.sectionsAllocations` array shown in step 1, with the generated `sectionId` and `variationId` values you need for the next step.
### 3. Set custom traffic allocation
**Endpoint:**
```
PATCH https://api.kameleoon.com/experiments/{experimentId}
```
Submit `mvtAllocationSettings` again, this time using the generated `sectionId` and `variationId` values from step 2.
**Example:**
```bash theme={null}
curl -L -X PATCH 'https://api.kameleoon.com/experiments/404811' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer ' \
--data-raw '{
"trafficAllocationMethod": "MANUAL",
"mvtAllocationSettings": {
"exposedPart": 0.8,
"sectionsAllocations": [
{"allocationPart": 0.6, "checked": true, "locked": true, "sectionId": 4451, "variationId": "1351294"},
{"allocationPart": 0.25, "checked": true, "locked": true, "sectionId": 4451, "variationId": "1351293"},
{"allocationPart": 0.15, "checked": true, "locked": true, "sectionId": 4451, "variationId": "0"},
{"allocationPart": 0.5, "checked": true, "locked": true, "sectionId": 4452, "variationId": "1351296"},
{"allocationPart": 0.3, "checked": true, "locked": true, "sectionId": 4452, "variationId": "1351295"},
{"allocationPart": 0.2, "checked": true, "locked": true, "sectionId": 4452, "variationId": "0"}
],
"combinationsAllocations": []
}
}'
```
**Response (abridged):**
```json theme={null}
{
"id": 404811,
"mvtAllocationSettings": {
"exposedPart": 0.8,
"sectionsAllocations": [
{"variationId": "1351294", "sectionId": 4451, "allocationPart": 0.6, "locked": true, "checked": true},
{"variationId": "1351293", "sectionId": 4451, "allocationPart": 0.25, "locked": true, "checked": true},
{"variationId": "0", "sectionId": 4451, "allocationPart": 0.15, "locked": true, "checked": true},
{"variationId": "1351296", "sectionId": 4452, "allocationPart": 0.5, "locked": true, "checked": true},
{"variationId": "1351295", "sectionId": 4452, "allocationPart": 0.3, "locked": true, "checked": true},
{"variationId": "0", "sectionId": 4452, "allocationPart": 0.2, "locked": true, "checked": true}
],
"combinationsAllocations": []
}
}
```
The allocation now matches the values you submitted, and `locked` stays `true`. A subsequent `GET` request confirms the same result.
### 4. Verify the experiment
Go to the **Experiments Dashboard** in the Kameleoon app and open the experiment to confirm the sections, variations, and traffic allocation match what you configured.
## Known limitations
* **Deleting large MVT experiments can time out.** `DELETE /experiments/{experimentId}` can return a `504 Gateway Timeout` error when the experiment has many combinations. A timeout doesn't necessarily mean the delete failed: send a `GET` request for the same experiment ID to confirm whether it still exists before retrying the delete.