Create an experiment

You can create an experiment from the dashboard, the REST API, or an AI agent over MCP. All three hit the same backend and produce the same experiment.

Dashboard

1. Open your project and go to Experiments, then New experiment.

2. Pick a type (element, cta, or manual), name it, and set the target URL.

3. For element and cta, enter the CSS selector and the variant content. Add at least a control and one variant.

4. Choose the goal and the stats engine, then create. Leaving it active starts it running immediately.

📸 Visual

Placeholder, the New experiment form with type picker, selector field, and variant editor filled in. Source: dashboard (auth).

REST API

POST https://statskit.ai/api/v1/experiments with a secret key.

Create an element experiment

curl -X POST https://statskit.ai/api/v1/experiments \
  -H "Authorization: Bearer vsk_live_…" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "element",
    "name": "Hero headline test",
    "url": "/",
    "selector": "#hero h1",
    "goal": "signup",
    "statsEngine": "bayesian",
    "variants": [
      { "key": "control" },
      { "key": "b", "content": "Ship 2x faster" }
    ],
    "activate": true
  }'

Create a cta experiment

curl -X POST https://statskit.ai/api/v1/experiments \
  -H "Authorization: Bearer vsk_live_…" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "cta",
    "name": "Signup button test",
    "url": "/pricing",
    "selector": "a.signup-btn",
    "variants": [
      { "key": "control" },
      { "key": "b", "content": "Start free trial", "href": "/signup", "bg": "#111", "color": "#fff" }
    ],
    "activate": true
  }'

Fields

• type: element (default), cta, or manual.
• name: required.
• url: the target URL pattern. Defaults to * (all pages).
• selector: a CSS selector for the element to test. Required for element and cta.
• goal: the conversion event. Optional for element/cta (a cta experiment defaults to cta_click); required for manual.
• statsEngine: bayesian (default) or frequentist.
• variants: at least two, one with key: "control". Per-variant content, href, bg, and color shape the override.
• activate: defaults to true, which starts the experiment running. Set false to create it as a draft.

Tip

To create a manual experiment, see Manual experiments, the payload sets type: "manual", requires goal, and omits selector.

MCP

An AI agent connected to the StatsKit MCP server can create experiments with the create_experiment tool. It takes the same shape as the REST payload: type, name, url, selector, goal, statsEngine, and variants.

Prompt an agent

Create an element experiment named "Hero headline test" on "/" that swaps
"#hero h1" to "Ship 2x faster" for variant b, goal signup, and start it.

The tool returns the experiment id, key, and status so the agent can follow up with results or set status.

What you get back

A successful create returns the experiment id, its assignment key, the resolved type, and status (running when activate is not false, otherwise draft). Use the id to read results or to set status with POST /v1/experiments/:id.