Apex by DripBothUpdated June 2, 2026

Documentation for the whole Apex tool.

Apex is an experimentation platform for agencies and ecommerce teams: install once, capture trustworthy signals, build variants with Operator or code, QA every change, launch experiments, read results, and feed the learning back into the next decision.

Get startedBoth

The shortest path from empty workspace to a live test

Use this sequence for a new store or client. It keeps setup, measurement, targeting, build, QA, and result readback in order.

1

Create or select the workspace

Apex supports company workspaces for one brand and agency workspaces for multiple client stores. Use the workspace switcher before changing a store, team, or experiment.

Open section
2

Connect the store

For Shopify, connect the app, approve scopes, enable the theme app embed, and verify the Web Pixel. For custom sites, install the SDK snippet from Store Connection.

Open section
3

Create foundations

Add metrics, reusable audiences, assets, and store profile evidence before building tests. This gives Operator and reporting enough context to make better decisions.

Open section
4

Build a first experiment

Create the test, choose the surface and audience, add variants, attach a primary metric, run QA, then start the experiment.

Open section
5

Read results and compound learning

Use Results and Analytics to inspect lift, revenue, funnels, heatmaps, and imported outcomes. Store the learning so the next idea starts smarter.

Open section
Product shotsBoth

What the product looks like in practice

These screenshots are captured from the local app and stored as documentation assets. They show the real dashboard surfaces rather than abstract diagrams.

Launchpad product screenshot

Launchpad

The daily command surface for setup, next moves, active tests, and learning proof.

Experiment inventory product screenshot

Experiment inventory

Drafts, live tests, blockers, status filters, and launch readiness in one list.

Analytics overview product screenshot

Analytics overview

Visitor, conversion, revenue, funnel, traffic, and real-time reporting surfaces.

Store profile product screenshot

Store profile

Brand, technical setup, product-data depth, and operator learnings.

Documentation product screenshot

Documentation

The docs system itself, using the supplied Apex Docs design language.

OperateOperator

The Apex operating workflow

The tool is organized around a repeatable loop: collect evidence, select the next idea, build the experiment, QA the runtime, launch, read the result, and store the learning.

Launchpad

Operator

Start here each day. Launchpad summarizes the active shop, readiness stage, recommended next move, drafts that need action, active tests, and recent learning proof.

  • Use the highlighted next move when priorities are unclear.
  • Scan readiness before pushing any test into QA.
  • Jump to store profile, ideas, experiments, or results from one surface.
Open in app

Ideas

Operator

The backlog collects experiment ideas, imported Research Hub items, comments, priorities, source context, and handoff actions.

  • Create ideas manually or import them from research sources.
  • Attach page context, evidence, and owner notes.
  • Create an experiment directly from a qualified idea.
Open in app

Experiments

Both

The experiment area manages drafts, live tests, archived tests, goals, variants, targeting, schedules, launch blockers, and status transitions.

  • Drafts must have a page or audience, variants, and at least one primary metric.
  • Running tests can be paused, completed, archived, restored, or converted into flags.
  • Experiment detail pages expose setup progress, analytics, QA, and developer fields.
Open in app

Apex Operator

Both

Operator is the model-led builder. It uses compact tools for page inspection, browser state, network activity, selector work, artifacts, QA, and persistence.

  • Prefer general tool affordances over narrow playbooks.
  • Use Operator to inspect the page, propose changes, build variants, and collect QA evidence.
  • Review Operator Logs when you need transcripts, tool timelines, artifacts, or failure states.
Open in app

Launchpad

Operator

Launchpad is the home route for an active shop. It answers what is ready, what is blocked, and what should happen next.

  • Shop stage: setup, launch, active learning, or readback mode.
  • Next-move recommendation with reason, destination, and confidence.
  • Setup checks for store signals, profile quality, goals, audiences, QA, and active experiments.
  • Draft and active experiment summaries with compact proof from recent learning.
  • Links into backlog, store profile, experiments, analytics, and results.

Ideas and backlog

Operator

Ideas are the source material for the experiment program. They can come from research, team notes, Operator analysis, or manual input.

  • Backlog list with status, priority, source, owner, comments, archive, and restore.
  • New idea form for title, evidence, hypothesis, target surface, and expected impact.
  • Detail view with comments, page context, Research Hub metadata, Codex handoff, and create-experiment action.
  • Import route for Research Hub backlog items.
  • Apex Operator can consume backlog context when drafting variants.

Experiments

Both

Experiments are the central testing object. A test contains targeting, traffic allocation, variants, metrics, QA state, schedule, and runtime status.

  • Experiment inventory with live, draft, paused, completed, archived, and scheduled states.
  • New experiment flow for name, description, URL or audience targeting, traffic allocation, planned test settings, and goals.
  • Detail page with setup progress, launch blockers, goals, variants, status actions, QA, analytics, and source backlog item.
  • Actions include start, pause, complete, archive, restore, duplicate via API, and create feature flag from experiment.
  • Conflict API checks overlapping experiments before launch.

Variant builder and workbench

Both

The variant builder is where storefront changes are authored and verified. It supports mutation mode, code mode, preview runtime, revision history, and Operator-assisted build flows.

  • Visual changes: text, HTML, style, attributes, remove, insert before, and insert after mutations.
  • Code mode: custom files, preview build status, direct code edits, saved workspace, and show-preview controls.
  • Operator chat: model-led page inspection, selector discovery, network checks, mutation authoring, and QA evidence.
  • Revisions: list saved revisions and inspect diffs.
  • Preview sessions: forced variants, host checks, page-state summaries, and persistent preview artifacts.

QA and launch

Both

QA verifies that a variation renders correctly, the forced URL works, and the tracking path is trustworthy before traffic starts.

  • Experiment QA status and goal-verification endpoints.
  • QA run endpoint for Operator-style audit packets and fix options.
  • Screenshot jobs across desktop, iPhone, and iPad devices.
  • Preview evidence and operator evidence APIs for persisted artifacts.
  • Launch panel with blockers, guardrails, schedule, and start action.

Results

Operator

Results captures what happened after an experiment runs. It supports Apex-tracked outcomes and imported external test results.

  • Test Results route for readback and imported outcomes.
  • Import preview and confirm endpoints for external data.
  • Experiment analytics for visitors, conversions, revenue, behavior, heatmaps, and screenshots.
  • Always-valid sequential settings and planned fixed-horizon snapshots.
  • Completed test outcomes feed learning summaries and future backlog decisions.
FoundationsBoth

The reusable objects every experiment depends on

Foundations make the program repeatable. They let teams reuse metrics, audiences, signals, evidence, assets, and store knowledge instead of rebuilding setup for every test.

Metrics

Operator

Create click, pageview, custom, revenue, and Shopify-connected goals. Goals can capture element text, attributes, or dataset values and can be primary or secondary inside experiments.

Open in app

Audiences

Both

Reusable visitor and page groups for experiments now and personalization later. Rules cover pages, traffic, behavior, customer signals, exact URLs, wildcards, and regex patterns.

Open in app

Signals

Operator

Signals capture evidence used by Operator and personalization: customer behavior, store profile facts, Research Hub imports, finding reviews, semantic sequences, and learning runs.

Open in app

Store profile

Operator

A structured brand and technical memory for a shop. It includes profile facts, audit findings, storefront checks, product-data depth, operator learning, and review workflow.

Open in app

Assets

Both

Upload and organize images, PDFs, and reference files for experiments, landing pages, and AI prompts. Asset usage can be queried through the assets API.

Open in app

Pages

Both

Legacy page targeting redirects into the current audience system. The runtime still supports exact, wildcard, and regex URL matching.

Open in app
AnalyticsOperator

Reporting surfaces

Analytics covers store-wide data, experiment data, funnel behavior, traffic source quality, visitor records, real-time debugging, and measurement quality.

SurfaceUse it forRoute
OverviewCore dashboard analytics across visitors, conversions, revenue, ecommerce, geo, sessions, entry and exit, and measurement quality.Open
AudienceVisitor and audience analysis for segment readback and future personalization work.Open
TrafficTraffic source breakdowns and attribution context.Open
VisitorsVisitor explorer for sessions, event trails, and identifiers.Open
RealtimeLive event console for debugging install and tracking behavior.Open
FunnelsBuild and run funnels from detected pages, then analyze breakdowns.Open
FlowPath-flow and journey analysis for entry, exit, and movement between pages.Open
AdvancedBoth

Flags, personalization, landing pages, and runtime extensions

These surfaces extend Apex beyond classic A/B testing. They use the same targeting and runtime primitives, but serve rollout, personalization, and generated-page workflows.

Landing pages

Operator

Create AI-assisted landing pages, render versions, publish them, chat with page-specific tools, and run QA on published variants.

Open in app

Feature flags

Developer

Native Apex flags with off/on variants, typed payloads, rollout percentage, targeting, decision debugger, activate, pause, and archive actions.

Open in app

Personalization

Both

Signal-driven storefront experiences with ordered matching rules, safe rollout, value payloads, runtime targeting, and decision debugger.

Open in app

External pixels

Developer

Generate external pixel snippets for non-standard tracking needs.

Open in app
AdminAdmin

Configuration and account administration

Admin surfaces control installation, team access, integrations, guardrails, API keys, webhooks, workspace settings, and operational observability.

Store connection

Admin

Shopify OAuth, app embed, manual snippet, runtime settings, edge routing, snippet size, and install verification.

Open in app

Guardrails

Admin

Shop-wide auto-pause defaults, sequential significance settings, planned test defaults, minimum runtime, and decision behavior.

Open in app

Profit analysis

Admin

Shopify reconnect and data scopes for product, inventory, order, cost, reconciliation, and contribution-margin reporting.

Open in app

Team and organization

Admin

Store team invites, agency team members, workspace settings, ownership transfer, leave workspace, and active org switching.

Open in app

API keys

Admin

Create publishable, test secret, and live secret keys. Full secrets are shown once. Permissions and expiration are configured on creation.

Open in app

Webhooks

Admin

Create endpoints, subscribe to events, inspect delivery attempts, rotate secrets by recreating webhooks, and debug failed deliveries.

Open in app

Internal admin routes

The /admin area is for operational owners. It includes usage, queues, API access, model usage, database status, release metadata, public monitors, SDK performance, Sentry issues, and test runners.
DevelopersDeveloper

Install and runtime model

Apex serves experiment configuration through the public /api/exp endpoint, applies browser DOM mutations through Apex Runtime, and sends event batches to the Cloudflare Worker for Tinybird analytics.

Runtime path

Apex Runtime initializes with the shop ID, fetches experiments and goals, assigns visitors with cookie persistence, applies targeting and mutations, tracks goals, and flushes batched events to the Worker.
  • Cloudflare Worker forwards normalized NDJSON events to Tinybird.
  • Dashboard APIs use Prisma against Supabase Postgres.
  • Public API v1 uses bearer API keys and JSON payloads.
  • Custom hostname traffic can route through edge.drip-apex.com for Worker handling.
  • Snippet delivery supports precompiled config and runtime settings.
Runtime snippet
<!-- Add before your closing </head> tag -->
<script>
  window.Drip=window.Drip||{q:[],init(c){this.q.push(["init",c])},track(e,p){this.q.push(["track",e,p])}}
</script>
<script async src="https://drip-sdk.pages.dev/drip.js"></script>
<script>
  Drip.init({
    shopId: "shop_uuid",
    workerUrl: "https://events.drip-apex.com"
  })
</script>
DevelopersDeveloper

Apex Runtime behavior

Apex Runtime initializes Apex on the storefront, resolves config, persists assignments, applies DOM changes, tracks events, handles anti-flicker, and batches network calls.

Track custom events
Drip.track("add_to_cart", {
  product_id: "gid://shopify/Product/123",
  value: 49.00,
  currency: "EUR"
});
Configuration endpoint
GET /api/exp?shop_id=shop_uuid

{
  "experiments": [...],
  "goals": [...],
  "worker_url": "https://events.drip-apex.com"
}

Assignment

Sticky cookie persistence keeps visitors in the same variation.

