API Documentation

The Experiment Flow API lets you run A/B tests and multi-armed bandits programmatically.

Authentication

All API requests require authentication. Include your API key in one of these ways:

X-API-Key: YOUR_API_KEY
Authorization: Bearer YOUR_API_KEY
?api_key=YOUR_API_KEY

Quick Start

Create an experiment and start tracking in 3 steps:

# 1. Create experiment
curl -X POST https://experimentflow.com/api/experiments \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "CTA Test", "variants": ["control", "variant_a"]}'

# 2. Get variant for visitor
curl "https://experimentflow.com/api/decide?experiment_id=1&visitor_id=user123&api_key=YOUR_API_KEY"

# 3. Track conversion
curl -X POST https://experimentflow.com/api/convert \
  -H "X-API-Key: YOUR_API_KEY" \
  -d '{"experiment_id": 1, "visitor_id": "user123"}'

Storage & Privacy

Experiment Flow is designed for privacy compliance. Here's how data is stored:

Client-Side (JavaScript SDK)

No cookies are used for tracking. The SDK uses localStorage only, making it GDPR/CCPA compliant without cookie consent banners for A/B testing.

Dashboard Authentication

This cookie is only set when you log into the dashboard. It's not used for visitor tracking.

Backend SDK

When using the Backend SDK, you manage user IDs yourself. No cookies or localStorage are involved - you pass the user_id directly in API calls.

JavaScript SDK Installation

Add the SDK to your website with a single script tag:

<script src="https://experimentflow.com/sdk.js"
        data-optimize-key="YOUR_API_KEY"></script>

Or initialize manually for more control:

<script src="https://experimentflow.com/sdk.js"></script>
<script>
  var ef = new ExperimentFlow({
    apiKey: 'YOUR_API_KEY',
    debug: true  // Enable console logging
  });
</script>

JavaScript SDK Usage

Get Variant

// Get variant for an experiment
ef.getVariant(1, function(variant) {
  if (variant === 'control') {
    // Show original
  } else if (variant === 'variant_a') {
    // Show variation
  }
});

// Or use the helper
ef.onVariant(1, {
  'control': function() { /* original */ },
  'variant_a': function() { document.querySelector('.cta').textContent = 'Buy Now!'; }
});

Track Conversion

// Track conversion for specific experiment
ef.convert(1);

// Track with value (e.g., order amount)
ef.convert(1, 49.99);

// Track with goal name
ef.convert(1, 49.99, 'purchase');

// Convert all active experiments
ef.convertAll(49.99, 'purchase');

DOM Modifications

// Automatically modify DOM based on variant
ef.activate(1, {
  'control': {},
  'variant_a': {
    '.hero-title': { text: 'New Headline!' },
    '.cta-button': { style: { backgroundColor: 'green' } },
    '.old-section': { hide: true }
  }
});

Set User ID (Cross-Device)

// After user logs in
ef.setUserId('user_12345');

// Now experiments sync across devices

Shopify Integration

The SDK includes built-in Shopify support with automatic event tracking:

// Initialize with Shopify support
ef.initShopify();

// Automatically tracks:
// - Add to cart (with product value)
// - Checkout start
// - Page context (product type, collection, etc.)

// Manual tracking on thank you page
ef.trackPurchase({ total_price: 9999 }); // Price in cents

// Test add-to-cart button variants
ef.testAddToCart(1, {
  'control': { text: 'Add to Cart' },
  'variant_a': { text: 'Buy Now - Free Shipping!', style: { backgroundColor: '#00aa00' } }
});

Backend SDK Overview

Run A/B tests entirely on your server without any client-side code. Perfect for:

• API response variations
• Pricing experiments
• Algorithm testing
• Email subject lines
• Feature flags

The Backend SDK uses your user_id for consistent assignment. No cookies or localStorage needed.

Python Example

import requests

API_KEY = "YOUR_API_KEY"
BASE_URL = "https://experimentflow.com"

def get_variant(experiment_key: str, user_id: str) -> str:
    """Get variant assignment for a user."""
    resp = requests.post(
        BASE_URL + "/api/backend/decide",
        headers={"X-API-Key": API_KEY},
        json={"experiment_key": experiment_key, "user_id": user_id}
    )
    return resp.json().get("variant", "control")

def track_conversion(experiment_key: str, user_id: str, revenue: float = None):
    """Track a conversion event."""
    requests.post(
        BASE_URL + "/api/backend/convert",
        headers={"X-API-Key": API_KEY},
        json={
            "experiment_key": experiment_key,
            "user_id": user_id,
            "revenue": revenue
        }
    )

# Usage in your app
@app.route("/checkout")
def checkout():
    user_id = get_current_user_id()

    variant = get_variant("checkout_flow", user_id)

    if variant == "new_checkout":
        return render_template("checkout_v2.html")
    return render_template("checkout.html")

@app.route("/purchase", methods=["POST"])
def purchase():
    user_id = get_current_user_id()
    order_total = calculate_order_total()

    track_conversion("checkout_flow", user_id, revenue=order_total)
    return jsonify({"status": "ok"})

Node.js Example

const API_KEY = 'YOUR_API_KEY';
const BASE_URL = 'https://experimentflow.com';

async function getVariant(experimentKey, userId) {
  const resp = await fetch(BASE_URL + '/api/backend/decide', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'X-API-Key': API_KEY
    },
    body: JSON.stringify({ experiment_key: experimentKey, user_id: userId })
  });
  const data = await resp.json();
  return data.variant || 'control';
}

async function trackConversion(experimentKey, userId, revenue) {
  await fetch(BASE_URL + '/api/backend/convert', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'X-API-Key': API_KEY
    },
    body: JSON.stringify({
      experiment_key: experimentKey,
      user_id: userId,
      revenue: revenue
    })
  });
}

