Split Testing API

The Split Testing API lets you programmatically get AI-powered A/B test recommendations and create no-code split tests — all from your AI coding agent or any HTTP client. This is ideal for teams that want to automate conversion rate optimization (CRO) workflows using tools like Claude Code, Cursor, or custom scripts.

Base URL: https://app.humblytics.com/api/external/v1

New to split testing? Read the Split Testing Overview for conceptual background on how Humblytics A/B testing works, goal types, and statistical methodology before diving into the API.

Looking for analytics endpoints? The External Analytics API covers traffic, clicks, and forms data — useful for monitoring experiment performance alongside these split testing endpoints.

---

Use Cases

Automated CRO with AI Agents

The Split Testing API is designed to work hand-in-hand with AI coding agents. Here are the primary use cases:

Use Case	How It Works
AI-driven test ideation	Your agent calls the recommendations endpoint, receives data-backed suggestions (selectors, copy, CSS changes), and presents them for review.
Hands-free experiment creation	After reviewing recommendations, the agent creates a split test via the API — no manual setup in the dashboard required.
Continuous optimization loops	An agent periodically fetches recommendations for key pages, creates tests for high-confidence suggestions, and monitors results via the analytics API.
Multi-page audit	The agent iterates over your top landing pages, fetches recommendations for each, and builds a prioritized optimization backlog.

---

Authentication

Uses the same property-scoped API keys as the External Analytics API.

Authorization: Bearer <your_api_key>

See External Analytics API — Authentication for key generation and management details.

---

Get Split Test Recommendations

GET /properties/{propertyId}/split-test-recommendations

Returns AI-generated A/B test recommendations for a specific page, based on your existing analytics data (traffic patterns, click behavior, bounce rates, and more). Each recommendation includes the exact CSS selector, change type, control value, and suggested variant value — ready to feed directly into the split test creation endpoint.

Query Parameters

Name	Type	Required	Default	Notes
page	string	Yes	N/A	The page path to get recommendations for (e.g. /home, /pricing).

Sample Request

curl \
  -H "Authorization: Bearer $HUMBLYTICS_API_KEY" \
  "https://app.humblytics.com/api/external/v1/properties/PROPERTY_ID/split-test-recommendations?page=/home"

Sample Response

{
  "meta": {
    "property_id": "prop_abc123",
    "page": "/home",
    "page_url": "https://yoursite.com/home"
  },
  "overall_analysis": "Your hero section has high traffic but a 78% bounce rate. The primary CTA is underperforming relative to page views, suggesting copy and visual prominence changes could yield significant gains.",
  "key_insights": [
    "CTA button receives only 3% of clicks despite above-the-fold placement",
    "Users spend an average of 4.2 seconds on the hero section before scrolling",
    "Mobile bounce rate is 12% higher than desktop on this page"
  ],
  "recommendations": [
    {
      "id": "rec_1",
      "title": "Hero CTA Text",
      "element_selector": "button.hero-cta",
      "element_type": "button",
      "change_type": "text",
      "control_value": "Learn More",
      "variant_value": "Start Free Trial",
      "confidence_score": 84,
      "expected_impact": "High: 8%+"
    },
    {
      "id": "rec_2",
      "title": "Hero CTA Color",
      "element_selector": "button.hero-cta",
      "element_type": "button",
      "change_type": "css",
      "control_value": "{ \"backgroundColor\": \"#6b7280\" }",
      "variant_value": "{ \"backgroundColor\": \"#ff6b35\" }",
      "confidence_score": 71,
      "expected_impact": "Medium: 3-8%"
    }
  ]
}

Response Fields

Field	Description
overall_analysis	A human-readable summary of the page's performance and optimization opportunities.
key_insights	Array of specific data-backed observations about user behavior on the page.
recommendations[].id	Unique recommendation ID (useful for logging and tracking).
recommendations[].element_selector	CSS selector for the target element — use this directly in the split test creation endpoint.
recommendations[].element_type	The type of HTML element (e.g. button, heading, image).
recommendations[].change_type	The kind of change: text (copy change) or css (style change).
recommendations[].control_value	The current value on your live page.
recommendations[].variant_value	The suggested new value to test against the control.
recommendations[].confidence_score	0–100 score indicating how confident the AI is that this change will improve performance.
recommendations[].expected_impact	Estimated impact level: Low: <3%, Medium: 3-8%, or High: 8%+.

Notes

• Recommendations are generated from your actual analytics data — they are not generic suggestions.

• Higher confidence_score values indicate stronger data signals behind the recommendation.

