Bandit

Response Format

All endpoints return a consistent JSON envelope:

{
  "success": true,
  "data": { ... },
  "error": "...",
  "timestamp": "2026-01-15T10:00:00.000Z"
}

Authentication

The API supports two authentication methods depending on the endpoint:

api-keyPass your API key via the Authorization: Bearer <key> header or x-api-key header. Used by the SDK for assignment and event endpoints.

sessionAuthenticated via NextAuth session cookie or x-user-email header. Used by the dashboard.

adminRequires the user to have the admin role within the company.

Assignments

Get treatment assignments for users in experiments

POST/assignments

Create assignment

Request a treatment assignment for a user in an experiment. The bandit algorithm selects the optimal treatment based on historical performance. If the user already has a cached assignment, it is returned instead.

Auth:api-key

Request Body

Name	Type	Required	Description
experimentId	string	required	ID of the experiment to assign
userId	string	required	Unique identifier for the user
context	Record<string, string \| number \| boolean>	optional	Optional context for contextual bandit algorithms (e.g. device type, location)

Responses

200Assignment returned successfully

400Experiment is not active

404Experiment not found

Example

Request

{
  "experimentId": "exp_abc123",
  "userId": "user_42",
  "context": {
    "deviceType": "mobile",
    "country": "US"
  }
}

Response

{
  "success": true,
  "data": {
    "assignmentId": "asgn_xyz789",
    "experimentId": "exp_abc123",
    "treatment": {
      "id": "trt_def456",
      "name": "Headline B",
      "config": {
        "content": "Start your free trial today"
      }
    },
    "confidence": 0.87
  },
  "timestamp": "2026-01-15T10:30:00.000Z"
}

GET/assignments/:experimentId

Get assignment

Retrieve a treatment assignment for a user via query parameters. Functionally equivalent to the POST endpoint but useful for simple GET-based integrations.

Auth:api-key

Path Parameters

Name	Type	Required	Description
experimentId	string	required	ID of the experiment

Query Parameters

Name	Type	Required	Description
userId	string	required	Unique identifier for the user
context	string (JSON)	optional	JSON-encoded context object for contextual bandits

Responses

200Assignment returned successfully

400Missing userId or experiment not active

404Experiment not found

Events

Track user events and conversions

POST/events

Track event

Record a user event such as a conversion, click, or view. Use assignmentId for precise attribution (recommended) or provide the legacy experimentId + treatmentId + userId triplet. Conversion events automatically update the bandit algorithm.

Auth:api-key

Request Body

Name	Type	Required	Description
assignmentId	string	optional	ID of the assignment (recommended). Provide this OR the legacy triplet below.
experimentId	string	optional	Experiment ID (legacy, use with treatmentId + userId)
treatmentId	string	optional	Treatment ID (legacy, use with experimentId + userId)
userId	string	optional	User ID (legacy, use with experimentId + treatmentId)
eventType	EventType	required	One of: ASSIGNMENT, CONVERSION, CLICK, VIEW, CUSTOM
value	number	optional	Numeric value (e.g. revenue amount for conversions)
metadata	Record<string, any>	optional	Arbitrary metadata to attach to the event

Responses

201Event created successfully

400Validation error or missing required fields

404Assignment, experiment, or treatment not found

409Duplicate event type for this assignment

Example

Request

{
  "assignmentId": "asgn_xyz789",
  "eventType": "CONVERSION",
  "value": 29.99,
  "metadata": {
    "product": "premium-plan"
  }
}

Response

{
  "success": true,
  "data": {
    "id": "evt_abc123",
    "experimentId": "exp_abc123",
    "treatmentId": "trt_def456",
    "userId": "user_42",
    "eventType": "CONVERSION",
    "value": 29.99,
    "metadata": {
      "product": "premium-plan",
      "assignmentId": "asgn_xyz789"
    },
    "timestamp": "2026-01-15T10:35:00.000Z"
  },
  "timestamp": "2026-01-15T10:35:00.000Z"
}

GET/events/:experimentId

List events

Retrieve event history for a specific experiment. Results are paginated with limit and offset query parameters.

Auth:session

Path Parameters

Name	Type	Required	Description
experimentId	string	required	ID of the experiment

Query Parameters

Name	Type	Required	Description
limit	number	optional	Maximum number of events to return (default: 100)
offset	number	optional	Number of events to skip (default: 0)

Responses

200Events returned successfully

404Experiment not found

POST/events/batch

Batch track events

Send multiple events in a single request. Accepts 1 to 1,000 events per batch. Each event is processed independently; partial failures return a 207 Multi-Status response with per-event error details.

Auth:api-key

Request Body

Name	Type	Required	Description
events	TrackEventRequest[]	required	Array of event objects (1-1000). Each follows the same schema as POST /events.

Responses

201All events created successfully

