Experiments API

Manage A/B experiments programmatically. All endpoints on this page require the secret management key vsk_live_….

Base URL: https://statskit.ai/api/v1

List experiments

GET /experiments

Returns every experiment for the project with status, goal, target selector, and variants.

curl https://statskit.ai/api/v1/experiments \
  -H "Authorization: Bearer vsk_live_..."

Create an experiment

POST /experiments

Creates and (by default) activates an experiment.

Field	Type	Notes
`type`	`element` \| `cta` \| `manual`	`element` swaps the text of a selector; `cta` swaps a button’s label/link/colors; `manual` has no DOM effect (you assign + emit goal events yourself)
`name`	string	Required
`url`	string	URL/path to run on, or `` for all pages (default ``)
`selector`	string	CSS selector to test, e.g. `#hero h1`. Not used for `manual`
`goal`	string	Conversion goal event name. Default `cta_click`; required for `manual`
`statsEngine`	string	Stats engine for analysis
`variants`	array	2–6 variants; include one with key `control` as the baseline (blank content on control keeps the original)
`activate`	boolean	Start immediately (default true)

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",
    "url": "/",
    "selector": "#hero h1",
    "goal": "signup",
    "variants": [
      { "key": "control" },
      { "key": "b", "content": "Ship 2x faster" }
    ]
  }'

For a manual experiment, the goal is required and there is no DOM effect. Assign visitors with statskit.experiment('<key>') in the browser or POST /experiments/:key/assign on the server, then emit your own goal events.

{
  "type": "manual",
  "name": "Onboarding flow",
  "goal": "activated",
  "variants": [
    { "key": "control" },
    { "key": "b" }
  ]
}

Get experiment results

GET /experiments/:id

Returns per-variant exposed / conversions / rate, uplift %, p-value, significance, and the winner. :id accepts the experiment id or key.

curl https://statskit.ai/api/v1/experiments/exp_abc123 \
  -H "Authorization: Bearer vsk_live_..."

Set experiment status

POST /experiments/:id

Change status to draft, running, or stopped.

curl -X POST https://statskit.ai/api/v1/experiments/exp_abc123 \
  -H "Authorization: Bearer vsk_live_..." \
  -H "Content-Type: application/json" \
  -d '{ "status": "running" }'

Assign a unit

POST /experiments/:key/assign

Server-side / headless assignment. Returns the variant a unit (visitor/user id) is bucketed into. Use for manual experiments or any server-driven test.

curl -X POST https://statskit.ai/api/v1/experiments/onboarding_flow/assign \
  -H "Authorization: Bearer vsk_live_..." \
  -H "Content-Type: application/json" \
  -d '{ "unit": "user_123", "url": "/app" }'

{ "variant": "b" }

Update metrics

PUT /experiments/:id/metrics

Set the experiment’s primary metric and guardrails.

curl -X PUT https://statskit.ai/api/v1/experiments/exp_abc123/metrics \
  -H "Authorization: Bearer vsk_live_..." \
  -H "Content-Type: application/json" \
  -d '{ "primary": "signup", "guardrails": ["bounce_rate"] }'