• The element_selector and change_type fields map directly to the selector and op fields in the split test creation endpoint, making it easy to pipe recommendations into live experiments.

---

Create a Split Test

POST /properties/{propertyId}/split-tests

Creates and activates a no-code A/B split test. The test injects changes into the page at runtime using the Humblytics script — no code deployment or page duplication required. You define one or more variants, each with a list of element-level changes (text swaps, CSS overrides, or attribute changes).

Request Body

Field	Type	Required	Default	Notes
name	string	Yes	N/A	A descriptive name for the experiment.
page	string	Yes	N/A	The page path to run the test on (e.g. /home).
type	string	Yes	N/A	Test type. Use nocode for API-created tests.
goal	string	Yes	N/A	The optimization goal. See goal options below.
auto_stop_days	number	No	N/A	Automatically stop the test after this many days.
variants	array	Yes	N/A	One or more variant definitions (see below).

Goal Options

Value	Description
click_through	Optimize for click-through rate on the page.
form_submission	Optimize for form submission rate.
bounce_rate	Optimize for reduced bounce rate.
session_time	Optimize for increased session duration.
destination_page	Optimize for visitors reaching a specific page.
external_destination	Optimize for visitors reaching an external URL.
revenue	Optimize for revenue per visitor.

Variant Object

Field	Type	Required	Notes
label	string	Yes	A descriptive label for this variant (e.g. Variant B — new copy).
changes	array	Yes	One or more changes to apply. See below.

Change Object

Field	Type	Required	Notes
selector	string	Yes	CSS selector for the target element.
op	string	Yes	The operation: text (replace text content), css (apply CSS styles), or attr (set an HTML attribute).
value	string or object	Yes	The new value. For css, pass a JSON object of CSS properties. For text and attr, pass a string.

Sample Request

curl -X POST \
  -H "Authorization: Bearer $HUMBLYTICS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Hero CTA Optimization",
    "page": "/home",
    "type": "nocode",
    "goal": "click_through",
    "auto_stop_days": 14,
    "variants": [
      {
        "label": "Variant B — new copy + color",
        "changes": [
          {
            "selector": "button.hero-cta",
            "op": "text",
            "value": "Start Free Trial"
          },
          {
            "selector": "button.hero-cta",
            "op": "css",
            "value": { "backgroundColor": "#ff6b35" }
          }
        ]
      }
    ]
  }' \
  "https://app.humblytics.com/api/external/v1/properties/PROPERTY_ID/split-tests"

Sample Response (201 Created)

{
  "experiment_id": "exp_xyz789",
  "name": "Hero CTA Optimization",
  "status": "active",
  "created_at": "2026-03-27T10:00:00.000Z",
  "variants": [
    {
      "label": "Control",
      "is_control": true,
      "changes": []
    },
    {
      "label": "Variant B — new copy + color",
      "is_control": false,
      "changes": [
        { "selector": "button.hero-cta", "op": "text", "value": "Start Free Trial" },
        { "selector": "button.hero-cta", "op": "css", "value": { "backgroundColor": "#ff6b35" } }
      ]
    }
  ]
}

Notes

• A Control variant is automatically created — you only need to define the variants you want to test against it.

• The test goes active immediately upon creation. Visitors will start being assigned to variants right away.

• Changes are applied at runtime by the Humblytics script. No code changes or redeployments are needed on your site.

• You can combine multiple changes per variant (e.g. text + CSS on the same element, or changes across multiple elements).

• Use auto_stop_days to prevent tests from running indefinitely. If omitted, the test runs until manually stopped.

---

End-to-End Workflow: Recommendations to Live Test

The most powerful pattern is chaining both endpoints — fetch recommendations, then create a test from the highest-confidence suggestion:

Step 1 — Get Recommendations

curl \
  -H "Authorization: Bearer $HUMBLYTICS_API_KEY" \
  "https://app.humblytics.com/api/external/v1/properties/PROPERTY_ID/split-test-recommendations?page=/home"

Review the recommendations array. Pick the entries with the highest confidence_score values.

Step 2 — Create the Split Test

Use the element_selector as the selector and change_type as the op:

curl -X POST \
  -H "Authorization: Bearer $HUMBLYTICS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Hero CTA Optimization",
    "page": "/home",
    "type": "nocode",
    "goal": "click_through",
    "auto_stop_days": 14,
    "variants": [
      {
        "label": "Variant B — new copy + color",
        "changes": [
          {
            "selector": "button.hero-cta",
            "op": "text",
            "value": "Start Free Trial"
          },
          {
            "selector": "button.hero-cta",
            "op": "css",
            "value": { "backgroundColor": "#ff6b35" }
          }
        ]
      }
    ]
  }' \
  "https://app.humblytics.com/api/external/v1/properties/PROPERTY_ID/split-tests"