207Partial success - some events failed

400Validation error (e.g. empty array or exceeds 1000)

Example

Request

{
  "events": [
    {
      "assignmentId": "asgn_xyz789",
      "eventType": "CLICK",
      "metadata": {
        "element": "cta-button"
      }
    },
    {
      "assignmentId": "asgn_xyz789",
      "eventType": "CONVERSION",
      "value": 49.99
    }
  ]
}

Response

{
  "success": true,
  "data": {
    "total": 2,
    "success_count": 2,
    "created": [
      "..."
    ],
    "errors": []
  },
  "timestamp": "2026-01-15T10:36:00.000Z"
}

Experiments

Create and manage experiments

GET/experiments

List experiments

Retrieve all experiments belonging to the authenticated company. Returns experiments with their treatments.

Auth:session

Responses

200Experiments returned successfully

POST/experiments

Create experiment

Create a new experiment in DRAFT status. Optionally include initial treatments. The experiment must be activated separately via PUT after adding at least one treatment.

Auth:session

Request Body

Name	Type	Required	Description
name	string	required	Human-readable name for the experiment
description	string	optional	Description of the experiment goals
algorithm	BanditAlgorithm	required	Algorithm to use: EPSILON_GREEDY, UCB1, THOMPSON_SAMPLING, LINEAR_CONTEXTUAL, or NEURAL_CONTEXTUAL
contentType	ContentType	optional	Content type of treatments (default: PLAIN_TEXT)
algorithmConfig	Record<string, any>	optional	Algorithm-specific configuration (e.g. epsilon value)
assignmentTtl	number	optional	Assignment cache TTL in seconds (default: 86400 = 24 hours)
treatments	Treatment[]	optional	Optional initial treatments to create with the experiment

Responses

201Experiment created in DRAFT status

400Validation error

Example

Request

{
  "name": "Homepage Headline Test",
  "description": "Test different headlines on the landing page",
  "algorithm": "THOMPSON_SAMPLING",
  "treatments": [
    {
      "name": "Control",
      "config": {
        "content": "Welcome to our platform"
      },
      "isControl": true
    },
    {
      "name": "Urgency",
      "config": {
        "content": "Limited time offer - start free today!"
      }
    }
  ]
}

Response

{
  "success": true,
  "data": {
    "id": "exp_abc123",
    "name": "Homepage Headline Test",
    "algorithm": "THOMPSON_SAMPLING",
    "status": "draft",
    "treatments": [
      "..."
    ]
  },
  "timestamp": "2026-01-15T10:00:00.000Z"
}

GET/experiments/:id

Get experiment

Retrieve a single experiment by ID, including all associated treatments and their configurations.

Auth:session

Path Parameters

Name	Type	Required	Description
id	string	required	ID of the experiment

Responses

200Experiment returned successfully

404Experiment not found

PUT/experiments/:id

Update experiment

Update experiment properties including name, description, status, and TTL. To activate an experiment, set status to ACTIVE. Activation requires at least one treatment.

Auth:session

Path Parameters

Name	Type	Required	Description
id	string	required	ID of the experiment to update

Request Body

Name	Type	Required	Description
name	string	optional	Updated name
description	string	optional	Updated description
status	ExperimentStatus	optional	New status: DRAFT, ACTIVE, PAUSED, COMPLETED, or ARCHIVED
assignmentTtl	number	optional	Updated assignment TTL in seconds
endAt	string (ISO 8601)	optional	Scheduled end date for the experiment

Responses

200Experiment updated successfully

400Cannot activate without treatments

404Experiment not found

POST/experiments/:id/generate-variant

AI generate variant

Use AI to generate a new treatment variant based on the experiment's existing treatments and performance data. The AI analyzes what's working and generates a new variant using one of eight strategies (emotional appeal, urgency, social proof, etc.).

Auth:session

Path Parameters

Name	Type	Required	Description
id	string	required	ID of the experiment

Responses

201AI variant generated and added as a new treatment

404Experiment not found

POST/experiments/:id/refresh

Refresh algorithm state

Rebuild the in-memory algorithm state from the event history in the database. Useful after manual data changes or if algorithm state has drifted.

Auth:session

Path Parameters

Name	Type	Required	Description
id	string	required	ID of the experiment

Responses

200Algorithm state refreshed successfully

404Experiment not found

POST/experiments/:id/treatments

Add treatment

Add a new treatment (variant) to an experiment. Each treatment has a name, content configuration, optional weight for traffic allocation, and an optional control flag.

Auth:session

Path Parameters

Name	Type	Required	Description
id	string	required	ID of the experiment

Request Body

Name	Type	Required	Description
name	string	required	Name of the treatment variant
description	string	optional	Description of this variant
config	{ content: string, metadata?: Record<string, any> }	required	Treatment configuration with content and optional metadata
weight	number	optional	Traffic weight (default: 1.0)
isControl	boolean	optional	Whether this is the control variant (default: false)

