Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.kaireonai.com/llms.txt

Use this file to discover all available pages before exploring further.

​
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": "active",
      "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"
    }
  ],
  "pagination": {
    "total": 3,
    "hasMore": false,
    "limit": 50,
    "cursor": null
  }
}

​
POST /api/v1/experiments

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

​
Request Body

FieldTypeRequiredDescription
keystringYesUnique experiment key
namestringYesDisplay name
descriptionstringNoDescription
statusstringNoOne of: draft, active, paused, archived. Default: "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

​
Validation

  • Traffic split must sum to 100%: championPct + sum(challengers[].trafficPct) must equal exactly 100. Returns 400 if not.
  • Key must be unique per tenant. Duplicate key returns 400.

​
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
DELETE also works at the collection level: DELETE /api/v1/experiments?id={experimentId}. Both the path parameter and query parameter forms are supported.

​
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": "active",
  "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