Step 3 — Monitor Results

Use the External Analytics API and the Humblytics dashboard to track experiment performance over time.

---

Using the Split Testing API with AI Agents

The Split Testing API is purpose-built for AI agent workflows. Below are ready-to-use instructions for the most popular AI coding tools. You can also find pre-filled versions of these instructions (with your property ID and API key already populated) in the Humblytics dashboard under Utilities → API Access → AI Agent Instructions.

Claude Code

Add the following to your project's CLAUDE.md file or paste it into your Claude Code session. Replace PROPERTY_ID with your actual property ID:

## Humblytics API

You have access to the Humblytics API for analytics and A/B testing. Use curl via the Bash tool to call these endpoints.

- Base URL: https://app.humblytics.com/api/external/v1
- Property ID: PROPERTY_ID
- API Key: stored in environment variable HUMBLYTICS_API_KEY
- Auth header: Authorization: Bearer $HUMBLYTICS_API_KEY

### Split Testing Endpoints

1. GET /properties/{propertyId}/split-test-recommendations?page={page}
   - Returns AI-powered A/B test recommendations for a page
   - Response includes: overall_analysis, key_insights, recommendations[] with element_selector, change_type (text|css), control_value, variant_value, confidence_score (0-100), expected_impact

2. POST /properties/{propertyId}/split-tests
   - Creates and activates a no-code A/B split test (goes live immediately)
   - Body: { name, page, type: "nocode", goal, auto_stop_days, variants: [{ label, changes: [{ selector, op, value }] }] }
   - Goal options: click_through, form_submission, bounce_rate, session_time, destination_page, external_destination, revenue
   - Map recommendation fields: element_selector → selector, change_type → op, variant_value → value

### Analytics Endpoints (for monitoring)

3. GET /properties/{propertyId}/traffic/trends?start={date}&end={date}&granularity=day
   - Time-series page views and unique visitors

4. GET /properties/{propertyId}/traffic/breakdown?start={date}&end={date}&limit=20
   - Top traffic segments: UTM, countries, devices, landing pages, referrers

5. GET /properties/{propertyId}/clicks/breakdown?start={date}&end={date}
   - Click events grouped by page and target

6. GET /properties/{propertyId}/forms/breakdown?start={date}&end={date}
   - Form submissions grouped by page and form target

### Workflow

When asked to optimize a page or run an A/B test:
1. Fetch recommendations for the target page using the recommendations endpoint
2. Present the recommendations to the user with confidence scores and expected impact
3. Ask which recommendations to implement (or suggest high-confidence ones above 70)
4. Create the split test using the selectors and values from the chosen recommendations
5. Confirm the experiment is active and provide the experiment ID

When asked to check analytics or site performance:
1. Use the traffic/trends endpoint for time-series data
2. Use traffic/breakdown for segment analysis
3. Use clicks/breakdown or forms/breakdown for event-level data

Cursor

Add the following to your project's .cursor/rules file or .cursorrules. Replace PROPERTY_ID with your actual property ID:

## Humblytics API

You have access to the Humblytics API for analytics and A/B testing. Call these endpoints using curl or fetch.

- Base URL: https://app.humblytics.com/api/external/v1
- Property ID: PROPERTY_ID
- API Key: stored in environment variable HUMBLYTICS_API_KEY
- Auth header: Authorization: Bearer $HUMBLYTICS_API_KEY

### Split Testing Endpoints

1. GET /properties/{propertyId}/split-test-recommendations?page={page}
   - Returns AI-powered A/B test recommendations for a page
   - Response includes: overall_analysis, key_insights, recommendations[] with element_selector, change_type (text|css), control_value, variant_value, confidence_score (0-100), expected_impact

2. POST /properties/{propertyId}/split-tests
   - Creates and activates a no-code A/B split test (goes live immediately)
   - Content-Type: application/json
   - Body: { name, page, type: "nocode", goal, auto_stop_days, variants: [{ label, changes: [{ selector, op, value }] }] }
   - Goal options: click_through, form_submission, bounce_rate, session_time, destination_page, external_destination, revenue
   - Map recommendation fields: element_selector → selector, change_type → op, variant_value → value

### Analytics Endpoints (for monitoring)

