--- title: Create an Experiment description: Create a new experiment in a space. url: https://storyblok.com/docs/api/management/experiments/create-an-experiment --- # Create an Experiment Create a new experiment in a space. Storyblok creates new experiments in `draft` status. Optionally, include variants and associate stories with the experiment in the same request. POST ```html https://mapi.storyblok.com/v1/spaces/:space_id/experiments ``` ## Path parameters - `:space_id` (required) (number) Numeric ID of a space. ## Request body properties - `experiment` (required) (object) The experiment to create. Show child properties - `name` (required) (string) Technical name of the experiment. Lowercase letters, numbers, and underscores only. Immutable after creation. - `display_name` (required) (string) Human-readable display name of the experiment. - `description` (string) Description of the experiment. - `story_ids` (number\[\]) Array of [story](/docs/api/management/stories/the-story-object) IDs to associate with the experiment. - `experiment_variants_attributes` (object\[\]) Array of variants to create with the experiment. The sum of all variant weights must equal `100`. Show child properties - `name` (required) (string) Technical name of the variant. Lowercase letters, numbers, and underscores only. - `display_name` (required) (string) Human-readable display name of the variant. - `weight` (number) Traffic weight of the variant in percent (0–100). - `is_control` (boolean) `true` if the variant is the control (baseline). One variant per experiment must be the control. ## Response properties - `experiment` (The Experiment Object) The created [experiment object](/docs/api/management/experiments/the-experiment-object). ## Examples - cURL ```shellscript curl "https://mapi.storyblok.com/v1/spaces/288868932106293/experiments/" \ -X POST \ -H "Authorization: YOUR_OAUTH_TOKEN" \ -H "Content-Type: application/json" \ -d "{\"experiment\":{\"description\":\"A short description for a simple test\",\"display_name\":\"A simple test\",\"experiment_variants_attributes\":[{\"display_name\":\"Control\",\"is_control\":true,\"name\":\"control\",\"weight\":60},{\"display_name\":\"Test\",\"is_control\":false,\"name\":\"test\",\"weight\":40}],\"name\":\"a_simple_test\",\"story_ids\":[176024833123843]}}" ``` - JS ```javascript // storyblok-js-client@>=7, node@>=18 import Storyblok from "storyblok-js-client"; const storyblok = new Storyblok({ oauthToken: "YOUR_PERSONAL_ACCESS_TOKEN", }); try { const response = await storyblok.post('spaces/288868932106293/experiments/', { "experiment": { "description": "A short description for a simple test", "display_name": "A simple test", "experiment_variants_attributes": [ { "display_name": "Control", "is_control": true, "name": "control", "weight": 60 }, { "display_name": "Test", "is_control": false, "name": "test", "weight": 40 } ], "name": "a_simple_test", "story_ids": [ 176024833123843 ] } }) console.log({ response }) } catch (error) { console.log(error) } ``` - PHP ```php $client = new \Storyblok\ManagementClient('YOUR_OAUTH_TOKEN'); $payload = ["experiment" => ["description" => "A short description for a simple test","display_name" => "A simple test","experiment_variants_attributes" => [["display_name" => "Control","is_control" => true,"name" => "control","weight" => 60],["display_name" => "Test","is_control" => false,"name" => "test","weight" => 40]],"name" => "a_simple_test","story_ids" => [176024833123843]]]; $client->post('spaces/288868932106293/experiments/', $payload)->getBody(); ``` - Java ```java HttpResponse response = Unirest.post("https://mapi.storyblok.com/v1/spaces/288868932106293/experiments/") .header("Content-Type", "application/json") .header("Authorization", "YOUR_OAUTH_TOKEN") .body({"experiment":{"description":"A short description for a simple test","display_name":"A simple test","experiment_variants_attributes":[{"display_name":"Control","is_control":true,"name":"control","weight":60},{"display_name":"Test","is_control":false,"name":"test","weight":40}],"name":"a_simple_test","story_ids":[176024833123843]}}) .asString(); ``` - C# ```csharp var client = new RestClient("https://mapi.storyblok.com/v1/spaces/288868932106293/experiments/"); var request = new RestRequest(Method.POST); request.AddHeader("Content-Type", "application/json"); request.AddHeader("Authorization", "YOUR_OAUTH_TOKEN"); request.AddParameter("application/json", "{\"experiment\":{\"description\":\"A short description for a simple test\",\"display_name\":\"A simple test\",\"experiment_variants_attributes\":[{\"display_name\":\"Control\",\"is_control\":true,\"name\":\"control\",\"weight\":60},{\"display_name\":\"Test\",\"is_control\":false,\"name\":\"test\",\"weight\":40}],\"name\":\"a_simple_test\",\"story_ids\":[176024833123843]}}", ParameterType.RequestBody); IRestResponse response = client.Execute(request); ``` - Python ```python import requests url = "https://mapi.storyblok.com/v1/spaces/288868932106293/experiments/" querystring = {} payload = {"experiment":{"description":"A short description for a simple test","display_name":"A simple test","experiment_variants_attributes":[{"display_name":"Control","is_control":true,"name":"control","weight":60},{"display_name":"Test","is_control":false,"name":"test","weight":40}],"name":"a_simple_test","story_ids":[176024833123843]}} headers = { 'Content-Type': "application/json", 'Authorization': "YOUR_OAUTH_TOKEN" } response = requests.request("POST", url, data=payload, headers=headers, params=querystring) print(response.text) ``` - Ruby ```ruby require 'storyblok' client = Storyblok::Client.new(oauth_token: 'YOUR_OAUTH_TOKEN') payload = {"experiment" => {"description" => "A short description for a simple test","display_name" => "A simple test","experiment_variants_attributes" => [{"display_name" => "Control","is_control" => true,"name" => "control","weight" => 60},{"display_name" => "Test","is_control" => false,"name" => "test","weight" => 40}],"name" => "a_simple_test","story_ids" => [176024833123843]}} client.post('spaces/288868932106293/experiments/', payload) ``` - Swift ```swift let storyblok = URLSession(storyblok: .mapi(accessToken: .oauth("YOUR_OAUTH_TOKEN"))) var request = URLRequest(storyblok: storyblok, path: "spaces/288868932106293/experiments/") request.httpMethod = "POST" request.httpBody = try JSONSerialization.data(withJSONObject: [ "experiment": [ "description": "A short description for a simple test", "display_name": "A simple test", "experiment_variants_attributes": [ [ "display_name": "Control", "is_control": true, "name": "control", "weight": 60, ], [ "display_name": "Test", "is_control": false, "name": "test", "weight": 40, ], ], "name": "a_simple_test", "story_ids": [ 176024833123843, ], ], ]) let (data, _) = try await storyblok.data(for: request) print(try JSONSerialization.jsonObject(with: data)) ``` - Kotlin ```kotlin val client = HttpClient { install(Storyblok(MAPI)) { accessToken = OAuth("YOUR_OAUTH_TOKEN") } } val response = client.post("spaces/288868932106293/experiments/") { setBody(buildJsonObject { putJsonObject("experiment") { put("description", "A short description for a simple test") put("display_name", "A simple test") putJsonArray("experiment_variants_attributes") { addJsonObject { put("display_name", "Control") put("is_control", true) put("name", "control") put("weight", 60) } addJsonObject { put("display_name", "Test") put("is_control", false) put("name", "test") put("weight", 40) } } put("name", "a_simple_test") putJsonArray("story_ids") { add(176024833123843) } } }) } println(response.body()) ``` ## Pagination - [Previous: Create a Story Mapping](/docs/api/management/experiments/create-a-story-mapping) - [Next: Delete a Story Mapping](/docs/api/management/experiments/delete-a-story-mapping)