// Express.js example
app.get('/api/pricing', async (req, res) => {
  const userId = req.user.id;
  const variant = await getVariant('pricing_test', userId);

  const prices = {
    control: { monthly: 29, annual: 290 },
    annual_first: { monthly: 29, annual: 249 }
  };

  res.json(prices[variant] || prices.control);
});

app.post('/api/subscribe', async (req, res) => {
  const { plan, amount } = req.body;
  await trackConversion('pricing_test', req.user.id, amount);
  // ... process subscription
});

Go Example

package main

import (
    "bytes"
    "encoding/json"
    "net/http"
)

const apiKey = "YOUR_API_KEY"
const baseURL = "https://experimentflow.com"

type DecideResponse struct {
    Variant string
}

func getVariant(experimentKey, userID string) (string, error) {
    body, _ := json.Marshal(map[string]string{
        "experiment_key": experimentKey,
        "user_id":        userID,
    })

    req, _ := http.NewRequest("POST", baseURL+"/api/backend/decide", bytes.NewBuffer(body))
    req.Header.Set("Content-Type", "application/json")
    req.Header.Set("X-API-Key", apiKey)

    resp, err := http.DefaultClient.Do(req)
    if err != nil {
        return "control", err
    }
    defer resp.Body.Close()

    var result DecideResponse
    json.NewDecoder(resp.Body).Decode(&result)
    return result.Variant, nil
}

func trackConversion(experimentKey, userID string, revenue float64) error {
    body, _ := json.Marshal(map[string]interface{}{
        "experiment_key": experimentKey,
        "user_id":        userID,
        "revenue":        revenue,
    })

    req, _ := http.NewRequest("POST", baseURL+"/api/backend/convert", bytes.NewBuffer(body))
    req.Header.Set("Content-Type", "application/json")
    req.Header.Set("X-API-Key", apiKey)

    _, err := http.DefaultClient.Do(req)
    return err
}

// Usage
func handleCheckout(w http.ResponseWriter, r *http.Request) {
    userID := getUserID(r)
    variant, _ := getVariant("checkout_flow", userID)

    switch variant {
    case "streamlined":
        renderTemplate(w, "checkout_v2.html")
    default:
        renderTemplate(w, "checkout.html")
    }
}

Get Current User

{
  "id": 1,
  "email": "[email protected]",
  "team_id": 1,
  "team_name": "My Team",
  "role": "owner",
  "plan": "pro"
}

Regenerate API Key

{
  "api_key": "opt_new_key_here"
}

List Experiments

Create Experiment

Get Experiment Statistics

{
  "experiment_id": 1,
  "experiment_name": "CTA Test",
  "status": "running",
  "total_visitors": 1000,
  "total_conversions": 120,
  "variants": [
    {"variant": "control", "visitors": 500, "conversions": 50, "conversion_rate": 0.10},
    {"variant": "variant_a", "visitors": 500, "conversions": 70, "conversion_rate": 0.14}
  ],
  "significance": {
    "is_significant": true,
    "confidence": 95.2,
    "p_value": 0.048,
    "z_score": 1.98
  },
  "winner": "variant_a",
  "improvement": 40.0
}

Promote Winner

Archive Experiment

Delete Experiment

Get Variant Assignment

{
  "variant": "variant_a",
  "visitor_id": "user_abc123",
  "in_test": true
}

Batch Decide (Multiple Experiments)

{
  "variants": {
    "1": "control",
    "2": "variant_a",
    "3": "variant_b"
  },
  "visitor_id": "user_abc123"
}

Track Conversion

Track Custom Event

Feature Flag (Backend SDK)

{
  "enabled": true,
  "variant": "new_checkout",
  "experiment_id": 1,
  "in_test": true
}

Backend Decide

{
  "variant": "treatment_a",
  "experiment_id": 1,
  "user_id": "user_12345",
  "in_test": true
}

Backend Batch Decide

{
  "variants": {
    "checkout_flow": {"variant": "new_checkout", "in_test": true, "experiment_id": 1},
    "pricing_test": {"variant": "annual_first", "in_test": true, "experiment_id": 2}
  },
  "user_id": "user_12345"
}

Backend Convert

{
  "status": "ok",
  "experiment_id": 1,
  "user_id": "user_12345",
  "variant": "treatment_a",
  "value": 99.99
}

Experiment Status

{
  "id": 1,
  "name": "Checkout Flow",
  "status": "running",
  "variants": ["control", "new_checkout"],
  "total_visitors": 1500,
  "total_conversions": 180,
  "conversion_rate": 0.12,
  "is_significant": true,
  "confidence": 95.2,
  "traffic_percent": 100,
  "auto_promote": true,
  "auto_promote_threshold": 0.95
}

Experiment by Key

{
  "id": 1,
  "name": "checkout_flow",
  "status": "running",
  "variants": ["control", "new_checkout"],
  "winner": ""
}

List Bandits

Create Bandit

Select Bandit Arm

Record Bandit Reward

Get Team

Invite Team Member

List Personalizers

Create Personalizer

Rank Actions

{
  "ranked_actions": [
    {"id": "product_3", "score": 0.85},
    {"id": "product_1", "score": 0.72},
    {"id": "product_2", "score": 0.45}
  ],
  "event_id": "evt_abc123"
}

Record Personalizer Reward

Get Credit Balance

{
  "balance": 50.00,
  "currency": "USD"
}

Top Up Credits

Get Subscription

{
  "plan": "pro",
  "seats": 3,
  "experiments_used": 5,
  "experiments_limit": 0,
  "events_used": 15000,
  "events_limit": 1000000
}

Start Checkout

{
  "checkout_url": "https://checkout.stripe.com/...",
  "client_secret": "cs_..."
}