3. GET /properties/{propertyId}/traffic/trends?start={date}&end={date}&granularity=day
4. GET /properties/{propertyId}/traffic/breakdown?start={date}&end={date}&limit=20
5. GET /properties/{propertyId}/clicks/breakdown?start={date}&end={date}
6. GET /properties/{propertyId}/forms/breakdown?start={date}&end={date}

### Workflow

When asked to optimize a page or run an A/B test:
1. Fetch recommendations for the target page
2. Present recommendations with confidence scores and expected impact
3. Ask which to implement (or suggest high-confidence ones above 70)
4. Create the split test using selectors and values from chosen recommendations
5. Confirm the experiment is active and provide the experiment ID

Generic (Any AI Agent)

For any other AI coding assistant, provide these instructions in its system prompt or project context:

You can interact with the Humblytics API to get data-driven A/B test recommendations,
create no-code experiments, and query analytics data.

Base URL: https://app.humblytics.com/api/external/v1
Auth: Bearer token via Authorization header

SPLIT TESTING:

STEP 1 — Get recommendations:
GET /properties/{propertyId}/split-test-recommendations?page={page}
Returns: overall_analysis, key_insights, and recommendations[] with element_selector,
change_type (text|css), control_value, variant_value, confidence_score, expected_impact.

STEP 2 — Create a split test:
POST /properties/{propertyId}/split-tests
Content-Type: application/json
Body: {
  "name": "...",
  "page": "/...",
  "type": "nocode",
  "goal": "click_through|form_submission|bounce_rate|session_time|destination_page|external_destination|revenue",
  "auto_stop_days": 14,
  "variants": [{
    "label": "Variant B",
    "changes": [{ "selector": "...", "op": "text|css|attr", "value": "..." }]
  }]
}
Returns: experiment_id, status, variants[] with control auto-created.

Map recommendation fields to split test fields:
  element_selector → selector
  change_type → op
  variant_value → value

ANALYTICS (for monitoring):
GET /properties/{propertyId}/traffic/trends?start={date}&end={date}&granularity=day
GET /properties/{propertyId}/traffic/breakdown?start={date}&end={date}&limit=20
GET /properties/{propertyId}/clicks/breakdown?start={date}&end={date}
GET /properties/{propertyId}/forms/breakdown?start={date}&end={date}

All endpoints require start and end dates in ISO-8601 format and an optional timezone parameter.

Always present recommendations to the user before creating tests.

Example Agent Conversation

Here is what a typical interaction looks like when an AI agent uses the Split Testing API:

User: "Optimize my homepage for more signups"

Agent workflow:

1. The agent calls GET /properties/prop_abc123/split-test-recommendations?page=/home and receives 3 recommendations.

2. The agent presents them:

   I found 3 optimization recommendations for /home:

   1. Hero CTA Text (confidence: 84) — Change "Learn More" → "Start Free Trial" — Expected impact: High (8%+)

   2. Hero CTA Color (confidence: 71) — Change gray background → orange — Expected impact: Medium (3-8%)

   3. Subheading Copy (confidence: 58) — Shorten subheading from 2 lines to 1 — Expected impact: Low (<3%)

   I'd recommend testing #1 and #2 together since they both target the hero CTA and have high confidence. Want me to create this experiment?

3. User confirms. The agent calls POST /properties/prop_abc123/split-tests with the selected recommendations mapped to a variant.

4. The agent confirms:

   Experiment created and live! ID: exp_xyz789. It will auto-stop after 14 days. You can monitor results in the Humblytics dashboard under Experiments.

---

Errors

The Split Testing API uses the same error format as the External Analytics API.

Status	Code	When it happens
400	invalid_request	Missing required fields, invalid page path, unsupported goal type, or malformed variant data.
401	unauthorized	Missing or invalid API key header.
403	forbidden	Property ID does not match the API key.
404	not_found	The specified page has no analytics data (recommendations endpoint only).
429	rate_limited	Too many requests in a short window.
500	internal_error	Unexpected server error. Retry later or contact support.

---

Best Practices

• Start with recommendations. Always fetch recommendations before creating a test — they are based on your actual data and give you the highest-probability wins.

• Test one hypothesis at a time. While you can bundle multiple changes into a single variant, keep tests focused so you can attribute results clearly.

• Set auto-stop durations. Use auto_stop_days to prevent experiments from running longer than needed. 14 days is a good default for most sites.

• Use high-confidence recommendations first. Prioritize recommendations with confidence_score above 70 for the best chance of statistically significant results.

• Monitor with the analytics API. Combine the Split Testing API with the External Analytics API to track experiment performance programmatically.

• Review before launching. When using AI agents, always review recommendations before creating tests — the agent should present options and ask for confirmation.