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

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 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.

Examples

cURL

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

// 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

$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

HttpResponse<String> 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#

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

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

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

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

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<JsonElement>())