Mutations

Text, HTML, attributes, styles, inserts, removals, CSS, and JS are applied idempotently.

Goal tracking

Clicks, pageviews, custom events, revenue, and captured element values are sent as events.

Page targeting

Exact, wildcard, regex, and segment-backed URL rules decide eligibility.

Batching

Events flush every five seconds or when twenty events accumulate.

Anti-flicker

Scoped or full-page masking prevents content flash while variants apply.

DevelopersDeveloper

Public API model

The public API exposes experiments, variations, goals, screenshots, webhooks, conflict checks, generated experiments, data export, data deletion, and harness session publishing.

Authentication

Create API keys in the dashboard. Send secret keys as Authorization: Bearer apx_sk_live_…. Full secret values are shown once when created.

Experiments

Create, update, start, pause, complete, duplicate, generate, fetch by slug, and check conflicts.

Variations

Create, update, generate, and manage mutation payloads.

Goals

Create and update metrics attached to experiments.

Screenshots

Request screenshot jobs and poll job status.

Harness

Create sessions, publish versions, and persist external test artifacts.

Privacy

Data export and data deletion endpoints support compliance workflows.

Base request
curl https://app.drip-apex.com/api/v1/experiments \
  -H "Authorization: Bearer apx_sk_live_..."
DevelopersDeveloper

Webhooks

Webhooks let external systems receive experiment and platform events as they happen. They are configured per shop and delivered with signed secrets.

Webhook dashboard

Developer

Create endpoints, choose subscribed events, enable or disable delivery, and inspect recent attempts.

Open in app

Delivery security

Developer

Store the signing secret when the webhook is created. Recreate the webhook if you need a new secret or endpoint.

Open in app
SupportBoth

Troubleshooting guide

Start with the symptom, then check the associated setup surface. Most issues are install, targeting, selector, goal, or credential problems.

The storefront does not load Apex

Check Store Connection first. Shopify stores need the app embed enabled. Manual installs need the SDK URL in the head and the correct shop ID.

Events are missing

Use Realtime Analytics and browser console checks. Confirm the SDK initialized, consent allows tracking, and the Worker URL is reachable.

A goal is not converting

For click goals, verify selector and text matching. For Shopify goals, confirm pixel event settings and that the metric is the Shopify-connected goal.

A variant does not show in QA

Confirm the forced preview URL, targeting eligibility, saved mutation, app embed status, and that the variation is not still empty.

Profit analysis is unavailable

Reconnect Shopify and approve product, inventory, and order read scopes. Old installs may need a reconnect before contribution data appears.

The API returns 401

Use a secret API key in the Authorization header. Existing keys only show their prefix, so create a new key if the full secret was lost.

ReferenceBoth

Feature manuals

This is the product manual layer: every major Apex feature is explained by what it does, how it works internally, how to use it, what data and APIs power it, and what usually breaks.

29 end-to-end feature manuals

The route catalog below is exhaustive at the page level. These manuals are intentionally broader: they group related pages, APIs, models, SDK behavior, and operational checks into the way a real user or developer understands the tool.

Access, authentication, and workspace selection

Both

Simple termsThis is the front door and tenant switchboard. It decides who is signed in, what workspace they belong to, and which shop every action applies to.

Controls who can enter Apex, which workspace they operate in, and which shop becomes active for every dashboard and API action.

/login/signup/verify-email/auth/reset-password/orgs/new/shops/new

Implementation behavior

  • Supabase Auth creates and refreshes the user session; protected dashboard routes require that session before rendering.
  • Apex stores the active shop in the `drip_active_shop` httpOnly cookie so server components and route handlers resolve the same tenant.
  • Company workspaces focus on one brand; agency workspaces add client management and cross-client navigation.
  • Shop records hold the storefront domain, display name, owner, worker URL, and integration metadata used by the runtime.

How to use it

  • Sign up or log in, verify email, then create or join a workspace.
  • Create a shop before creating goals, experiments, audiences, API keys, or webhooks.
  • Use the workspace and shop switchers before making changes for a client or brand.
  • Accept store or organization invitations from the invitation acceptance routes.

When not to use it

  • Do not use shop switching as a permissions workaround; assign the user to the correct workspace or store.
  • Do not create duplicate shops just to test setup; use the existing staging or test workspace when possible.
  • Do not troubleshoot product data until the active shop and workspace are confirmed.

Implementation source

  • Pages live under `src/app/(auth)` and onboarding routes such as `src/app/(dashboard)/orgs/new` and `src/app/(dashboard)/shops/new`.
  • Tenant resolution depends on Supabase Auth plus the active-shop cookie used by dashboard route handlers.
  • Shop and organization membership state is stored in Prisma models in `prisma/schema.prisma` and managed through `/api/shops` and `/api/orgs` handlers.

Data and API

  • Supabase Auth user and session records.
  • Prisma models: `Organization`, `OrganizationMember`, `Shop`, `ShopUser`, `Invitation`, `OrgInvitation`.
  • APIs: `/api/shops`, `/api/orgs`, `/api/org-invitations`, `/api/invitations`.

Failure modes

  • No active shop: create/select a shop or clear a stale active-shop cookie.
  • Wrong tenant data: switch the active workspace before editing experiments or integrations.
  • Expired invitation: request a new invitation from a workspace or store admin.

Launchpad

Operator

Simple termsLaunchpad is the home screen that tells an operator what to do next for the selected shop.

The daily command center for a shop. It shows readiness, active tests, draft blockers, recent learning, and the next best action.

/

Implementation behavior

  • Launchpad reads the active shop and aggregates setup state from goals, audiences, store profile, installation, drafts, and running experiments.
  • It computes a readiness stage such as setup, launch, active learning, or readback based on what exists and what is blocking progress.
  • The next-move card points to the highest-leverage route with a reason and confidence so operators do not hunt through the app.
  • Learning proof comes from recent experiment outcomes, store profile findings, and signals that are already persisted.

How to use it

  • Start from Launchpad before creating new work.
  • Follow the highlighted next move if setup or launch readiness is unclear.
  • Open active and draft tests directly from the Launchpad lists.
  • Use readiness checks to decide whether to install, add metrics, build variants, QA, or read results.

When not to use it

  • Do not use it as the source of truth for detailed experiment math; open the experiment or analytics pages for that.
  • Do not treat a next-move suggestion as approval to launch without QA.
  • Do not diagnose SDK install issues from Launchpad alone; use Realtime Analytics and installation checks.

Implementation source

  • The route is `src/app/(dashboard)/page.tsx` with supporting dashboard data calls.
  • It composes shop setup state from experiments, goals, audiences, installation, analytics summaries, and store profile state.
  • Navigation cards link into the same underlying routes documented in the complete catalog.

Data and API

  • Reads `Shop`, `Experiment`, `Variation`, `Goal`, `ExperimentGoal`, store profile, signal, and installation state.
  • Analytics summaries come from dashboard and experiment analytics APIs.
  • Navigation connects into `/backlog`, `/tests`, `/analytics`, `/store-profile`, and `/installation`.

Failure modes

  • Empty Launchpad usually means no shop, no installation, or no foundations yet.
  • A next move that looks stale usually points to incomplete setup data rather than a broken recommendation.
  • Analytics cards stay thin until SDK events reach the Worker and Tinybird.

Ideas and backlog

Operator

Simple termsThe backlog is where rough test ideas live before they are ready to become experiments.

The planning layer for experiment concepts before they become tests. It stores hypotheses, evidence, source context, comments, priority, and handoff notes.

/backlog/backlog/new/backlog/[id]/backlog/import

Implementation behavior

  • Ideas can be created manually, imported from Research Hub context, or generated from Operator and store-profile evidence.
  • Each idea keeps status, priority, source, target surface, expected impact, comments, archive state, and optional linked experiment.
  • The detail page turns a qualified idea into an experiment without losing the original evidence trail.
  • Codex handoff and Research Hub snapshots preserve external research context for future builders.

How to use it

  • Create ideas when evidence is not ready to launch as an experiment.
  • Attach page context and proof so Operator can reason about the target surface.
  • Move high-confidence ideas into experiments from the detail route.
  • Archive stale ideas instead of deleting useful historical context.

When not to use it

  • Do not put live-test configuration only in an idea; create an experiment when it needs runtime behavior.
  • Do not use ideas as a dumping ground without evidence, target page, or expected metric.
  • Do not delete old idea context when archiving is enough to keep history clean.

Implementation source

  • Pages live under `src/app/(dashboard)/backlog`.
  • Handlers live under `/api/backlog`, including comments, archive, restore, import, and create-experiment actions.
  • Backlog items can link to experiments so the original hypothesis and evidence remain attached.

Data and API

  • Backlog and comment models plus imported research metadata.
  • APIs: `/api/backlog`, `/api/backlog/[id]`, `/api/backlog/[id]/comments`, `/api/backlog/import`.
  • Linked experiments store the relationship back to the originating idea.

Failure modes

  • Weak ideas produce weak experiments: add evidence, page URL, target user, and expected metric before handoff.
  • Imported items may need cleanup if external source fields are incomplete.
  • Archived ideas disappear from default lists but can be restored.

Experiment creation and lifecycle

Both

Simple termsAn experiment is the actual test that can be shown to visitors. It owns the variants, targeting, traffic, metrics, QA, and launch status.

The core A/B testing workflow: create a draft, configure targeting and metrics, build variants, QA, launch, monitor, pause, complete, archive, or restore.

/tests/tests/new/tests/[id]

Implementation behavior

  • An `Experiment` owns status, traffic allocation, targeting JSON, schedule, planned-test settings, sequential settings, and optional backlog source.
  • Each experiment has `Variation` records with weight, control flag, mutation payloads, code workspace metadata, and preview state.
  • Primary and secondary metrics are connected through `ExperimentGoal`; a primary metric is required for meaningful launch/readback.
  • Status transitions gate runtime eligibility: draft is not delivered, running can be assigned, paused stops new delivery, completed feeds readback, archived hides from default operations.
  • Conflict checks compare targeting and schedule against other live or scheduled tests before launch.

How to use it

  • Create the experiment from an idea or from `/tests/new`.
  • Set the target URL/audience, traffic allocation, and schedule before building variants.
  • Attach at least one primary metric and any secondary metrics.
  • Build the variants, run QA, resolve blockers, then start the experiment.
  • Pause for emergencies, complete after enough evidence, archive when it should leave the operating list.

When not to use it

  • Do not launch an experiment for a change you already know you want to ship to everyone; use a feature flag or direct implementation.
  • Do not create a test without a measurable primary metric.
  • Do not run overlapping tests on the same page/audience unless the conflict is intentional and understood.

Implementation source

  • Pages live under `src/app/(dashboard)/tests`.
  • Dashboard handlers live under `/api/experiments`, `/api/variations`, and experiment subroutes for start, pause, complete, archive, restore, QA, goals, conflicts, and code workspaces.
  • The Prisma models are `Experiment`, `Variation`, `Goal`, and `ExperimentGoal`; public automation uses `/api/v1/experiments`.

Data and API

  • Prisma models: `Experiment`, `Variation`, `Goal`, `ExperimentGoal`, `Page`, `Segment`, `ExperimentAuditLog`.
  • Internal APIs: `/api/experiments`, `/api/experiments/[id]`, `/api/experiments/[id]/status`, `/api/experiments/[id]/archive`, `/api/experiments/conflicts`.
  • Public APIs: `/api/v1/experiments`, `/api/v1/experiments/{id}`, `/api/v1/experiments/{id}/start`, `/pause`, `/complete`, `/duplicate`.

Failure modes

  • Cannot launch: check missing primary metric, missing variant, no URL/audience, zero traffic allocation, or unresolved QA blockers.
  • Visitors not assigned: experiment is not running, targeting does not match, or the SDK is not installed on that page.
  • Overlapping tests: use conflict output to adjust URL, segment, schedule, or traffic.

Targeting, pages, audiences, and segments

Both

Simple termsTargeting answers the question: who is eligible to see this thing, and on which pages?

Defines who and what page qualifies for experiments, feature flags, and personalization rules.

