Skip to main content

​
GET /api/v1/experiments

List all experiments with their champion model and challengers. Supports cursor-based pagination.

​
Response

{
  "data": [
    {
      "id": "exp_001",
      "key": "cc-propensity-v2-test",
      "name": "Credit Card: Scorecard vs Bayesian",
      "status": "running",
      "trafficSplit": { "championPct": 50 },
      "autoPromote": true,
      "promoteThreshold": 0.02,
      "promoteAfterDays": 14,
      "championModel": { "id": "model_001", "name": "Scorecard v3" },
      "challengers": [
        { "modelId": "model_002", "trafficPct": 50, "model": { "name": "Bayesian v1" } }
      ],
      "createdAt": "2026-03-01T10:00:00.000Z"
    }
  ],
  "total": 3,
  "hasMore": false
}

​
POST /api/v1/experiments

Create a new experiment. Traffic split must sum to 100%.

​
Request Body

FieldTypeRequiredDescription
keystringYesUnique experiment key
namestringYesDisplay name
descriptionstringNoDescription
statusstringNoDefault: "draft"
championModelIdstringNoChampion model ID
trafficSplitobjectNo{ championPct: number }. Default: { championPct: 80 }
challengersarrayNo[{ modelId, trafficPct }]
autoPromotebooleanNoAuto-promote challenger if it wins. Default: false
promoteThresholdnumberNoMinimum uplift for auto-promotion. Default: 0.02
promoteAfterDaysnumberNoDays to wait before auto-promotion. Default: 14

​
Example

curl -X POST https://playground.kaireonai.com/api/v1/experiments \
  -H "Content-Type: application/json" \
  -H "X-Tenant-Id: my-tenant" \
  -d '{
    "key": "cc-bayesian-test",
    "name": "Credit Card: Champion vs Bayesian",
    "championModelId": "model_001",
    "trafficSplit": { "championPct": 50 },
    "challengers": [{ "modelId": "model_002", "trafficPct": 50 }],
    "autoPromote": true,
    "promoteThreshold": 0.02,
    "promoteAfterDays": 14
  }'
Response: 201 Created

​
GET /api/v1/experiments/

Get experiment details with champion and challenger models.

​
PUT /api/v1/experiments/

Update an experiment. Challengers are replaced entirely if provided.

​
Request Body

All fields optional. Same as POST fields plus results (object) for storing outcome data.

​
DELETE /api/v1/experiments/

Delete an experiment and its challengers. Response: 204 No Content

​
GET /api/v1/experiments//results

Returns uplift analysis and statistical significance for treatment vs holdout. The endpoint first checks for live variant assignment data. If no assignments exist, it falls back to stored JSON results.

​
Response

{
  "experimentId": "exp_001",
  "experimentName": "Credit Card: Champion vs Bayesian",
  "status": "running",
  "hasResults": true,
  "dataSource": "live",
  "treatment": {
    "samples": 5200,
    "conversions": 416,
    "conversionRate": 0.08,
    "ci95Lower": 0.0728,
    "ci95Upper": 0.0877
  },
  "holdout": {
    "samples": 520,
    "conversions": 31,
    "conversionRate": 0.0596,
    "ci95Lower": 0.0419,
    "ci95Upper": 0.0839
  },
  "uplift": {
    "absolute": 0.0204,
    "relative": 0.3423
  },
  "significance": {
    "zScore": 1.52,
    "pValue": 0.1286,
    "isSignificant": false,
    "confidenceLevel": 0.95
  },
  "requiredSampleSize": 15000,
  "upliftAnalysis": {
    "treatmentConversionRate": 0.08,
    "holdoutConversionRate": 0.0596,
    "uplift": 0.0204,
    "relativeUplift": 0.3423,
    "zScore": 1.52,
    "pValue": 0.1286,
    "significant": false
  },
  "variants": [
    { "label": "Champion", "modelName": "Scorecard v3", "samples": 2600, "conversionRate": 0.079 },
    { "label": "Challenger 1", "modelName": "Bayesian v1", "samples": 2600, "conversionRate": 0.081 }
  ]
}

​
Statistical Methods

  • Two-proportion z-test for significance testing (p < 0.05)
  • Wilson confidence intervals for per-variant conversion rates
  • Required sample size estimation based on baseline rate and minimum detectable effect

​
Roles

EndpointAllowed Roles
GET /experimentsany authenticated
POST /experimentsadmin, editor
PUT /experiments/{id}admin, editor
DELETE /experiments/{id}admin, editor
GET /experiments/{id}/resultsany authenticated
See also: Algorithms & Models