Responses

201Treatment added successfully

404Experiment not found

DELETE/experiments/:id/treatments/:treatmentId

Remove treatment

Remove a treatment from an experiment. The treatment must belong to the specified experiment.

Auth:session

Path Parameters

Name	Type	Required	Description
id	string	required	ID of the experiment
treatmentId	string	required	ID of the treatment to remove

Responses

200Treatment removed successfully

400Treatment does not belong to experiment

404Experiment or treatment not found

Funnels

Create and manage multi-step experiment funnels

GET/funnels

List funnels

Retrieve all funnels belonging to the authenticated company. Each funnel links multiple experiments into a sequential conversion path.

Auth:session

Responses

200Funnels returned successfully

POST/funnels

Create funnel

Create a new funnel linking one or more experiments into a multi-step conversion path. Requires at least one experiment ID.

Auth:session

Request Body

Name	Type	Required	Description
name	string	required	Human-readable name for the funnel
description	string	optional	Description of the funnel goals
experimentIds	string[]	required	Ordered list of experiment IDs that form the funnel steps (minimum 1)

Responses

201Funnel created successfully

400Validation error (e.g. missing name or empty experimentIds)

Example

Request

{
  "name": "Onboarding Flow",
  "description": "Test headline → CTA → pricing across the onboarding funnel",
  "experimentIds": [
    "exp_headline",
    "exp_cta",
    "exp_pricing"
  ]
}

Response

{
  "success": true,
  "data": {
    "id": "fnl_abc123",
    "name": "Onboarding Flow",
    "description": "Test headline → CTA → pricing across the onboarding funnel",
    "experimentIds": [
      "exp_headline",
      "exp_cta",
      "exp_pricing"
    ],
    "status": "draft"
  },
  "timestamp": "2026-01-15T12:00:00.000Z"
}

GET/funnels/:id

Get funnel

Retrieve a single funnel by ID, including details about its linked experiments and their current status.

Auth:session

Path Parameters

Name	Type	Required	Description
id	string	required	ID of the funnel

Responses

200Funnel returned successfully

404Funnel not found

PUT/funnels/:id

Update funnel

Update funnel properties such as name, description, or status.

Auth:session

Path Parameters

Name	Type	Required	Description
id	string	required	ID of the funnel to update

Request Body

Name	Type	Required	Description
name	string	optional	Updated name
description	string	optional	Updated description
status	string	optional	New status: draft, active, paused, or completed

Responses

200Funnel updated successfully

400Validation error

404Funnel not found

DELETE/funnels/:id

Delete funnel

Delete a funnel. This does not delete the linked experiments, only the funnel grouping.

Auth:session

Path Parameters

Name	Type	Required	Description
id	string	required	ID of the funnel to delete

Responses

200Funnel deleted successfully

400Failed to delete funnel

POST/funnels/:id/reward

Record funnel reward

Record a reward (conversion value) for a user who completed the funnel. Updates the bandit algorithm state for all experiments in the funnel based on the treatments the user was assigned. Each user can only have one reward per funnel.

Auth:session

Path Parameters

Name	Type	Required	Description
id	string	required	ID of the funnel

Request Body

Name	Type	Required	Description
userId	string	required	ID of the user who completed the funnel
value	number	required	Reward value (must be >= 0, e.g. revenue amount)

Responses

200Reward recorded and algorithm state updated

404Funnel not found or no assignments found for this user

409Reward already recorded for this user in this funnel

500Internal error recording reward

Example

Request

{
  "userId": "user_42",
  "value": 49.99
}

Response

{
  "success": true,
  "data": {
    "funnelId": "fnl_abc123",
    "userId": "user_42",
    "value": 49.99
  },
  "timestamp": "2026-01-15T14:00:00.000Z"
}

API Reference

Response Format

Authentication

Assignments

Create assignment

Request Body

Responses

Example

Get assignment

Path Parameters

Query Parameters

Responses

Events

Track event

Request Body

Responses

Example

List events

Path Parameters

Query Parameters

Responses

Batch track events

Request Body

Responses

Example

Experiments

List experiments

Responses

Create experiment

Request Body

Responses

Example

Get experiment

Path Parameters

Responses

Update experiment

Path Parameters

Request Body

Responses

AI generate variant

Path Parameters

Responses

Refresh algorithm state

Path Parameters

Responses

Add treatment

Path Parameters

Request Body

Responses

Remove treatment

Path Parameters

Responses

Funnels

List funnels

Responses

Create funnel

Request Body

Responses

Example

Get funnel

Path Parameters

Responses

Update funnel

Path Parameters

Request Body

Responses

Delete funnel

Path Parameters

Responses

Record funnel reward

Path Parameters

Request Body

Responses

Example