A/B Testing API

The A/B testing system controls how testers are assigned to variants and how study rounds are managed. Use these endpoints to drive variant assignment, track per-tester task progress, control round lifecycle, schedule reminders, and retrieve aggregate analytics.

Endpoints

POST /api/ab/assign JWT

Assign a tester to an A/B variant for a study

Variant assignment is deterministic per tester and study. Calling this endpoint again for the same tester and study returns the existing assignment.

Request body

{
  "jobId": "job_abc123",
  "testerId": "user_xyz789"
}

Field	Type	Required	Description
jobId	string	Yes	Study to assign the tester to
testerId	string	Yes	Tester to assign

Response

{
  "success": true,
  "data": {
    "jobId": "job_abc123",
    "testerId": "user_xyz789",
    "variant": "B",
    "assignedAt": "2026-03-16T09:00:00Z",
    "isNew": true
  },
  "error": null,
  "metadata": null
}

isNew is false when the assignment already existed.

GET /api/ab/progress/:sessionId JWT

Retrieve task progress for a session within an A/B test

Path parameters

Parameter	Description
sessionId	Session ID

Response

{
  "success": true,
  "data": {
    "sessionId": "sess_001",
    "variant": "A",
    "totalTasks": 5,
    "completedTasks": 3,
    "tasks": [
      { "taskId": "t_001", "title": "Find the settings page", "completed": true, "completedAt": "2026-03-16T10:05:00Z" },
      { "taskId": "t_002", "title": "Update account email", "completed": true, "completedAt": "2026-03-16T10:09:00Z" },
      { "taskId": "t_003", "title": "Complete checkout flow", "completed": true, "completedAt": "2026-03-16T10:18:00Z" },
      { "taskId": "t_004", "title": "Submit support request", "completed": false, "completedAt": null },
      { "taskId": "t_005", "title": "Log out of the account", "completed": false, "completedAt": null }
    ]
  },
  "error": null,
  "metadata": null
}

POST /api/ab/task-checklist/save JWT

Save task checklist state for a session

Call this endpoint to persist checklist progress as the tester works through tasks. Designed for incremental saves rather than bulk submission.

Request body

{
  "sessionId": "sess_001",
  "tasks": [
    { "taskId": "t_004", "completed": true, "completedAt": "2026-03-16T10:22:00Z" }
  ]
}

Response

{
  "success": true,
  "data": {
    "sessionId": "sess_001",
    "savedCount": 1
  },
  "error": null,
  "metadata": null
}

POST /api/ab/task-checklist/generate JWT

Generate a task checklist for a session from the study definition

Creates the initial task list for a session based on the parent study’s task configuration and the assigned variant. Call once per session before the tester starts.

Request body

{
  "sessionId": "sess_001",
  "jobId": "job_abc123",
  "variant": "A"
}

Response

{
  "success": true,
  "data": {
    "sessionId": "sess_001",
    "variant": "A",
    "tasks": [
      { "taskId": "t_001", "title": "Find the settings page", "description": "Navigate to account settings without using the search bar.", "order": 1 },
      { "taskId": "t_002", "title": "Update account email", "description": "Change your email address to test@example.com.", "order": 2 }
    ]
  },
  "error": null,
  "metadata": null
}

POST /api/ab/round/start JWT

Start a new A/B test round for a study

A round groups a set of sessions into a cohort. Starting a new round allows you to run multiple waves of testing on the same study with distinct participant pools.

Request body

{
  "jobId": "job_abc123",
  "roundLabel": "Round 2 - Post-redesign",
  "targetSessionCount": 10
}

Field	Type	Required	Description
jobId	string	Yes	Study to start a round for
roundLabel	string	No	Human-readable label for this round
targetSessionCount	integer	No	How many sessions to collect before the round auto-closes

Response

{
  "success": true,
  "data": {
    "roundId": "round_002",
    "jobId": "job_abc123",
    "label": "Round 2 - Post-redesign",
    "status": "active",
    "startedAt": "2026-03-16T09:00:00Z"
  },
  "error": null,
  "metadata": null
}

POST /api/ab/round/pause JWT

Pause an active A/B test round

Pausing prevents new sessions from being assigned to the round. Existing in-progress sessions continue until completion.

Request body

{
  "roundId": "round_002",
  "reason": "Interim review by product team"
}

Response

{
  "success": true,
  "data": {
    "roundId": "round_002",
    "status": "paused",
    "pausedAt": "2026-03-16T14:00:00Z"
  },
  "error": null,
  "metadata": null
}

POST /api/ab/reminders/cron Cron

Trigger reminder processing for pending A/B test sessions

This endpoint is called by the scheduler. It finds sessions that have been inactive beyond the configured reminder threshold and dispatches notifications to testers.

Request body

None required.

Response

{
  "success": true,
  "data": {
    "processedAt": "2026-03-16T08:00:00Z",
    "remindersQueued": 4,
    "skipped": 1
  },
  "error": null,
  "metadata": null
}

GET /api/ab/analytics/:jobId JWT

Retrieve A/B test analytics for a study

Path parameters

Parameter	Description
jobId	Study ID

Returns aggregated metrics broken down by variant, including task completion rates, average session duration, and frustration scores.

Response

{
  "success": true,
  "data": {
    "jobId": "job_abc123",
    "totalSessions": 20,
    "variants": {
      "A": {
        "sessionCount": 10,
        "avgCompletionRate": 0.72,
        "avgDurationSeconds": 1840,
        "avgFrustrationScore": 0.38,
        "taskBreakdown": [
          { "taskId": "t_001", "completionRate": 0.90 },
          { "taskId": "t_002", "completionRate": 0.70 }
        ]
      },
      "B": {
        "sessionCount": 10,
        "avgCompletionRate": 0.85,
        "avgDurationSeconds": 1620,
        "avgFrustrationScore": 0.24,
        "taskBreakdown": [
          { "taskId": "t_001", "completionRate": 0.95 },
          { "taskId": "t_002", "completionRate": 0.88 }
        ]
      }
    },
    "winner": "B",
    "confidence": 0.92
  },
  "error": null,
  "metadata": null
}

winner and confidence are null if there are fewer than 5 sessions per variant.