Setting the file. One moment.
Skill 26 · Launchdarkly Experiment Guide
Subchapter 26.1
references/create-experiment.mdMarkdown6 KBView on GitHub
This is one logical step with two implementations. Detect what’s available and use it. Only run this after the user has confirmed the draft (Step 7).
Detection order (already confirmed up front by the skill’s preflight, which checks for the create tools — a flags-only MCP does not qualify):
create-experiment,
create-metric, start-experiment-iteration, …) → MCP path (preferred).You need these values, gathered in earlier steps:
projectKey, environmentKey (from get-projects, or get-environment for one environment).ruleId
(fallthrough rule id is the string "fallthrough"), and current
flagConfigVersion.Prefer delegating the mechanical details to
launchdarkly-experiment-setup. It owns the field-level rules (mutableFieldsByStatus, iteration lifecycle, stopping with a winner). This reference is the abstraction contract so this skill can complete the flow even when that skill isn’t loaded.
create-metric (or delegate to
launchdarkly-metric-create). Skip if reusing an existing metric.create-experiment:{
"projectKey": "my-project",
"environmentKey": "production",
"key": "redesigned-checkout-experiment",
"name": "Redesigned Checkout Experiment",
"description": "Test the redesigned checkout against the current flow.",
"iteration": {
"hypothesis": "The redesigned checkout will lift completion ~3% for logged-in shoppers.",
"primarySingleMetricKey": "checkout-completed",
"metrics": [
{ "key": "checkout-completed" },
{ "key": "checkout-error-rate" }
],
"treatments": [
{ "name": "Control", "baseline": true, "allocationPercent": 50,
"parameters": [{ "flagKey": "new-checkout", "variationId": "<control-variation-id>" }] },
{ "name": "New Checkout", "baseline": false, "allocationPercent": 50,
"parameters": [{ "flagKey": "new-checkout", "variationId": "<treatment-variation-id>" }] }
],
"flags": {
"new-checkout": { "ruleId": "fallthrough", "flagConfigVersion": 7 }
},
"randomizationUnit": "user"
}
}get-experiments; confirm the experiment exists with a
not_started iteration.Create the experiment as a draft. Start it only after the flag and tracking
code are deployed and the user says yes again. Starting
(start-experiment-iteration, with confirm: true) requires the flag to be on, a
randomizationUnit, and at least one non-zero allocation.
Rules that matter: exactly one treatment has baseline: true; allocations sum
to 100; the iteration object is required on create.
Base URL https://app.launchdarkly.com. Header:
Authorization: <token>, where <token> is the API access token the user pasted (plus Content-Type: application/json, and
LD-API-Version: beta for experiment endpoints).
Create a metric (skip if reusing):
POST /api/v2/metrics/{projectKey}
{
"key": "checkout-completed",
"name": "Checkout completed",
"kind": "custom",
"isNumeric": false,
"eventKey": "checkout-completed",
"successCriteria": "HigherThanBaseline"
}Create the experiment (body mirrors the MCP iteration):
POST /api/v2/projects/{projectKey}/environments/{environmentKey}/experiments
{
"key": "redesigned-checkout-experiment",
"name": "Redesigned Checkout Experiment",
"iteration": {
"hypothesis": "The redesigned checkout will lift completion ~3% for logged-in shoppers.",
"primarySingleMetricKey": "checkout-completed",
"metrics": [{ "key": "checkout-completed" }, { "key": "checkout-error-rate" }],
"treatments": [
{ "name": "Control", "baseline": true, "allocationPercent": 50,
"parameters": [{ "flagKey": "new-checkout", "variationId": "<control-variation-id>" }] },
{ "name": "New Checkout", "baseline": false, "allocationPercent": 50,
"parameters": [{ "flagKey": "new-checkout", "variationId": "<treatment-variation-id>" }] }
],
"flags": { "new-checkout": { "ruleId": "fallthrough", "flagConfigVersion": 7 } },
"randomizationUnit": "user"
}
}Start the iteration (only after the flag and tracking code are deployed and
the user says yes again): create-experiment already created a not_started
iteration — do not POST .../iterations to start it (that creates a second,
now-deprecated iteration). Start the existing draft with a semantic-patch PATCH
on the experiment:
PATCH /api/v2/projects/{projectKey}/environments/{environmentKey}/experiments/{experimentKey}
Content-Type: application/json; domain-model=launchdarkly.semanticpatch
{ "instructions": [{ "kind": "startIteration" }] }Same preconditions as the MCP path: the flag must be on, the iteration needs a
randomizationUnit, and at least one treatment must have a non-zero allocation.
Verify:
GET /api/v2/projects/{projectKey}/environments/{environmentKey}/experiments/{experimentKey}CRUD reality check: metrics support full CRUD (create/read/update/delete). Experiments support create/read/update + iterations, but no delete — you manage an experiment’s life through its iterations, not by deleting it.
For exact request/response schemas, see the OpenAPI spec:
https://launchdarkly.com/docs/api/other/get-openapi-spec (tags: Metrics,
Experiments).
Present the draft plus the two POST calls above with the user’s real values
filled in, and tell them they can either run them with an API token or open the
experiment in the LaunchDarkly UI. Point them at launchdarkly-experiment-setup
to finish and to run the iteration lifecycle.