/audience/audience/new/audience/:id/edit/pages/pages/new

Implementation behavior

  • Runtime page matching supports exact, wildcard, and regex URL rules.
  • Segments combine page, traffic, behavior, customer, device, and Shopify/customer signals into reusable audience definitions.
  • Experiment targeting JSON can reference direct URL rules or saved segment rules depending on the workflow.
  • Legacy pages redirect into the current audience system, but the underlying runtime still understands URL patterns.

How to use it

  • Create broad page groups for repeated target surfaces such as PDP, cart, homepage, and collection pages.
  • Use exact URLs for one-page tests, wildcard for families of pages, and regex only when pattern control is needed.
  • Build saved audiences when the same visitor logic will be reused across tests, flags, or personalization.
  • Review targeting before launch when an experiment does not appear in preview.

When not to use it

  • Do not use a broad audience when a page-specific test only belongs on one surface.
  • Do not use regex unless exact or wildcard matching cannot express the rule.
  • Do not rely on behavior/customer signals before those signals are actually collected for the shop.

Implementation source

  • Audience pages live under `src/app/(dashboard)/audience`; legacy page routes live under `src/app/(dashboard)/pages`.
  • Handlers live under `/api/segments` and `/api/pages`.
  • Matching logic is shared by dashboard targeting utilities and the SDK runtime URL/segment evaluation.

Data and API

  • Prisma models: `Segment`, `SegmentRule`, `Page`, `Experiment.targeting` JSON.
  • APIs: `/api/segments`, `/api/pages`, `/api/detected-pages`, `/api/analytics/detected-pages`.
  • SDK URL matcher evaluates current location before assignment and mutation.

Failure modes

  • No match because of protocol, trailing slash, query strings, or an overly narrow regex.
  • Audience rule depends on a signal that has not been collected yet.
  • Multiple eligible tests can conflict; check conflict output and traffic allocation.

Metrics, goals, and conversion tracking

Both

Simple termsMetrics tell Apex what success means for a test: a click, pageview, custom event, revenue event, or Shopify event.

Creates reusable success events for experiments: click, pageview, custom, revenue, and Shopify-connected conversion goals.

/goals/goals/new/goals/new/visual

Implementation behavior

  • A `Goal` stores type, selector, URL pattern, event name, capture rules, text matching, revenue settings, and count-once behavior.
  • Click goals bind to selectors in the SDK; optional capture rules can store element text, value, attribute, or dataset values.
  • Pageview goals match URL patterns after the SDK sees a page event.
  • Custom and revenue goals are tracked through SDK calls or Shopify event integrations.
  • Experiments attach goals through `ExperimentGoal`, with one goal marked primary for readback and launch criteria.

How to use it

  • Create reusable metrics before building an experiment.
  • Use click goals for UI actions, pageview goals for route arrival, custom goals for product events, and revenue goals for order value.
  • Verify selectors in QA before launch.
  • Mark one primary metric per experiment and keep secondary metrics for diagnostics.

When not to use it

  • Do not use a click goal when the real outcome is revenue or checkout completion.
  • Do not use fragile selectors that depend on generated class names if a stable selector exists.
  • Do not mark multiple goals as primary for the same experiment decision.

Implementation source

  • Metric pages live under `src/app/(dashboard)/goals`.
  • Handlers live under `/api/goals`, `/api/generate-selector`, and goal-verification experiment QA routes.
  • The SDK binds goal listeners and sends matching events through the Worker into Tinybird.

Data and API

  • Prisma models: `Goal`, `ExperimentGoal`, `ShopifyEventSetting`.
  • APIs: `/api/goals`, `/api/goals/[id]`, `/api/generate-selector`, `/api/goal-verifications`.
  • Events land in Tinybird `events` with `event_type`, `experiment_id`, `variation_id`, `properties`, and timestamp.

Failure modes

  • Selector does not fire: inspect DOM timing, selector specificity, and whether the element is replaced after SDK binding.
  • Revenue missing: confirm Shopify/web pixel settings or custom revenue payload shape.
  • Conversion rate looks wrong: check count-once rules, bot/internal traffic, and whether the primary goal is attached to the right experiment.

Variant builder, visual mutations, and code mode

Both

Simple termsThe builder is where a treatment variation is made. It can save simple DOM mutations or a richer code workspace.

The builder authors the actual storefront change for a variation. It supports visual mutations, custom CSS/JS, file-based code workspaces, previews, revisions, and generated changes.

/tests/[id]/variations/[varId]

Implementation behavior

  • Visual mutations are saved as structured JSON actions such as text, HTML, style, attribute, remove, insert before, and insert after.
  • The SDK applies mutations idempotently after targeting and assignment succeed.
  • Code mode stores generated workspace files, preview builds, build status, and revision metadata for more complex variants.
  • Selector generation and mutation generation APIs help produce or refine changes from prompts and page context.
  • Revision history lets teams inspect earlier builder states and roll forward from known working versions.

How to use it

  • Start with visual mutations for simple copy, style, layout, or insertion changes.
  • Use code mode when the change needs component logic, assets, or multi-file behavior.
  • Save frequently, preview the forced variation, then run QA before launching traffic.
  • Keep the control variation clean and edit treatment variations only.

When not to use it

  • Do not use code mode for a copy or color change that a structured mutation can handle.
  • Do not edit the control variation as if it were a treatment.
  • Do not launch a generated variant without previewing and saving the final state.

Implementation source

  • The editor route is `src/app/(dashboard)/tests/[id]/variations/[varId]/page.tsx`.
  • Operator and builder logic lives under `src/features/apex-operator` plus variation handlers under `/api/experiments/[id]/variations/[variationId]`.
  • Mutation payloads are stored on `Variation.mutations`; code workspace files, revisions, and builds use the experiment variation workspace APIs.

Data and API

  • Prisma `Variation.mutations`, variation weight/control fields, code workspace models, preview artifact records, and revision records.
  • APIs: `/api/variations`, `/api/variations/[id]`, `/api/generate-mutations`, `/api/generate-selector`, `/api/tools/*`, `/api/experiments/[id]/code-workspace/*`.
  • SDK mutation engine and preview-session runtime.

Failure modes

  • Change flashes or appears late: tune anti-flicker, selector timing, or target container.
  • Mutation misses element: inspect selector, iframe/shadow DOM boundaries, and dynamic rendering.
  • Code preview fails: review build status, generated files, unsupported browser APIs, and asset paths.

Apex Operator and tool-led building

Both

Simple termsOperator is the AI builder. It uses browser, page, code, selector, network, screenshot, filesystem, and persistence tools to help build and QA experiments.

Apex Operator is the model-led experiment builder. It gives the model compact tools for inspecting pages, network traffic, state, selectors, artifacts, QA evidence, and persistence.

