Experiments

Create and manage A/B test experiments on feature flags. Experiments split traffic between variants and track conversions to measure impact.

Base URL: https://app.krafter.dev/api/v1

List Experiments

Retrieve all experiments for a flag.

GET /flags/:flag_id/experiments

Required scope: flags:read

Example Request

curl https://app.krafter.dev/api/v1/flags/d4e5f6a7-8b9c-4d0e-9f1a-2b3c4d5e6f7a/experiments \
  -H "Authorization: Bearer kr_live_abc123def456"

Example Response

{
  "data": [
    {
      "id": "3c4d5e6f-7a8b-4c9d-8e0f-1a2b3c4d5e6f",
      "name": "Hero Banner A/B Test",
      "environment": "production",
      "status": "running",
      "variants": [
        {
          "key": "control",
          "value": "old",
          "percentage": 50
        },
        {
          "key": "treatment",
          "value": "new",
          "percentage": 50
        }
      ],
      "conversions": {
        "control": 142,
        "treatment": 187
      },
      "started_at": "2025-03-12T12:00:00Z",
      "stopped_at": null,
      "created_at": "2025-03-12T11:00:00Z",
      "updated_at": "2025-03-16T08:00:00Z"
    }
  ]
}

---

Create Experiment

Create a new experiment on a flag. Variant percentages must sum to 100.

POST /flags/:flag_id/experiments

Required scope: flags:write

Request Body

Field	Type	Required	Description
name	string	Yes	Display name for the experiment.
environment	string	Yes	Environment to run the experiment in (e.g., "production").
variants	array	Yes	Array of variant objects. See Variant Format.
status	string	No	One of "draft", "running", "stopped", "completed". Defaults to "draft". Most callers leave this unset and use the Start and Stop endpoints to transition.

Variant Format

Each variant is an object with three fields:

Field	Type	Description
key	string	Unique identifier for this variant (e.g., "control", "treatment").
value	any	The flag value to return for users assigned to this variant.
percentage	integer	Traffic allocation percentage (0-100). All variant percentages must sum to 100.

Example Request

curl -X POST https://app.krafter.dev/api/v1/flags/d4e5f6a7-8b9c-4d0e-9f1a-2b3c4d5e6f7a/experiments \
  -H "Authorization: Bearer kr_live_abc123def456" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Hero Banner A/B Test",
    "environment": "production",
    "variants": [
      {
        "key": "control",
        "value": "old",
        "percentage": 50
      },
      {
        "key": "treatment",
        "value": "new",
        "percentage": 50
      }
    ]
  }'

Example Response

// 201 Created
{
  "data": {
    "id": "3c4d5e6f-7a8b-4c9d-8e0f-1a2b3c4d5e6f",
    "name": "Hero Banner A/B Test",
    "environment": "production",
    "status": "draft",
    "variants": [
      {
        "key": "control",
        "value": "old",
        "percentage": 50
      },
      {
        "key": "treatment",
        "value": "new",
        "percentage": 50
      }
    ],
    "conversions": {
      "control": 0,
      "treatment": 0
    },
    "started_at": null,
    "stopped_at": null,
    "created_at": "2025-03-12T11:00:00Z",
    "updated_at": "2025-03-12T11:00:00Z"
  }
}

---

Start Experiment

Start a draft or stopped experiment. Traffic will begin being split between variants. Restarting a stopped experiment resets started_at to the current time but preserves prior conversion counters.

POST /flags/:flag_id/experiments/:experiment_id/start

Required scope: flags:write

Example Request

curl -X POST https://app.krafter.dev/api/v1/flags/d4e5f6a7-8b9c-4d0e-9f1a-2b3c4d5e6f7a/experiments/3c4d5e6f-7a8b-4c9d-8e0f-1a2b3c4d5e6f/start \
  -H "Authorization: Bearer kr_live_abc123def456"

Example Response

{
  "data": {
    "id": "3c4d5e6f-7a8b-4c9d-8e0f-1a2b3c4d5e6f",
    "name": "Hero Banner A/B Test",
    "environment": "production",
    "status": "running",
    "variants": [
      {
        "key": "control",
        "value": "old",
        "percentage": 50
      },
      {
        "key": "treatment",
        "value": "new",
        "percentage": 50
      }
    ],
    "conversions": {
      "control": 0,
      "treatment": 0
    },
    "started_at": "2025-03-12T12:00:00Z",
    "stopped_at": null,
    "created_at": "2025-03-12T11:00:00Z",
    "updated_at": "2025-03-12T12:00:00Z"
  }
}

---

Stop Experiment

Stop a running experiment. Traffic splitting will cease and the flag will return its default value.

POST /flags/:flag_id/experiments/:experiment_id/stop

Required scope: flags:write

Example Request

curl -X POST https://app.krafter.dev/api/v1/flags/d4e5f6a7-8b9c-4d0e-9f1a-2b3c4d5e6f7a/experiments/3c4d5e6f-7a8b-4c9d-8e0f-1a2b3c4d5e6f/stop \
  -H "Authorization: Bearer kr_live_abc123def456"

Example Response

{
  "data": {
    "id": "3c4d5e6f-7a8b-4c9d-8e0f-1a2b3c4d5e6f",
    "name": "Hero Banner A/B Test",
    "environment": "production",
    "status": "completed",
    "variants": [
      {
        "key": "control",
        "value": "old",
        "percentage": 50
      },
      {
        "key": "treatment",
        "value": "new",
        "percentage": 50
      }
    ],
    "conversions": {
      "control": 142,
      "treatment": 187
    },
    "started_at": "2025-03-12T12:00:00Z",
    "stopped_at": "2025-03-16T18:00:00Z",
    "created_at": "2025-03-12T11:00:00Z",
    "updated_at": "2025-03-16T18:00:00Z"
  }
}

Experiment Statuses

Status	Description
draft	Experiment created but not yet started. No traffic splitting.
running	Experiment is active. Traffic is being split between variants.
stopped	Experiment was stopped via Stop Experiment. Final conversion counts are available. Can be restarted via Start Experiment.
completed	Reserved status — not currently set by any API endpoint. Listed for forward compatibility.