Skip to main content

Experiments API

Run A/B tests to compare different flows or content variants and measure their impact. All endpoints require JWT authentication.

List Experiments​

GET /api/experiments

Query Parameters

ParameterTypeDefaultDescription
pagestring"1"Page number
limitstring"20"Items per page
statusstring—Filter by status (draft, running, stopped, completed)

Response

{
  "data": [
    {
      "id": "exp_abc123",
      "name": "Onboarding Flow Test",
      "description": "Compare short vs. detailed onboarding",
      "type": "ab_test",
      "status": "running",
      "audienceId": "aud_xyz",
      "startDate": "2025-02-01T00:00:00Z",
      "endDate": null,
      "createdAt": "2025-01-28T10:00:00Z",
      "updatedAt": "2025-02-01T00:00:00Z",
      "variants": [
        {
          "id": "v1",
          "name": "Control",
          "splitPercentage": 50,
          "flowId": "flow_a"
        },
        {
          "id": "v2",
          "name": "Detailed",
          "splitPercentage": 50,
          "flowId": "flow_b"
        }
      ],
      "_count": { "assignments": 500 }
    }
  ],
  "meta": { "total": 3, "page": 1, "limit": 20, "totalPages": 1 }
}

Create Experiment​

POST /api/experiments

Request Body

{
  "name": "Onboarding Flow Test",
  "description": "Compare short vs. detailed onboarding",
  "type": "ab_test",
  "audienceId": "aud_xyz",
  "variants": [
    {
      "name": "Control",
      "splitPercentage": 50,
      "flowId": "flow_a",
      "config": {}
    },
    {
      "name": "Detailed",
      "splitPercentage": 50,
      "flowId": "flow_b",
      "config": {}
    }
  ]
}

Variant splitPercentage values must sum to 100.

Get Experiment​

GET /api/experiments/:id

Returns the experiment with all variant details.

Update Experiment​

PATCH /api/experiments/:id

Updates experiment metadata and variants (partial update — only provided fields are modified). Only allowed while the experiment is in draft status.

Archive Experiment​

DELETE /api/experiments/:id

Start Experiment​

POST /api/experiments/:id/start

Launches the experiment. Users matching the audience criteria will be assigned to variants based on split percentages.

Stop Experiment​

POST /api/experiments/:id/stop

Stops variant assignment. Existing assignments remain but no new users are enrolled.

Get Results​

GET /api/experiments/:id/results

Returns raw variant assignment and conversion data.

Response

{
  "data": {
    "experimentId": "exp_abc123",
    "name": "Onboarding Flow Test",
    "status": "running",
    "startDate": "2025-02-01T00:00:00Z",
    "endDate": null,
    "variants": [
      {
        "variantId": "v1",
        "variantName": "Control",
        "splitPercentage": 50,
        "participants": 250,
        "results": []
      }
    ]
  }
}

Compute Results​

POST /api/experiments/:id/compute-results

Triggers statistical analysis and returns computed conversion rates.

Response

{
  "data": {
    "experimentId": "exp_abc123",
    "variants": [
      {
        "variantId": "v1",
        "variantName": "Control",
        "sampleSize": 250,
        "conversions": 45,
        "conversionRate": 0.18
      },
      {
        "variantId": "v2",
        "variantName": "Detailed",
        "sampleSize": 250,
        "conversions": 67,
        "conversionRate": 0.268
      }
    ]
  }
}