/tests/[id]/variations/[varId]/operator-logs/api/operator/*

Implementation behavior

  • Operator sessions gather current experiment, variation, page, workspace, and store-profile context.
  • Tools let the model inspect DOM, network, console, page state, selectors, files, screenshots, artifacts, and saved preview state.
  • Operator writes structured changes to variation mutations or code workspaces instead of relying on one-off text suggestions.
  • External handoff now prefers the Apex CLI workflow: install `@drip-apex/apex-cli`, run `apex login`, check out canonical workspace files, dogfood with `apex workspace dev`, then publish with `apex workspace publish`.
  • The CLI uses the same canonical workspace file model as in-app Operator: `src/index.js`, `src/index.scss`, `src/info.js`, `src/mutations.json`, `experiment.config.json`, `targeting.json`, `goals/*.json`, `segments/*.json`, `network/*.recipe.json`, and `dev-doc.md`.
  • Logs preserve chat messages, tool calls, evidence, failure states, artifacts, and network details for review.
  • The product principle is general tool affordance first: avoid hardcoding one test type as the only supported workflow.

How to use it

  • Use Operator to inspect a target page, propose a variant, build it, and collect QA evidence.
  • Review every generated change before launch.
  • Open Operator Logs when a run fails, produces unexpected output, or needs auditability.
  • Give Operator specific constraints, but let it use general tools for page inspection and implementation.
  • For handoff runs, let the external agent inspect the live target URL and relevant storefront/domain context itself; screenshots are useful evidence, not a hard prerequisite.

When not to use it

  • Do not treat Operator output as automatically launch-safe.
  • Do not use it for deterministic one-click workflows that normal forms already handle faster.
  • Do not constrain Operator to one narrow playbook when a general page-inspection tool can solve the task better.

Implementation source

  • Core code lives under `src/features/apex-operator`.
  • APIs include `/api/operator-chat-session`, `/api/operator-events`, `/api/operator-runs`, `/api/operator-evidence`, `/api/operator-network`, and `/api/operator-screenshot`.
  • The variation editor mounts the Operator UI and uses saved tool results to persist mutations, code workspace changes, artifacts, and evidence.
  • External handoff uses `@drip-apex/apex-cli` with `apex workspace checkout`, `apex workspace dev`, and `apex workspace publish` against canonical workspace files shared with in-app Operator.

Data and API

  • APIs include `/api/operator/chat`, `/api/operator/stream`, `/api/operator/messages`, `/api/operator/runs`, `/api/operator/evidence`, `/api/operator/network`, `/api/operator/screenshot`, and tool endpoints.
  • CLI workspace APIs include `/api/v1/experiments/[id]/variations/[variationId]/workspace`, file read/write routes, build, and revisions.
  • Models include operator sessions, events, artifacts, evidence, review records, and code workspace snapshots.
  • Uses store profile facts, assets, backlog context, experiment setup, and preview browser state.

Failure modes

  • Poor output usually means missing target URL, missing store context, or vague instruction.
  • Tool failure can come from blocked storefront access, auth-required pages, CSP, or preview host mismatch.
  • Never assume generated code is launch-ready without QA and visual inspection.

QA workspace, previews, screenshots, and launch gating

Both

Simple termsQA is the safety check before traffic. It proves the variant renders, tracking works, and blockers are resolved.

QA proves that a variant renders correctly, tracking fires, screenshots are captured, and launch blockers are resolved before visitors see a test.

/tests/[id]?tab=qa/tests/[id]/variations/[varId]

Implementation behavior

  • Preview sessions force a specific experiment and variation through cookies or preview parameters.
  • QA run APIs inspect the experiment setup, target page, goals, screenshots, and runtime behavior.
  • Screenshot jobs can capture desktop, iPhone, and iPad views and persist result URLs.
  • Goal verification checks whether the selected metric can be observed or triggered in the preview path.
  • Launch gates combine setup blockers, QA state, guardrails, and experiment status.

How to use it

  • Open QA from an experiment before pressing start.
  • Preview every variation on the intended URL and key device sizes.
  • Run screenshots and goal verification for the primary metric.
  • Fix every blocker or consciously document the exception before launch.

When not to use it

  • Do not use QA as a substitute for setting up the experiment correctly.
  • Do not approve a test from desktop screenshots only when mobile traffic matters.
  • Do not ignore a failed goal verification just because the visual change looks right.

Implementation source

  • The QA tab is the `?tab=qa` view of `src/app/(dashboard)/tests/[id]/page.tsx`, with deeper runs inside the variation editor.
  • Handlers include `/api/experiments/[id]/qa/run`, `/api/experiments/[id]/qa/screenshots`, `/api/experiments/[id]/qa/goal-verification`, `/api/preview`, and `/api/preview-sessions`.
  • Screenshot jobs and preview sessions persist evidence used by launch gates.

Data and API

  • Prisma `ScreenshotJob`, preview session records, operator evidence, goal verification records, and experiment QA state.
  • APIs: `/api/experiments/[id]/qa/run`, `/api/experiments/[id]/goal-verifications`, `/api/screenshots`, `/api/preview`, `/api/preview-sessions`.
  • Public screenshot endpoints exist under `/api/v1/screenshots`.

Failure modes

  • Preview shows control: force cookie/session missing or targeting does not match.
  • Screenshot job stuck: check browser worker availability and target page accessibility.
  • Goal verification false negative: selector may need user interaction, delayed render, or a different URL state.

Results, imported outcomes, and readback

Operator

Simple termsResults is where Apex turns tracked or imported test data into a decision and a learning.

Turns live and completed experiment data into decisions, learnings, and future backlog evidence.

/test-results/tests/[id]

Implementation behavior

  • Apex reads assignment and conversion events from Tinybird by experiment, variation, goal, and time window.
  • Sequential settings and planned-test snapshots support always-valid or fixed-horizon readback depending on setup.
  • Imported results let teams capture external testing outcomes and preview them before confirmation.
  • Completed experiment outcomes can be summarized into store learnings and used by the next backlog cycle.

How to use it

  • Review results after enough runtime and sample have accumulated.
  • Compare primary metric lift, secondary metric movement, revenue, traffic quality, and screenshots.
  • Use import preview before committing external result data.
  • Record the conclusion so Launchpad and future ideas retain the learning.

When not to use it

  • Do not call a winner before the test has enough runtime, sample, and measurement quality.
  • Do not mix imported external results with Apex-tracked results without checking dates and variant mapping.
  • Do not use secondary metrics as the main decision unless the experiment was intentionally set up that way.

Implementation source

  • Results routes live under `src/app/(dashboard)/test-results` and experiment detail analytics sections.
  • Handlers include `/api/test-results`, `/api/test-results/import/preview`, `/api/test-results/import/confirm`, and `/api/analytics/experiment/[id]`.
  • Readback joins Prisma experiment context with Tinybird visitor/conversion/revenue/event pipes.

Data and API

  • Tinybird pipes for visitors, conversions, timeseries, revenue, behavior, and dashboard stats.
  • APIs: `/api/analytics/experiment`, `/api/test-results/import/preview`, `/api/test-results/import/confirm`, `/api/experiments/[id]/stats`.
  • Models include experiment outcome, imported result, learning, and audit records.

Failure modes

  • No results: no runtime traffic, wrong shop ID, event ingestion failure, or the test was never running.
  • Unexpected lift: inspect traffic allocation, targeting, internal traffic, and goal attachment.
  • External import mismatch: validate variation names, dates, sample counts, and metric units before confirm.

Analytics suite

Operator

Simple termsAnalytics shows what visitors and tests are doing across the store: realtime events, traffic, funnels, flow, visitors, revenue, and measurement quality.

Store-wide and experiment-aware reporting across visitors, conversions, revenue, ecommerce, traffic, funnels, journey flow, realtime events, and measurement quality.

/analytics/analytics/audience/analytics/traffic/analytics/visitors/analytics/realtime/analytics/funnels/analytics/funnels/new/analytics/flow

Implementation behavior

  • The SDK and Worker send normalized events into the Tinybird `events` datasource.
  • Dashboard APIs proxy Tinybird pipes and combine them with Prisma context for shop, experiment, and goal names.
  • Realtime views query recent events to verify install, pageview, custom event, and QA traffic.
  • Funnels use detected pages or saved funnel steps to compute conversion and drop-off.
  • Visitor explorer reads sessions and event trails for individual debugging.

How to use it

  • Use Overview for business-level health and experiment summaries.
  • Use Realtime immediately after installation or QA.
  • Use Traffic and Audience to understand quality and targeting context.
  • Use Funnels and Flow when the question is journey movement rather than one metric.
  • Use Visitors to debug one visitor, session, or identifier.

When not to use it

  • Do not use store-wide analytics to make a variant decision without opening the experiment-level report.
  • Do not use Realtime as long-term reporting; it is mainly for debugging fresh events.
  • Do not trust funnel results until page detection and URL normalization are checked.

Implementation source

  • Pages live under `src/app/(dashboard)/analytics` and its child routes.
  • Handlers live under `/api/analytics/*`, `/api/realtime-analytics`, `/api/detected-pages`, and semantic analytics routes.
  • Tinybird pipes and datasource definitions live under `packages/tinybird`.

Data and API

  • Tinybird datasource: `events` with shop, visitor, session, user, event type, experiment, variation, URL, properties, device, country, timestamp.
  • Pipes include `dashboard_stats`, `experiment_visitors`, `experiment_conversions`, `experiment_timeseries`, and `detected_pages`.
  • APIs under `/api/analytics/*`, `/api/realtime-analytics`, `/api/semantic/*`, and `/api/detected-pages`.

Failure modes

  • Realtime empty: SDK not installed, wrong shop ID, Worker error, or blocked network call.
  • Funnels incomplete: detected pages have not accumulated enough events or URL normalization differs.
  • Experiment report blank: experiment IDs or variation IDs are missing from tracked events.

Store profile, audits, signals, and learning runs

Operator

Simple termsStore profile is Apex's memory for the brand, technical setup, evidence, and learnings for a shop.

The persistent memory of a shop: brand facts, technical findings, product-data depth, storefront evidence, customer signals, audit findings, and operator learnings.

/store-profile/signals

Implementation behavior

  • Audit runs collect evidence and findings about storefront quality, tracking setup, product data, and technical readiness.
  • Brand and technical profiles store normalized facts that Operator can reuse across ideas and builds.
  • Signals capture behavior, reviewed findings, semantic sequences, and store facts that help audiences and personalization.
  • Learning runs summarize completed work into reusable context for future experiment planning.

How to use it

  • Open Store Profile before asking Operator to build major variants.
  • Review and approve findings so only trusted evidence influences later work.
  • Use Signals for reusable behavioral or store facts.
  • Refresh audits after major store, theme, product catalog, or tracking changes.

When not to use it

  • Do not use stale profile facts after a major theme, app, product, or tracking change.
  • Do not let unreviewed audit findings drive important decisions.
  • Do not use signal-based personalization until the underlying signals are trustworthy.

Implementation source

  • Pages live under `src/app/(dashboard)/store-profile` and `src/app/(dashboard)/signals`.
  • Handlers live under `/api/store-profile`, `/api/shop-audits`, `/api/signals`, and semantic analytics endpoints.
  • Profile, evidence, finding, fact, and learning-run models are defined in `prisma/schema.prisma`.

Data and API

  • Models include `ShopAuditRun`, `ShopAuditEvidence`, `ShopAuditFinding`, `ShopBrandProfile`, `ShopTechnicalProfile`, `ShopLearningRun`, `StoreFact`, and signal records.
  • APIs under `/api/store-profile/*`, `/api/signals`, `/api/semantic/*`, and audit review endpoints.
  • Evidence can include screenshots, detected pages, product data, and runtime checks.

Failure modes

  • Operator lacks context: profile is empty or findings are unreviewed.
  • Old technical advice: rerun audit after a theme, app, or tracking change.
  • Signal-based targeting is weak until enough events and facts exist.

Assets and references

Both

Simple termsAssets are the files and references Apex can use while building tests, pages, and AI prompts.

Stores images, PDFs, creative references, and prompt material used for experiments, landing pages, and Operator instructions.

/assets

Implementation behavior

  • Assets are uploaded under the active shop and tracked with file metadata, usage links, and context.
  • Operator and landing-page builders can reference assets when generating copy, layout, or visual changes.
  • Usage lookups help determine whether deleting or replacing an asset affects active work.

How to use it

  • Upload brand, product, campaign, or research material before generating content-heavy variants.
  • Attach assets to the relevant idea, experiment, or landing-page workflow when possible.
  • Check asset usage before removing files.

When not to use it

  • Do not upload large unoptimized files when a compressed asset will work.
  • Do not delete assets before checking where they are used.
  • Do not expect Operator to use an asset unless it is attached or mentioned in context.

Implementation source

  • The page lives under `src/app/(dashboard)/assets`.
  • Handlers include `/api/assets`, `/api/assets/upload`, and `/api/assets/[id]/usage`.
  • Asset metadata is shop-scoped and can be referenced by Operator, landing pages, and experiment workflows.

Data and API

  • Asset metadata and usage records in Prisma-backed storage.
  • APIs: `/api/assets`, `/api/assets/upload`, `/api/assets/usage`.
  • File delivery depends on the configured storage provider and public/private access mode.

Failure modes

  • Broken asset in preview: check URL, permissions, and whether the file was replaced.
  • Operator ignores asset: make the asset relevant in the prompt or attach it to the active context.
  • Large files may fail upload or slow preview if not optimized.

Landing pages and landing-page QA

Operator

Simple termsLanding pages are standalone generated pages that Apex can edit, preview, QA, and publish.

Creates, edits, previews, QA checks, and publishes AI-assisted landing pages separate from standard experiment variants.

/landing-pages/landing-pages/new/landing-pages/[id]/landing-pages/[id]/qa

Implementation behavior

  • Landing pages have typed page records, content blocks, versions, publish status, preview URLs, and immutable published bundles.
  • Operator chat can edit blocks, generate copy, update structure, and render a new version.
  • QA checks a specific page version before it becomes the published/live version.
  • Published bundles can be served through the configured landing-page runtime/storage path.

How to use it

  • Create a new landing page from a page type and initial content.
  • Use Operator to refine blocks, layout, proof points, and copy.
  • Preview and QA the version that will be published.
  • Publish only after the QA route shows the intended version and target state.

When not to use it

  • Do not use landing pages for a small change to an existing product page; use an experiment variant instead.
  • Do not publish a version that has not been previewed and QAed.
  • Do not use generic generated copy without brand/profile context.

Implementation source

  • Pages live under `src/app/(dashboard)/landing-pages`.
  • Handlers include `/api/landing-pages`, `/api/landing-pages/[id]/chat`, `/operator-tools`, `/publish`, `/qa`, and version render routes.
  • Landing page records, versions, blocks, artifacts, and publish state are persisted separately from experiment variations.

Data and API

  • Landing page, version, block, QA, publish, and artifact records.
  • APIs under `/api/landing-pages`, `/api/landing-pages/[id]/versions`, `/api/landing-pages/[id]/render`, `/api/landing-pages/[id]/qa`, and publish endpoints.
  • Can reuse assets, store profile facts, and Operator evidence.

Failure modes

  • Preview mismatch: ensure the version being QAed is the intended current version.
  • Publish target unavailable: check storage/runtime configuration and generated bundle state.
  • Generic copy: add brand profile, assets, and precise audience context before generation.

Feature flags

Developer

Simple termsFeature flags are controlled switches or payloads for engineering rollouts, not visual A/B test DOM changes.

Runtime toggles for off/on variants, typed payloads, rollout percentages, targeting, and source-experiment promotion.

/flags

Implementation behavior

  • Flags use the same targeting and rollout concepts as experiments but return a decision payload instead of DOM mutation behavior.
  • A flag has status, key, rollout, targeting, variants, default/off value, and optional source experiment.
  • Decision debugger explains why a visitor would receive a variant.
  • Flags can be activated, paused, archived, or created from successful experiments.

How to use it

  • Use flags when engineering needs a controlled rollout or remote configuration.
  • Keep payloads typed and stable so application code can consume them safely.
  • Test decisions with the debugger before activating.
  • Archive flags that are permanently shipped in application code.

When not to use it

  • Do not use a flag when you need experiment analytics and variant conversion tracking.
  • Do not put secret or unsafe values in flag payloads consumed by the browser.
  • Do not keep temporary rollout flags alive after the feature is permanently shipped.

Implementation source

  • Pages live under `src/app/(dashboard)/flags`.
  • Handlers live under `/api/flags` plus activate, pause, archive, and decision-debugger routes.
  • Flags share targeting and rollout ideas with experiments but return typed decision payloads instead of DOM mutations.

Data and API

  • Flag and flag variant models plus targeting JSON.
  • APIs under `/api/flags`, `/api/flags/[id]/activate`, `/pause`, `/archive`, `/decision-debugger`, and experiment-to-flag creation.
  • Runtime decisions are delivered through configuration and flag evaluation endpoints.

Failure modes

  • Application sees default value: flag paused, key mismatch, targeting miss, or rollout percentage excludes visitor.
  • Bad payload breaks consuming app code: validate schema and defaults before activation.
  • Old flags create confusion: archive retired rollouts.

Personalization

Both

Simple termsPersonalization chooses a visitor-specific experience from ordered rules and signals.

Signal-driven storefront experiences with ordered rules, payloads, targeting, rollout controls, and decision debugging.

/personalization

Implementation behavior

  • Personalization rules evaluate visitor and store signals in order and return the first eligible experience.
  • Experiences can use targeting, payload values, rollout percentage, and safe status controls.
  • Decision debugger shows matched and rejected rules so teams can understand runtime behavior.
  • The runtime uses the same event, segment, and signal foundation as experiments and flags.

How to use it

  • Create personalization only after the signal or audience is trustworthy.
  • Order specific rules above broad fallback rules.
  • Roll out gradually and inspect decisions before expanding traffic.
  • Use analytics and visitor trails to validate that the experience is reaching the intended group.

When not to use it

  • Do not use personalization when you need a clean randomized A/B test result.
  • Do not personalize from signals that are missing, noisy, or legally sensitive.
  • Do not create broad rules above specific rules unless the broad rule is meant to catch most traffic.

Implementation source

  • Pages live under `src/app/(dashboard)/personalization`.
  • Handlers live under `/api/personalizations` plus activate, pause, archive, and decision-debugger routes.
  • Runtime decisions use segment, signal, rollout, and payload records tied to the active shop.

Data and API

  • Personalization, rule, payload, segment, signal, and decision records.
  • APIs under `/api/personalization`, `/api/personalization/[id]/activate`, `/pause`, `/archive`, and `/decision-debugger`.
  • Uses SDK events, store facts, visitor context, and segment rules.

Failure modes

  • Wrong experience appears: rule order, broad targeting, or stale visitor signals.
  • No experience appears: paused status, rollout exclusion, missing signal, or targeting miss.
  • Hard-to-debug outcomes: use the decision debugger and visitor explorer together.

Store connection, Shopify install, and Web Pixel

Admin

Simple termsStore connection gets Apex onto the storefront and connects Shopify so events, products, orders, and revenue can flow.

Connects Apex to a storefront so experiments, analytics, Shopify events, product data, and revenue analysis can work.

/installation/connect/connect/callback/api/shopify/*

Implementation behavior

  • Shopify OAuth grants app scopes and stores installation metadata for the active shop.
  • Theme app embed or manual snippet loads Apex Runtime on storefront pages.
  • Shopify Web Pixel and event settings send checkout/order-related events that are not available from DOM-only tracking.
  • Product, inventory, and order sync endpoints populate cost and reconciliation data when scopes are available.
  • Install verification checks Apex Runtime reachability, snippet size, runtime settings, and recent events.

How to use it

  • Use Shopify OAuth when the store is Shopify; use manual snippet for custom storefronts.
  • Enable app embed or install the Apex Runtime snippet exactly once.
  • Verify realtime events after installation.
  • Reconnect Shopify when scopes, store permissions, or app access change.

When not to use it

  • Do not install both manual snippet and app embed in a way that loads the SDK twice.
  • Do not rely on Shopify revenue reporting without Web Pixel/event settings enabled.
  • Do not debug experiments before install verification and realtime events pass.

Implementation source

  • Install pages live under `src/app/(dashboard)/installation`.
  • Handlers include `/api/shopify/auth`, `/api/shopify/auth/callback`, `/api/shopify/settings`, `/api/shopify/snippet`, `/api/shopify/webhooks`, `/api/onboarding/verify-install`, and `/api/shops/runtime-settings`.
  • Runtime delivery uses the SDK package, Worker URL, Shopify installation metadata, and Web Pixel configuration.

Data and API

  • Models include `Shop`, Shopify installation/session records, `ShopifyEventSetting`, product/order/cost sync records.
  • APIs under `/api/shopify/*`, `/api/installation`, `/api/snippet`, `/api/runtime-settings`, `/api/check-snippet-size`.
  • Runtime uses `/api/exp`, CDN SDK, Worker URL, and Web Pixel events.

Failure modes

  • No storefront events: app embed disabled, snippet missing, blocked script, wrong shop ID, or Worker URL problem.
  • OAuth failed: domain mismatch, missing scopes, or stale callback state.
  • Revenue missing: Web Pixel or Shopify event settings are not enabled.

Runtime controls, SDK, anti-flicker, and consent

Developer

Simple termsThe runtime is the code on the storefront that decides eligibility, applies changes, and sends tracking events.

The browser runtime fetches experiment config, assigns visitors, applies variants, tracks goals, respects runtime settings, and batches events.

/installation/api/exp/api/sdk/*/api/consent/*

Implementation behavior

  • `Drip.init` initializes with shop ID and worker URL, then fetches `/api/exp` for active experiments and goals.
  • Assignment uses traffic allocation, variation weights, targeting, and sticky visitor cookies.
  • The mutation engine applies DOM changes and custom code after eligibility is resolved.
  • Goal listeners emit pageview, click, custom, revenue, and Shopify-linked events.
  • Event batching flushes every five seconds or twenty events; anti-flicker can hide content until variants apply.
  • Consent and runtime settings decide when tracking can run and how conservative the SDK should be.

How to use it

  • Install the snippet from Store Connection and verify it in Realtime Analytics.
  • Use custom tracking calls for non-DOM events.
  • Tune anti-flicker only around surfaces that can visibly change.
  • Keep the shop ID and worker URL aligned with the active shop.

When not to use it

  • Do not bypass consent requirements for analytics tracking.
  • Do not use heavy anti-flicker on pages where no visible change can happen.
  • Do not use client-side SDK behavior for server-only experiments or secure backend decisions.

Implementation source

  • SDK code lives in `packages/sdk`; Worker ingestion lives in `packages/worker`; Tinybird schemas and pipes live in `packages/tinybird`.
  • Config is served by `/api/exp` and runtime settings/snippet APIs in the web app.
  • Events are batched by the SDK, sent to the Worker, normalized to NDJSON, and stored in Tinybird.

Data and API

  • Packages: `packages/sdk`, `packages/worker`, `packages/tinybird`.
  • APIs: `/api/exp`, `/api/sdk/config`, `/api/sdk/publish`, `/api/consent/settings`, `/api/runtime-settings`.
  • Tinybird receives normalized NDJSON from the Worker.

Failure modes

  • Flicker: anti-flicker missing, selector delayed, or heavy page script contention.
  • Assignments change unexpectedly: cookies cleared, visitor ID reset, or weights/status changed mid-test.
  • Events missing: consent disabled, network blocked, Worker unavailable, or batching not flushed before navigation.

Edge routing and custom domains

Developer

Simple termsEdge routing sends a customer domain through Apex's Cloudflare Worker when a flow needs proxy-level control.

Routes customer domains through the Apex Worker path for edge-managed experiences and SSL-for-SaaS style storefront handling.

/installation/api/edge-routing/*

Implementation behavior

  • Custom hostnames can CNAME to `edge.drip-apex.com` so traffic enters the Cloudflare Worker.
  • The Worker resolves the shop/domain, applies routing rules, and proxies or handles configured paths.
  • Fallback origins and hostname validation prevent unverified traffic from being treated as a trusted shop domain.
  • Runtime config keeps edge routing separate from normal SDK-only installs.

How to use it

  • Use edge routing only when a storefront flow requires Worker mediation rather than SDK-only DOM changes.
  • Validate DNS and custom hostname status before switching traffic.
  • Keep origin settings current for each shop domain.
  • Test preview and production domains separately.

When not to use it

  • Do not use edge routing for ordinary DOM-only A/B tests that the SDK can handle.
  • Do not route production domains before DNS validation and origin testing are complete.
  • Do not mix Vercel domain ownership and Cloudflare custom hostname routing without checking which edge receives traffic.

Implementation source

  • Worker code lives in `packages/worker` and Cloudflare routes are documented in project configuration.
  • Dashboard install and edge pages call internal domain-routing and edge-resolution APIs.
  • Cloudflare custom hostnames and shop origin fields determine how requests are resolved.

Data and API

  • Cloudflare Worker routes, custom hostname records, shop origin fields, and edge-routing API state.
  • APIs under `/api/edge-routing/*` and installation/runtime verification endpoints.
  • Worker observability is the main debugging source for edge routing.

Failure modes

  • Hostname not active: DNS CNAME or validation TXT is missing.
  • Origin loop or blank response: wrong origin field or Vercel/domain conflict.
  • SDK works but edge route does not: these are separate deployment paths and must be verified independently.

Profit analysis and Shopify reconciliation

Admin

Simple termsProfit analysis adds cost and order context so a winning test can be judged by margin, not only conversion rate.

Adds product cost, inventory, order, and contribution-margin context so experiment results can be read against profit, not only conversion rate.

/settings/integrations/api/profit/*/api/shopify/*

Implementation behavior

  • Shopify sync jobs fetch product, inventory, order, and cost data when required scopes are connected.
  • Reconciliation compares Shopify events and Apex events to detect missing or mismatched revenue records.
  • Variant cost and margin data can be joined to experiment outcomes to judge business impact.
  • Profit endpoints expose sync health, variant costs, contribution margin, and data quality state.

How to use it

  • Reconnect Shopify with the needed scopes before relying on margin reporting.
  • Run or monitor sync jobs before reading profit-sensitive experiments.
  • Check reconciliation when revenue differs between Shopify and Apex.
  • Use contribution margin as a secondary decision metric when discounts, bundles, or upsells are involved.

When not to use it

  • Do not use margin reporting before Shopify scopes and cost data are confirmed.
  • Do not compare profit across variants if revenue attribution is failing.
  • Do not treat delayed Shopify sync data as real-time truth.

Implementation source

  • Integration UI lives under `src/app/(dashboard)/settings/integrations`.
  • Handlers include Shopify product/order/reconciliation endpoints and profit-analysis APIs.
  • Prisma product/order/cost records are joined with Tinybird revenue and experiment context for reporting.

Data and API

  • Shopify product/order/inventory/cost records, variant costs, reconciliation records, and experiment revenue events.
  • APIs under `/api/profit/*`, `/api/shopify/orders/*`, `/api/shopify/products/*`, `/api/shopify/reconcile*`, and integration settings.
  • Tinybird revenue events plus Prisma product/order cost tables.

Failure modes

  • Margin unavailable: missing Shopify scopes or no cost data.
  • Revenue mismatch: Web Pixel settings, order sync delay, currency, or duplicate events.
  • Sync stale: rerun sync and inspect job logs before trusting profit readback.

Guardrails, planned tests, and auto-pause

Admin

Simple termsGuardrails are the rules that keep tests from launching or being interpreted too casually.

Defines the statistical and operational rules that determine when tests can launch, pause, and be interpreted.

/settings/guardrails/tests/new/tests/[id]

Implementation behavior

  • Shop guardrail settings hold default minimum runtime, sequential significance preferences, auto-pause behavior, and planned-test defaults.
  • Experiment setup can opt into planned fixed-horizon or sequential readback depending on the selected settings.
  • Runtime and analytics code use these fields to label status, warnings, and decision readiness.
  • Auto-pause defaults protect against obvious risk but do not replace human review of experiment quality.

How to use it

  • Configure guardrails before creating a large batch of experiments.
  • Choose planned-test settings during experiment creation when sample size and duration matter.
  • Use sequential mode when ongoing monitoring is expected.
  • Review warnings before starting, pausing, or completing a test.

When not to use it

  • Do not use guardrails as a replacement for a clear hypothesis and primary metric.
  • Do not disable runtime/sample warnings just to ship more tests.
  • Do not switch statistical modes mid-test without documenting why.

Implementation source

  • Settings UI lives under `src/app/(dashboard)/settings/guardrails` and experiment creation/detail routes.
  • Settings are read and written through guardrail/settings APIs and experiment update flows.
  • Experiment stats and result components read planned-test and sequential fields to label decision readiness.

Data and API

  • Guardrail settings on shop and experiment records.
  • APIs under `/api/settings/guardrails`, experiment creation/update endpoints, and stats endpoints.
  • Results views read planned-test and sequential fields for interpretation.

Failure modes

  • Premature winner call: test does not meet runtime, sample, or statistical assumptions.
  • Unexpected pause: auto-pause threshold or guardrail was triggered.
  • Inconsistent readback: experiment settings changed after launch; inspect audit history.

API keys and public API v1

Developer

Simple termsAPI keys let external servers automate Apex safely for a shop.

Lets external systems create and manage experiments, variations, goals, screenshots, webhooks, privacy requests, and harness sessions.

/api-keys/api/v1/*

Implementation behavior

  • API keys are created per shop as publishable, test secret, or live secret keys and stored hashed.
  • Secret keys are shown once, then used as bearer tokens for `/api/v1` requests.
  • Public route handlers validate the key, resolve the shop, authorize the action, and return JSON responses.
  • The docs page renders the OpenAPI reference from the app's `openapiSpec` source.

How to use it

  • Create a live secret key for production server-to-server automation.
  • Use test secret keys for staging and automation trials.
  • Never put secret keys in browser code; use publishable keys only where client exposure is intended.
  • Use the OpenAPI reference for request and response shapes.

When not to use it

  • Do not put live secret keys in browser code, snippets, or public repositories.
  • Do not use a live key for staging automation.
  • Do not keep unused keys active after an integration is removed.

Implementation source

  • UI lives under `src/app/(dashboard)/api-keys`.
  • Handlers live under `/api/api-keys` and `/api/v1/*`.
  • OpenAPI source lives in `src/lib/api/openapi-spec` and schemas live under `src/lib/api`.

Data and API

  • Prisma `ApiKey` with hashed secret, type, permissions, expiry, and shop relation.
  • APIs: `/api/api-keys` and all `/api/v1/*` handlers.
  • OpenAPI JSON at `/api/v1/openapi.json`.

Failure modes

  • 401 or 403: missing bearer token, wrong key type, expired key, disabled key, or wrong shop.
  • Lost secret: create a new key because full secrets are not recoverable.
  • Automation mutates wrong shop: verify key belongs to the intended active shop.

Webhooks

Developer

Simple termsWebhooks notify another system when Apex events happen.

Sends Apex events to external systems when experiments or platform actions happen.

/webhooks/webhooks/new/api/v1/webhooks

Implementation behavior

  • Webhook endpoints are configured per shop with URL, subscribed events, enabled state, and signing secret.
  • Delivery attempts are recorded so failures can be inspected and retried or debugged.
  • Secrets are used by receivers to verify the payload came from Apex.
  • Public API v1 can create and manage webhook configuration for automation.

How to use it

  • Create one endpoint per external receiver or environment.
  • Subscribe only to the events that receiver needs.
  • Store the signing secret when created; rotate by recreating or updating the webhook.
  • Inspect recent attempts when a downstream system reports missing events.

When not to use it

  • Do not use webhooks when the receiver cannot verify signatures.
  • Do not subscribe to every event by default if the receiver only needs one event family.
  • Do not rely on webhooks for synchronous user-facing UI changes; they are delivery notifications.

Implementation source

  • Pages live under `src/app/(dashboard)/webhooks`.
  • Handlers live under `/api/webhooks` and `/api/v1/webhooks`.
  • Webhook records store endpoint URL, subscribed events, enabled state, signing secret, and delivery attempt metadata.

Data and API

  • Prisma `Webhook` plus webhook delivery/attempt records.
  • APIs: `/api/webhooks`, `/api/webhooks/[id]`, `/api/v1/webhooks`, and delivery handling routes.
  • Events include experiment lifecycle and platform integration events where supported.

Failure modes

  • Receiver sees invalid signature: wrong secret, changed endpoint, or payload transformation by a proxy.
  • No delivery: webhook disabled, event not subscribed, or shop mismatch.
  • Repeated failures: inspect attempt status, response body, timeout, and receiver availability.

Team, clients, organization, account, and admin settings

Admin

Simple termsThese settings decide who can access Apex, which clients exist, and how workspace-level administration works.

Manages who can access work, which clients belong to an agency, account-level preferences, integrations, and organization-level configuration.

/team/clients/org/settings/settings/settings/account/settings/integrations

Implementation behavior

  • Store team membership and organization membership are separate so client access can be scoped.
  • Agency workspaces expose client management and workspace settings beyond single-store company workflows.
  • Account settings manage personal user profile and account-level state.
  • Integration settings manage Shopify, profit analysis, and external platform health.

How to use it

  • Invite teammates at the store or organization level depending on the access they need.
  • Use Clients for agency workspace client setup.
  • Use Organization Settings for workspace ownership and defaults.
  • Use Integrations when Shopify or profit-analysis data needs reconnection.

When not to use it

  • Do not invite users at the organization level when they only need one store.
  • Do not change ownership or leave a workspace without confirming another admin remains.
  • Do not use account settings for store or workspace configuration.

Implementation source

  • Pages live under `src/app/(dashboard)/team`, `clients`, `org`, `account`, and settings routes.
  • Handlers include `/api/team/*`, `/api/orgs/*`, `/api/clients`, `/api/account/profile`, and invitation endpoints.
  • Membership and role models in Prisma separate organization access from shop access.

Data and API

  • Models include `Organization`, `OrganizationMember`, `Shop`, `ShopUser`, invitations, account/user profile records, and integration records.
  • APIs under `/api/team`, `/api/clients`, `/api/orgs`, `/api/settings/*`, and invitation endpoints.
  • Active shop and active organization state determines what settings are visible.

Failure modes

  • User cannot see a shop: they may be in the organization but not assigned to the store.
  • Wrong client edited: switch active workspace/shop before changing settings.
  • Ownership transfer or leave-workspace actions should be checked carefully because they affect access.

Internal admin, ops, test runner, and release observability

Admin

Simple termsInternal admin is for maintainers checking platform health, releases, queues, usage, and automated tests.

Operational surfaces for Apex maintainers: usage, model spend, public monitors, release metadata, Sentry status, queues, database state, SDK performance, and test runners.

/admin/admin/*/api/admin/*

Implementation behavior

  • Admin routes are separated from normal shop operations and intended for maintainers.
  • They aggregate internal job state, release manifests, model-usage records, Sentry issues, database checks, SDK performance summaries, and public endpoint monitors.
  • Test runner routes trigger or inspect internal verification flows and synthetic checks.
  • Release metadata ties deployed code and environment health back to operational state.

How to use it

  • Use admin routes when diagnosing platform health rather than a single shop setup issue.
  • Check release metadata after a deploy.
  • Inspect queues and monitors before assuming a product feature is broken.
  • Use test runner outputs as evidence, not as a replacement for user-flow verification.

When not to use it

  • Do not use internal admin screens for normal client operation.
  • Do not take destructive or production-impacting admin actions while debugging a single shop issue.
  • Do not trust a stale monitor without checking its last run time.

Implementation source

  • Pages live under `src/app/(dashboard)/admin`.
  • Handlers live under `/api/admin/*`, `/api/test-runner/*`, `/api/model-usage`, `/api/public-monitors`, and health routes.
  • Release scripts write manifests under `docs/releases`, and admin surfaces read those plus external service health signals.

Data and API

  • Admin APIs under `/api/admin/*`, `/api/test-runner/*`, `/api/public-monitors`, `/api/model-usage`, and release metadata endpoints.
  • External systems include Vercel, Sentry, Cloudflare, Tinybird, and Supabase.
  • Local release manifests are stored under `docs/releases` by deploy scripts.

Failure modes

  • A shop issue can look like a platform issue; verify tenant setup before escalating.
  • Monitor stale data: check last run time and release manifest.
  • Admin actions can affect production operations, so keep changes scoped and logged.

Privacy, export, deletion, and auditability

Developer

Simple termsPrivacy endpoints help export or delete user/visitor data and keep records of sensitive changes.

Supports compliance workflows for exporting or deleting visitor/user data and auditing sensitive operational actions.

/api/v1/data-export/api/v1/data-deletion/api/privacy/*

Implementation behavior

  • Public privacy endpoints accept authenticated server-to-server requests scoped by shop API key.
  • Export looks up relevant visitor/user data across persisted records and analytics where supported.
  • Deletion requests remove or anonymize records according to the implemented data path.
  • Audit logs and operational records preserve changes to experiments and admin-sensitive workflows.

How to use it

  • Use data export for access requests and data deletion for erasure workflows.
  • Pass stable visitor/user identifiers so the request can find the right records.
  • Keep privacy automation server-side with secret API keys.
  • Check audit logs when reconstructing who changed experiment or integration state.

When not to use it

  • Do not run privacy requests from browser code or public clients.
  • Do not assume one identifier finds every record if visitors were anonymous or cookies changed.
  • Do not skip audit review for sensitive admin or experiment changes.

Implementation source

  • Public handlers live under `/api/v1/data-export` and `/api/v1/data-deletion`.
  • Audit and privacy-related handlers use shop-scoped API key authentication.
  • The implementation spans relational shop data and analytics/event identifiers, with retention limits depending on storage path.

Data and API

  • Public APIs: `/api/v1/data-export` and `/api/v1/data-deletion`.
  • Internal privacy/admin APIs and audit-log models.
  • Event data, visitor/session identifiers, experiment assignment data, and shop-scoped relational records.

Failure modes

  • Request cannot find data: identifier mismatch or events not linked to a user ID.
  • Partial deletion risk: analytics and relational stores have different retention paths.
  • Do not run privacy workflows with client-exposed keys.

Checkout-block experiments

Developer

Simple termsCheckout-block experiments configure supported Shopify checkout extension content instead of changing the storefront DOM.

Configures Shopify checkout-block experiment payloads and preview state for checkout-adjacent surfaces.

/tests/[id]/checkout-block/api/checkout-blocks/*

Implementation behavior

  • Checkout-block configuration is tied to an experiment and stores payloads that can be read by the Shopify extension or related runtime.
  • Preview state helps validate what a block will render before exposing it to eligible traffic.
  • Tracking still depends on the broader Apex event and revenue setup.
  • Because checkout is constrained, this path uses explicit configuration instead of arbitrary DOM mutation.

How to use it

  • Use this only for supported Shopify checkout-block surfaces.
  • Configure the block payload and preview it before launch.
  • Attach revenue or checkout-related goals that are actually trackable in the store's Shopify setup.
  • Keep block changes small and test them carefully because checkout surfaces are sensitive.

When not to use it

  • Do not use checkout blocks for normal product page, cart, or collection changes.
  • Do not test unsupported checkout surfaces with this feature.
  • Do not launch checkout changes without stricter QA because checkout regressions are high impact.

Implementation source

  • The page lives under `src/app/(dashboard)/tests/[id]/checkout-block`.
  • Handlers include Shopify checkout-block config APIs and related experiment/Shopify event endpoints.
  • The runtime depends on Shopify extension constraints plus Apex experiment and revenue-event attribution.

Data and API

  • Checkout-block config records tied to experiment/variation records.
  • APIs under `/api/checkout-blocks/*` and Shopify event/revenue endpoints.
  • Shopify extension/runtime data plus Apex events.

Failure modes

  • Block not visible: extension not installed, checkout surface unsupported, targeting miss, or preview context missing.
  • Revenue not attributed: Shopify event settings or experiment IDs missing from events.
  • Checkout regressions require immediate pause and rollback.

Heatmaps, behavior screenshots, and visual evidence

Operator

Simple termsVisual evidence helps explain what visitors saw or did, not just whether the metric moved.

Adds visual and behavioral proof to analytics so teams can understand not only whether a test moved a metric but how visitors interacted.

/tests/[id]/analytics/api/heatmaps/*/api/behavior-screenshots/*

Implementation behavior

  • Behavior screenshots and heatmap endpoints store or query visual evidence tied to shop, page, experiment, variation, and time window.
  • Experiment detail can combine screenshots, event data, and conversion metrics into a richer readback.
  • Operator QA evidence can also include screenshots and observations gathered during preview.

How to use it

  • Use visual evidence when conversion movement needs explanation.
  • Compare control and treatment screenshots for obvious rendering differences.
  • Use heatmap or behavior data alongside visitor trails rather than as the only decision source.
  • Capture fresh evidence after variant changes.

When not to use it

  • Do not use heatmaps as the sole decision source for an experiment winner.
  • Do not compare screenshots captured before and after unrelated page/theme changes as if they are equivalent.
  • Do not overread sparse heatmaps with low traffic.

Implementation source

  • Experiment detail and analytics pages consume visual evidence APIs.
  • Handlers include `/api/analytics/experiment/[id]/heatmap`, `/api/analytics/experiment/[id]/heatmap/screenshots`, and behavior screenshot routes.
  • Evidence is keyed by shop, page, experiment, variation, device, and time window where supported.

Data and API

  • APIs under `/api/heatmaps/*`, `/api/behavior-screenshots/*`, screenshot jobs, and operator evidence endpoints.
  • Tinybird event streams plus persisted screenshot/evidence records.
  • Experiment and variation IDs connect visual evidence to results.

Failure modes

  • Missing screenshot: target page inaccessible, job failed, or evidence was captured before the variation rendered.
  • Heatmap sparse: not enough traffic or events in the selected time window.
  • Visual proof can mislead if traffic/device mix differs between variants.

Help, docs, brand surfaces, and generated references

Both

Simple termsThis is the documentation and support layer for users, operators, and developers.

The support layer for understanding Apex, finding help, sharing brand context, and inspecting machine-readable API documentation.

/docs/help/brand/api/v1/openapi.json

Implementation behavior

  • The docs route uses the supplied Apex Docs HTML design as the visual source of truth and renders the product manual from local data in this page.
  • The complete catalog documents every app route surface, while the API surface map documents route-handler families.
  • The generated endpoint reference is built from the local OpenAPI spec so public API docs stay aligned with code.
  • Help and brand routes provide user support and brand-facing collateral.

How to use it

  • Use Feature manuals for how each product area works.
  • Use Complete feature catalog when you need the route-level map.
  • Use API surface and Endpoint reference when integrating or debugging automation.
  • Use Help for support flows that are not specific to implementation details.

When not to use it

  • Do not treat docs as a replacement for live QA or current production monitoring.
  • Do not rely on the OpenAPI reference for internal dashboard APIs; it only covers public v1.
  • Do not let screenshots drift after major UI changes.

Implementation source

  • Docs live in `src/app/docs/page.tsx` and `src/app/docs/layout.tsx`.
  • OpenAPI source lives in `src/lib/api/openapi-spec` and is served at `/api/v1/openapi.json`.
  • Product shots live under `public/docs/product-shots`.

Data and API

  • Docs page data lives in `src/app/docs/page.tsx`.
  • OpenAPI source lives in `src/lib/api/openapi-spec` and is served at `/api/v1/openapi.json`.
  • Product shots are stored in `public/docs/product-shots`.

Failure modes

  • Docs drift when new routes or APIs are added without updating the manual and catalogs.
  • OpenAPI only covers public v1 endpoints; internal APIs need the API surface map.
  • Product shots need to be refreshed after major UI changes.
ReferenceBoth

Complete feature catalog

This is the exhaustive route-level map of the current Apex product. If a user can navigate to a page in the app, it is listed here with what that surface is responsible for.

Access and onboarding

8 surfaces

Login

Both
/login

Email/password authentication, Supabase session creation, password reset entry, and redirect handling for protected app routes.

Signup

Both
/signup

New-account entry point. Users can create an Apex account before creating or joining a workspace.

Verify email

Both
/verify-email

Email verification holding page after signup. It keeps unverified users out of protected workspace surfaces.

Reset password

Both
/auth/reset-password

Password update flow for users with a valid Supabase reset token.

Create workspace

Admin
/orgs/new

Creates a company or agency workspace. Agency workspaces unlock client management; company workspaces focus on one operating company.

Create store

Admin
/shops/new

Creates a shop under the active workspace, stores domain/name, and initializes the worker URL used by runtime config.

Store invitation acceptance

Both
/invitations/accept

Accepts store-level invitations with invalid, missing, accepted, declined, and expired states.

Workspace invitation acceptance

Both
/org-invitations/accept

Accepts organization invitations and adds the user to the workspace with the invited role.

Daily operating surfaces

11 surfaces

Launchpad

Operator
/

Shop-level command center with readiness stage, blockers, next move, setup checks, active tests, draft tests, and recent learning proof.

Ideas

Operator
/backlog

Prioritized backlog of concepts, approved ideas, linked drafts, source snapshots, comments, archive/restore state, and create-experiment action.

New backlog item

Operator
/backlog/new

Captures test, price, shipping, or landing-page concepts with evidence, target surface, and handoff context.

Concept detail

Operator
/backlog/[id]

Shapes the idea, evidence, prioritization, comments, Research Hub snapshot, Codex handoff, and linked experiment creation.

Experiments

Both
/tests

Experiment inventory with status filters, launch readiness, setup progress, draft blockers, linked backlog items, and create-test entry.

New experiment

Both
/tests/new

Creates a test with store URL, targeting, traffic allocation, schedule, goal selection, planned-test options, variants, and optional backlog linkage.

Experiment detail

Both
/tests/[id]

Full test workspace: setup checklist, goals, variants, status actions, launch blockers, analytics, QA actions, schedule, targeting, and developer metadata.

QA tab

Both
/tests/[id]?tab=qa

Forced preview URLs, variant verification, QA run state, screenshot evidence, and launch-readiness checks before traffic starts.

Variation editor

Both
/tests/[id]/variations/[varId]

The deepest builder surface: preview browser, Operator chat, selector tooling, mutation authoring, code mode, workspace files, build status, preview controls, QA evidence, artifacts, and save/apply behavior.

Checkout block experiment

Developer
/tests/[id]/checkout-block

Configures Shopify checkout-block experiment payloads and preview state for checkout-adjacent testing.

Results

Operator
/test-results

Readback surface for individual outcomes, imported external results, overall impact, and learnings that shape the next experiment.

Foundations

10 surfaces

Assets

Both
/assets

Upload and organize reference files, images, PDFs, and prompt material. Asset usage is tracked so teams know where a file is consumed.

Metrics

Both
/goals

Reusable click, pageview, custom, revenue, and Shopify-connected goals. Metrics can be primary or secondary inside tests.

New metric

Both
/goals/new

Creates success events with selectors, text match, URL patterns, event names, revenue settings, count-once behavior, and capture rules.

Visual metric builder

Operator
/goals/new/visual

Legacy visual builder redirect into the current metric creation path.

Audiences

Both
/audience

Reusable visitor groups and page groups for experiments and personalization, including page, traffic, behavior, and customer-signal rules.

New audience

Both
/audience/new

Rule-builder for URL, page, traffic source, device, behavior, Shopify/customer attributes, exact, wildcard, and regex targeting.

Signals

Operator
/signals

Visitor and storefront facts that Apex captures and reuses for audiences, feature flags, personalization, and Operator context.

Store profile

Operator
/store-profile

Brand memory and technical memory: profile facts, audit runs, evidence, storefront checks, findings, learning runs, and brand guideline presets.

Pages

Both
/pages

Legacy page targeting redirect. Current targeting is handled by audiences and segment rules while runtime still supports URL patterns.

New page

Both
/pages/new

Legacy new-page targeting redirect into the current audience and segment creation flow.

Analytics

8 surfaces

Analytics overview

Operator
/analytics

Top-level analytics tabs for overview, acquisition, behavior, funnels, traffic, visitors, realtime, ecommerce, quality, and experiment performance.

Audience analytics

Operator
/analytics/audience

Audience composition, visitor segments, and time-windowed audience behavior.

Traffic sources

Operator
/analytics/traffic

Traffic source, campaign, and acquisition quality breakdowns across 7, 30, and 90 day windows.

Visitor explorer

Operator
/analytics/visitors

Visitor records, sessions, identifiers, and event trails for debugging individual journeys.

Realtime analytics

Both
/analytics/realtime

Live event console for verifying install health, pageview flow, custom events, and QA traffic.

Funnels

Operator
/analytics/funnels

Full-funnel analysis with breakdowns, detected pages, saved funnels, run endpoint, and conversion-path summaries.

Funnel builder

Operator
/analytics/funnels/new

Builds funnels from detected URLs, custom steps, saved funnel definitions, and run-now analysis.

Flow

Operator
/analytics/flow

Path-flow view for entry pages, exit pages, movement between URLs, and behavioral drop-off patterns.

Advanced product surfaces

10 surfaces

Landing pages

Operator
/landing-pages

Typed editorial pages with current version, QA state, publish target, live URL, immutable bundles, previews, and Operator edits.

New landing page

Operator
/landing-pages/new

Starts from typed templates, initial content blocks, page type, publish mode, and Operator-adjustable block structure.

Landing page editor

Operator
/landing-pages/[id]

Apex Operator edits page blocks, renders versions, previews static pages, launches immutable R2 bundles, and manages publish state.

Landing page QA

Operator
/landing-pages/[id]/qa

Version-level preview links, QR codes, QA runs, approval state, and launch gating for landing pages.

Feature flags

Developer
/flags

Runtime toggles with status, rollout percentage, source experiment, delivery type, targeting, typed values, and archive/pause/activate actions.

New feature flag

Developer
/flags/new

Creates native Apex flags that SDK callers can evaluate and dashboards can toggle.

Feature flag detail

Developer
/flags/[id]

Off/on variants, targeting, decision debugger, payload value, typed values, rollout control, source experiment, and lifecycle metadata.

Personalization

Both
/personalization

Signal targeting, surfaces, priority, runtime status, rollout, and inventory of personalized experiences.

New personalization

Both
/personalization/new

Creates signal-driven storefront experiences with matching rules and structured experience payloads.

Personalization detail

Both
/personalization/[id]

Experience payloads, targeting, ordered rules, decision debugger, safe rollout, source, and lifecycle metadata.

Installation and runtime administration

7 surfaces

Store connection

Admin
/installation

Shopify connection state, app embed instructions, manual snippet, install verification, snippet settings, and setup flow.

Manual script install

Developer
/installation/manual

Copy-paste script install for non-Shopify stores: paste script, open site, verify events.

Runtime controls

Admin
/installation/runtime

Shop runtime settings for flicker behavior, consent behavior, debug mode, and QA cookies.

Edge routing

Developer
/installation/edge-routing

DNS, origin, custom hostname, SSL, fallback origin, and Worker-edge routing setup for custom domains.

Snippet inspector

Developer
/installation/snippet-size

Analyzes tracking snippet size, compression, payload composition, and runtime budget.

Experiment guardrails

Admin
/settings/guardrails

Shop-wide auto-pause defaults, sequential significance settings, fixed-horizon planned test options, minimum runtime, and per-test override model.

Profit analysis

Admin
/settings/integrations

Shopify integration and reconnect flow for order, product, inventory, cost, reconciliation, and profit-analysis scopes.

Workspace, team, and support

11 surfaces

Clients

Admin
/clients

Agency-workspace client list. Switch into a client workspace before working on that store’s tests and profiles.

Store team or agency team

Admin
/team

Team members, store invitations, workspace members, roles, and invite management. Content changes by workspace type.

Workspace settings

Admin
/org/settings

Workspace name, slug, type, ownership, and organization-level settings.

Workspace members

Admin
/org/members

Organization-level membership list and role management for workspace admins and owners.

Profile

Both
/account

User display name and image shown across Apex comments, ownership, and team surfaces.

API keys

Developer
/api-keys

Creates and manages publishable, test secret, and live secret API keys. Secrets are shown once, with permissions and expiration presets.

Webhooks

Developer
/webhooks

Webhook inventory, event subscriptions, endpoint status, delivery attempts, and create/detail routes.

New webhook

Developer
/webhooks/new

Configures endpoint URL, subscribed event types, and active state. The webhook secret is created with the endpoint.

Webhook detail

Developer
/webhooks/[id]

Shows endpoint configuration, delivery history, response status, retry/debug data, and active state.

Operator logs

Both
/operator-logs

Search persisted Operator runs, chat transcripts, tool/event timelines, artifacts, statuses, filters, and failure states.

Help

Both
/help

In-app resources, workflow links, FAQs, setup guidance, API docs link, and practical troubleshooting entry points.

Internal and brand surfaces

7 surfaces

Documentation

Both
/docs

The complete Apex documentation system: quickstart, product shots, operating workflow, feature manuals, route catalog, API surface map, data model map, endpoint reference, and troubleshooting.

Brand book

Both
/brand

Public Apex brand book surface and visual system reference.

Brand guidelines redirect

Both
/brand-guidelines

Redirects to the current brand documentation surface.

Admin dashboard

Admin
/admin

Internal ops dashboard for AI usage, database, queues, API access, models, workspaces, shops, and system state.

Admin ops

Admin
/admin/ops

Client launch readiness, runtime risk, alerts, monitors, SDK performance, runtime state, release metadata, Shopify signals, event stream, Sentry, and stale shops.

Admin releases

Admin
/admin/releases

Local, staging, and production release metadata, feature flags, latest manifests, recent release manifests, commit refs, and build information.

Admin test runner

Admin
/admin/tests

Internal runner for exercising admin-level diagnostics and operational tests.

ReferenceDeveloper

API surface map

This section documents the full internal and public route-handler surface by family. The generated OpenAPI reference below expands the public v1 API; this map also covers dashboard, Operator, analytics, Shopify, cron, and internal routes.

Public runtime

Browser-facing configuration, preview sessions, forced QA URLs, and harness artifacts used by the storefront runtime and QA surfaces.

6 routes
/api/exp/api/preview/api/preview-sessions/api/qa-preview/api/harness/sessions/[token]/manifest/api/harness/artifacts/[id]

Experiments and variants

Dashboard CRUD, lifecycle actions, launch checks, experiment-goal joins, conflict detection, and variation updates.

11 routes
/api/experiments/api/experiments/[id]/api/experiments/[id]/start/api/experiments/[id]/pause/api/experiments/[id]/complete/api/experiments/[id]/archive/api/experiments/[id]/restore/api/experiments/[id]/goals/api/experiments/[id]/create-flag/api/experiments/conflicts/api/variations/[varId]

Operator, variant workbench, and QA

Model-led build loop, context reduction, network introspection, persisted runs, screenshot capture, evidence storage, QA packets, code workspace files, build output, and revision diffs.

20 routes
/api/operator-chat-session/api/operator-context-reduce/api/operator-events/api/operator-evidence/api/operator-network/api/operator-runs/api/operator-screenshot/api/operator-dev-bridge/api/experiments/[id]/qa/api/experiments/[id]/qa/run/api/experiments/[id]/qa/goal-verification/api/experiments/[id]/qa/screenshots/api/experiments/[id]/variations/[variationId]/workspace/api/experiments/[id]/variations/[variationId]/files/api/experiments/[id]/variations/[variationId]/files/[...path]/api/experiments/[id]/variations/[variationId]/build/api/experiments/[id]/variations/[variationId]/revisions/api/experiments/[id]/variations/[variationId]/revisions/[revisionId]/diff/api/qa-audit/api/tools/search-code

Foundations and learning

Metrics, audiences, signals, assets, store profile memory, audit evidence, findings, and learning runs.

17 routes
/api/goals/api/goals/[id]/api/segments/api/segments/[id]/api/signals/api/signals/[id]/api/assets/api/assets/[id]/api/assets/[id]/usage/api/store-profile/api/store-profile/facts/[id]/api/store-profile/findings/review/api/store-profile/learning-runs/api/shop-audits/api/shop-audits/collect/api/shop-audits/profile/api/shop-audits/findings/[id]

Backlog and results

Idea intake, comments, archive/restore, experiment creation from ideas, handoff packets, Research Hub import, and result import/readback.

12 routes
/api/backlog/api/backlog/[id]/api/backlog/[id]/archive/api/backlog/[id]/restore/api/backlog/[id]/comments/api/backlog/[id]/comments/[commentId]/api/backlog/[id]/create-experiment/api/backlog/[id]/codex-handoff/api/internal/research-hub/backlog/import/api/test-results/api/test-results/import/preview/api/test-results/import/confirm

Analytics

Dashboard metrics, exports, experiment stats, behavior analytics, heatmaps, funnels, detected pages, goal suggestions, realtime debugging, traffic, visitors, ecommerce, geo, quality, and semantic learning.

27 routes
/api/analytics/dashboard/api/analytics/dashboard/export/api/analytics/timeseries/api/analytics/experiment/[id]/api/analytics/experiment/[id]/behavior/api/analytics/experiment/[id]/behavior-summary/api/analytics/experiment/[id]/heatmap/api/analytics/experiment/[id]/heatmap/screenshots/api/analytics/full-funnel/api/analytics/funnels/api/analytics/funnels/[id]/api/analytics/funnels/[id]/run/api/analytics/pages/api/analytics/suggest-goals/api/analytics/realtime/api/analytics/traffic/api/analytics/visitors/api/analytics/flow/api/analytics/ecommerce/api/analytics/geo/api/analytics/sessions/api/analytics/entry-exit/api/analytics/measurement-quality/api/analytics/shopify-reconciliation/api/analytics/insights/api/analytics/semantic/findings/api/analytics/semantic/sequences

Advanced products

Landing page generation, page-specific Operator tools, rendering, publish, QA, feature flag lifecycle, and personalization lifecycle.

18 routes
/api/landing-pages/api/landing-pages/[id]/api/landing-pages/[id]/chat/api/landing-pages/[id]/operator-tools/api/landing-pages/[id]/publish/api/landing-pages/[id]/qa/api/landing-pages/[id]/versions/[versionId]/render/api/landing-pages/preview/[versionId]/api/flags/api/flags/[id]/api/flags/[id]/activate/api/flags/[id]/pause/api/flags/[id]/archive/api/personalizations/api/personalizations/[id]/api/personalizations/[id]/activate/api/personalizations/[id]/pause/api/personalizations/[id]/archive

Installation, Shopify, edge, and jobs

Install verification, shop switching, runtime settings, Shopify OAuth/pixel/settings/snippet/checkout-blocks, Cloudflare domain routing, edge resolution, snippet precompile, background jobs, and cron maintenance.

22 routes
/api/onboarding/verify-install/api/shops/api/shops/switch/api/shops/runtime-settings/api/shops/auto-stop/api/shopify/auth/api/shopify/auth/callback/api/shopify/claim/api/shopify/webhooks/api/shopify/settings/api/shopify/snippet/api/shopify/checkout-blocks/config/api/internal/domain-routing/discover/api/internal/domain-routing/preflight/api/internal/domain-routing/configure/api/internal/domain-routing/verify/api/internal/edge/resolve/api/internal/snippet/precompile/api/internal/jobs/process/api/cron/cleanup-webhooks/api/cron/archive-experiments/api/cron/ops-check

Workspace, team, API access, webhooks, privacy, and admin

User profile, workspace and team membership, invitations, ownership transfer, API key management, webhook management, privacy exports/deletion, audit logs, admin diagnostics, and health checks.

33 routes
/api/account/profile/api/orgs/api/orgs/switch/api/orgs/[orgId]/api/orgs/[orgId]/members/api/orgs/[orgId]/members/[id]/api/orgs/[orgId]/invitations/api/orgs/[orgId]/invitations/[id]/api/orgs/[orgId]/leave/api/orgs/[orgId]/transfer-ownership/api/org-invitations/accept/api/org-invitations/decline/api/invitations/accept/api/invitations/decline/api/team/members/api/team/members/[id]/api/team/invitations/api/team/invitations/[id]/api/team/leave/api/team/transfer-ownership/api/api-keys/api/api-keys/[id]/api/v1/webhooks/api/v1/webhooks/[id]/api/v1/data-export/api/v1/data-deletion/api/audit-logs/api/admin/ops/api/admin/usage/api/admin/tests/api/admin/tests/run/api/health/api/health/deep

Public API v1

External automation API authenticated by Apex API keys. It includes experiment CRUD, harness sessions, and Apex CLI workspace checkout, file sync, build, and revision routes. The generated endpoint reference below expands these methods from the OpenAPI spec.

25 routes
/api/v1/openapi.json/api/v1/experiments/api/v1/experiments/[id]/api/v1/experiments/[id]/start/api/v1/experiments/[id]/pause/api/v1/experiments/[id]/complete/api/v1/experiments/[id]/duplicate/api/v1/experiments/[id]/screenshots/api/v1/experiments/[id]/variations/[variationId]/workspace/api/v1/experiments/[id]/variations/[variationId]/files/api/v1/experiments/[id]/variations/[variationId]/files/[...path]/api/v1/experiments/[id]/variations/[variationId]/build/api/v1/experiments/[id]/variations/[variationId]/revisions/api/v1/experiments/[id]/variations/generate/api/v1/experiments/by-slug/[slug]/api/v1/experiments/conflicts/api/v1/experiments/generate/api/v1/variations/api/v1/variations/[id]/api/v1/goals/api/v1/goals/[id]/api/v1/screenshots/[jobId]/api/v1/harness/sessions/api/v1/harness/sessions/[id]/versions/api/v1/harness/sessions/[id]/publish
ReferenceDeveloper

Data model map

Apex is backed by Prisma models in Supabase Postgres. This map groups the current schema so developers understand which objects power each feature family.

Tenancy and access

Workspace, shop, team, invitation, profile, API credential, audit, and privacy-request ownership boundaries.

OrganizationOrgMemberOrgInvitationShopShopMemberInvitationUserProfileApiKeyAuditLogPrivacyRequest

Experimentation

Core test setup, targeting, metrics, variants, QA runs, screenshots, heatmaps, archives, behavior insight, and result readback.

ExperimentVariationGoalExperimentGoalSegmentSignalPageExperimentQaRunScreenshotJobHeatmapScreenshotExperimentArchiveExperimentBehaviorInsightTestResult

Operator and workbench

Persisted agent runs, chat messages, tool timelines, artifacts, code workspaces, revisions, preview sessions, and usage logging.

OperatorRunOperatorMessageOperatorEventCodeArtifactExperimentWorkspaceExperimentWorkspaceFileExperimentWorkspaceRevisionPreviewSessionAiUsageLog

Store intelligence

Runtime controls, store checks, evidence, findings, brand profile, technical profile, learning runs, facts, and reference assets.

ShopRuntimeSettingsShopAuditRunShopAuditEvidenceShopAuditFindingShopBrandProfileShopTechnicalProfileShopLearningRunShopStoreEvidenceShopStoreFactAsset

Advanced runtime

Flags, typed payloads, personalized experiences, generated landing pages, published versions, QA runs, external harness sessions, and saved funnels.

FeatureFlagFeatureFlagVariantPersonalizationPersonalizationRulePersonalizationExperienceLandingPageLandingPageVersionLandingPagePublishLandingPageQaRunHarnessSessionFunnel

Shopify and delivery

Shopify OAuth/install state, product cost data, pixel event settings, webhook endpoints, and webhook delivery records.

ShopifyInstallationShopifyVariantCostShopifyEventSettingWebhookWebhookDelivery

Enums

The controlled vocabularies used by status filters, lifecycle actions, targeting types, workspace roles, and runtime delivery modes.

ExperimentStatusGoalTypePatternTypeShopRoleInvitationStatusOrgRoleWorkspaceTypeSegmentTypeSegmentStatusBacklogStatusBacklogActionTypeFeatureFlagStatusFeatureFlagDeliveryTypePersonalizationStatusPersonalizationDeliveryTypeLandingPageStatusLandingPagePublishModeLandingPageTypeApiKeyTypePrivacyRequestTypePrivacyRequestStatusAuditAction
ReferenceDeveloper

Endpoint reference

API for managing A/B testing experiments, variations, goals, webhooks, and screenshots.

Base URL

https://app.drip-apex.com/api/v1

OpenAPI spec

The full OpenAPI 3.1 document is available at /api/v1/openapi.json.

Roadmap2 endpoints

Experiments11 endpoints

Variations5 endpoints

Apex Workspace6 endpoints

Goals5 endpoints

Screenshots2 endpoints

Webhooks4 endpoints