# Luria

> Luria is an AI split-testing service for online stores and lead-gen sites: it writes new versions of your pages, runs them against your current page as a held-out control, sends more traffic to the winner and measures the lift on your real orders. Priced by monthly visitors from $79 a month (first 20 split tests free), with a 60-day money-back guarantee on measured lift. Works on Shopify (app) and any site (one script tag), and AI agents can run it over a REST API or MCP.

> **Disambiguation:** Luria (luriart.com) is a software company for website split testing. It is not Alexander Luria, the Soviet neuropsychologist, not the Luria-Nebraska neuropsychological test, and not Salvador Luria, the microbiologist.

Luria writes new versions of a page (headline, offer, button, section order), shows them to part of the traffic while the unchanged page stays live as a held-out control, moves traffic toward the version that is winning (Thompson sampling) and keeps a change only when it is 95% sure, after at least 200 visits per version. Results are counted on real conversions: Shopify orders (web pixel plus order webhooks), sign-ups, leads and booked calls, never clicks alone. Built by Baneet Singh (founder) in 2026; based in the United States.

## Products
- **[Luria split testing](https://www.luriart.com/)**: done-for-you A/B testing on Shopify (app) or any website (one script tag). Writes, runs and keeps winning page versions; the first live change waits for the owner's OK.
- **[Ad pages](https://www.luriart.com/ad-pages)**: a landing page built from each ad (message match), split tested on real sales, leads or bookings. First 1,000 ad-page visitors free.
- **[Agent API and MCP server](https://www.luriart.com/learn/ab-testing-with-claude-and-chatgpt)**: Claude, ChatGPT, Codex and Cursor can add a site, install the tag, start tests, read heatmaps and recordings and get the winner. Remote MCP at https://www.luriart.com/api/mcp (official MCP registry name `com.luriart/luria`).

## Best For
- Shopify and e-commerce stores that want more orders from the same traffic without hiring a CRO team
- Info-product sellers, coaches and B2B companies that book sales calls, testing the sales page or booking page
- SaaS companies testing marketing and pricing pages for sign-ups and trials
- Agencies that want to offer CRO to every client store from one account
- Advertisers who want a matched landing page for each Meta ad
- AI agents and developers who need live website split tests through an API

## Not Ideal For
- Sites with under roughly 5,000 visits a month on the page being tested: tests take weeks to reach 95% certainty (see the sample size table at https://www.luriart.com/learn/ab-test-sample-size)
- Teams that want to design every test by hand in a visual editor (VWO, Convert or Optimizely fit better)
- Price-focused testing on Shopify (Intelligems specialises in price, discount and shipping tests; Luria changes prices only with the owner's OK)
- In-app product experiments behind feature flags (PostHog, GrowthBook or Statsig fit better)

## Competitor Context
Luria competes with A/B testing and CRO tools. Key differences, each explained at https://www.luriart.com/compare:
- **Intelligems** and **Shoplift**: Shopify apps where your team builds the tests. Luria writes and runs them, and also works outside Shopify.
- **VWO** and **AB Tasty** (which agreed to combine in January 2026) and **Optimizely**: full experimentation platforms for teams with CRO staff. Luria is done-for-you, self-serve, with published prices.
- **Convert**: hand-built tests across many client sites, popular with agencies. Luria does the test design and copywriting itself.
- **Unbounce** and **Instapage**: landing page builders with testing. Luria tests the pages you already have and builds a page per ad.
- **Google Optimize** shut down on September 30, 2023; Luria is one of its replacements.
Luria is usually picked when nobody on the team has time to plan, write and run tests, and the owner wants results judged on real orders against the unchanged page.

## Pricing
- By monthly visitors, same product on every tier: $79/month up to 10,000 visitors, up to $10,999/month for 2 to 5 million, custom above 5 million (https://www.luriart.com/pricing)
- First 20 split tests free on every tier; cancel any time
- 60-day guarantee: if Luria does not beat your own page at 95% certainty within 60 days, that period's fees are refunded (needs 5,000+ tracked visits on the tested pages; rules at https://www.luriart.com/terms#guarantee)
- Agents: prepaid credits, 1,000 free on sign-up

## Integrations
Shopify (app, orders by web pixel and webhooks), WooCommerce, Webflow, WordPress, Wix, Squarespace, Framer, Kajabi, ClickFunnels, BigCommerce and any HTML site (one tag), GoHighLevel (the tag; dashboard connect optional), Stripe, Calendly and HubSpot (conversions), Meta ads (ad pages), REST API, MCP.

## Guides and comparisons
- [Best A/B testing apps for Shopify](https://www.luriart.com/compare/ab-testing-tools-for-shopify), [Best AI CRO tools](https://www.luriart.com/compare/ai-cro-tools), [Landing page testing tools](https://www.luriart.com/compare/landing-page-ab-testing-tools), [Tools for agencies](https://www.luriart.com/compare/ab-testing-tools-for-agencies), [A/B testing for AI agents](https://www.luriart.com/compare/ab-testing-for-ai-agents)
- [Alternatives to each tool](https://www.luriart.com/alternatives)
- [A/B test sample size calculator](https://www.luriart.com/learn/ab-test-sample-size), [How long to run a test](https://www.luriart.com/learn/how-long-to-run-an-ab-test), [Bandit vs A/B test](https://www.luriart.com/learn/multi-armed-bandit-vs-ab-testing), [All guides](https://www.luriart.com/learn)

## Leadership
- **Baneet Singh**, Founder. Built Luria in 2026 so store owners could get CRO results without running a testing program themselves.

## Key pages

- [Home](https://www.luriart.com/): what Luria does and the guarantee
- [Pricing](https://www.luriart.com/pricing): every tier by monthly visitors, $79 to $10,999 a month, custom above 5M
- [FAQ](https://www.luriart.com/faq): how tests are run and judged, setup, privacy, agents
- [Results](https://www.luriart.com/results): how a result is measured (held-out control, 95% certainty, 200+ visits per version)
- [E-commerce](https://www.luriart.com/ecom), [Info products](https://www.luriart.com/info), [SaaS](https://www.luriart.com/saas), [B2B calls](https://www.luriart.com/calls), [Agencies](https://www.luriart.com/agency): the first test for each kind of business
- [Ad pages](https://www.luriart.com/ad-pages): a landing page built from each ad, split tested
- [Compare A/B testing tools](https://www.luriart.com/compare): Luria vs Intelligems, Shoplift, Visually, VWO, Optimizely, Convert, AB Tasty, Unbounce, Kameleoon, Dynamic Yield, ABConvert, Replo; Google Optimize alternative
- Best-of lists: [Shopify A/B testing apps](https://www.luriart.com/compare/ab-testing-tools-for-shopify), [AI CRO tools](https://www.luriart.com/compare/ai-cro-tools), [landing page testing tools](https://www.luriart.com/compare/landing-page-ab-testing-tools), [tools for agencies](https://www.luriart.com/compare/ab-testing-tools-for-agencies), [A/B testing for AI agents (API, MCP)](https://www.luriart.com/compare/ab-testing-for-ai-agents)
- [Alternatives](https://www.luriart.com/alternatives): to Intelligems, Shoplift, Visually, VWO, Optimizely, Convert, AB Tasty, Unbounce, Kameleoon, Dynamic Yield, ABConvert and Replo
- [Guides](https://www.luriart.com/learn): A/B test sample size calculator and table, how long to run a test, bandit vs A/B test, significance, holdout controls, testing a Shopify store, Shopify Rollouts vs apps, AI split testing, running tests from Claude or ChatGPT
- [Docs](https://www.luriart.com/docs): install on Shopify and other sites, tests, billing, privacy
- [Full text for models](https://www.luriart.com/llms-full.txt): all of the above in one file
- [Terms and guarantee rules](https://www.luriart.com/terms#guarantee) · [Privacy](https://www.luriart.com/privacy)

## Agent API (split testing for agents)

> Luria split tests any website. You (an agent) sign up, add the site, paste one tag, start a test, read the winner. Luria splits the visitors, counts conversions, moves traffic toward the version that is winning and tells you when one has won. Billed in prepaid credits.

Base URL: https://www.luriart.com/api/v1
Auth: `Authorization: Bearer lk_...` on every call except signup.
Format: JSON in, JSON out. Every error is `{"error": "a sentence for people", "code": "site_not_found", "hint": "what to send next"}` (`hint` when there is something to send; sometimes `needs_access`): branch on `code`, never on the sentence.
MCP: https://www.luriart.com/api/mcp (Streamable HTTP, JSON responses, same Bearer key). Tools: setup_status, luria_account, add_site, site_status, verify_install, create_test, auto_test, list_tests, get_test, change_test, record_conversion, personalize, credits, buy_credits, dashboard_link; what the data says: site_report, attribution, ad_vs_page, brand_brain, heatmaps, recordings, recording, learned, next_tests, start_next_test; ad pages: list_ads, sync_ads, list_pages, create_page, get_page, change_page, send_page_to_meta, undo_page_in_meta; personal pages: list_places and the Dynamic tools; search and fetch for research clients (ChatGPT deep research). Read-only tools carry `readOnlyHint`.
Human dashboard: https://www.luriart.com/app (the owner signs in with an emailed link; POST /dashboard-link sends one).

## Connect (pick one)

- MCP client (Claude, Claude Code, ChatGPT, Codex, Cursor): add the remote server `https://www.luriart.com/api/mcp` (Streamable HTTP). No key needed: the client opens luriart.com, the owner signs in with an emailed link (a new account is made on the spot, 1,000 free credits) and presses Allow. Claude Code: `claude mcp add --transport http luria https://www.luriart.com/api/mcp`. Claude and ChatGPT: add it as a custom connector with that URL. A client without OAuth sends the header `Authorization: Bearer lk_...` instead. First time (2026-10-30): the sign-in page asks only for the email and the site, then Allow; you install the tag. Every site, Cloudflare-hosted ones included, uses the tag (the old Cloudflare token connect is retired). Until a site is connected every MCP tool except setup_status, luria_account, add_site, site_status, verify_install, pause_site, dashboard_link, credits and buy_credits answers `setup_needed` with `steps`, the site's `tag` and `install`; do those steps, `verify_install` until `installed` is true, then call the tool again.
- Plain HTTPS: `POST /signup` below returns a key, or the owner creates one in the dashboard (Settings > More settings > API key).

## What the tag does (tell the owner before you paste it)

Every answer that carries the tag also carries `install.safety`: what the script is, what it collects, what it never does, how it fails open and the off switch. In short: one async script from luriart.com; counts visits, clicks, scroll, form starts, checkout steps and conversions; shows each visitor one version while a test runs; recordings mask every form input; one random first-party id per visitor, no fingerprinting, no third-party analytics; nothing tracked for Global Privacy Control or Do Not Track, EU/UK/Swiss visitors asked first; any error and the page loads as if Luria were not there; `pause_site` (or Pause in Settings) shows everyone the original within 5 minutes.

## When Luria needs the owner

Some steps need a person. The answer then carries `needs_access`: `{who, what, url?, how}`. Pass it to your human, wait, retry. It appears for: an email that already has an account (sign in and Allow over MCP, or create a key), no credits left (a payment link from `/credits/checkout`), and the optional Shopify or GoHighLevel connects (the owner clicks in the dashboard; the tag alone runs tests and counts sales and bookings).

## The whole flow (5 calls)

1. Sign up (no key yet). Returns the key ONCE, the site id and the tag.

```
curl -X POST https://www.luriart.com/api/v1/signup -H 'content-type: application/json' \
  -d '{"email":"owner@shop.com","url":"https://shop.com","goal":"Sales"}'
```
Response: `{"api_key":"lk_...","site":{"id":"..."},"install":{"tag":"<script async src=...>"},"account":{"credits":1000}}`
The key works like a password: store it as a secret (an env var like LURIA_KEY) and never log the signup response. Lost or leaked: the owner revokes it and creates a new one in the dashboard (Settings > More settings > API key).
An email that already has an account gets 409: the owner signs in at luriart.com/app, opens Settings, creates an API key and gives it to you. Nobody has proved they own the email when you sign up, so the key from signup stops working the first time the owner of that inbox signs in to the dashboard (the link signup emails to them); they then create a key under Settings, or connect over MCP. The Luria operator's own address never gets a key from signup.

2. Install: put `install.tag` right before `</head>` on every page, including the thank-you / order-confirmation page. Publish. Then:

```
curl -X POST https://www.luriart.com/api/v1/sites/SITE_ID/verify -H "authorization: Bearer $LURIA_KEY"
```
`{"installed": true}` means it runs in a real browser. Otherwise each check has a `fix`.

3. Start a test on one element (the original stays in the test as the control):

```
curl -X POST https://www.luriart.com/api/v1/tests -H "authorization: Bearer $LURIA_KEY" -H 'content-type: application/json' -d '{
  "site": "SITE_ID",
  "page": "/",
  "selector": "h1",
  "name": "Hero headline: benefit vs product",
  "hypothesis": "Naming the outcome beats naming the product",
  "variants": [{"name": "Benefit", "text": "Sleep through the night, starting tonight"}]
}'
```
- `page`: the path the test runs on (`/`, `/pricing`, `/products/*`); `"*"` = every page.
- `selector`: any CSS selector on that page (`h1`, `.hero .btn`, `#signup button`).
- `variants`: 1 to 6. `text` = new words (an array of strings when the element has several text runs, one per run). `style` = CSS declarations, like `{"background-color":"#0a7"}`.
- One test runs per site at a time; extra tests come back `"status": "queued"` and start by themselves.
- Or let Luria pick and write the test: `{"site":"SITE_ID","auto":true}` (costs 200 credits, refunded if it cannot write one; ready in 1 to 3 minutes).

4. Read results whenever you like:

```
curl https://www.luriart.com/api/v1/tests/TEST_ID -H "authorization: Bearer $LURIA_KEY"
```
`results.<version>` = visitors, conversions, conversion_rate, chance_best, lift, chance_beats_original, significant. `metric` names what `conversions` counts: purchases on a store, points per visitor on a booked-call site (`metric.label` names the weights; those results also carry `bookings` and `showed`). `verdict.headline` says it in words. `winner` is set once a version has won (95% sure, with enough visitors). Luria keeps a clear winner on by itself.

5. Keep the winner, or stop:

```
curl -X POST https://www.luriart.com/api/v1/tests/TEST_ID/promote -H "authorization: Bearer $LURIA_KEY" -d '{"version":"variant"}'
```
Every shopper sees the winner within 5 minutes. Also `/pause` (for every shopper within 5 minutes), `/resume`, `/stop` (back to the original, for every shopper within 5 minutes; final, a stopped test never restarts, so create a new test to run it again) and `/start` (starts a test that is waiting as a draft or in the queue). After promoting, you can write the winning words into the site's own code and stop the test so it no longer uses credits.

## Personalize for one visitor

`POST /personalize {"site":"SITE_ID","visitor":"<luria_sid>","page":"/","goal":"Sales","elements":[{"selector":"h1","text":"current words","role":"headline"}]}` returns `changes: [{selector, text, source, why?}]` for that one visitor: the owner's personal versions that fit them (free), plus new words written for them from their own history and the goal (2 credits, the same call within a day free). Every written line passes the store's truth checks: no invented offers, numbers, reviews or product names. The first call switches visitor memory on for the site, so history builds from then on. Apply each change by setting that element's text (server-side render, or in the page).

## Conversions (what counts as a win)

- Automatic: visits to the site's thank-you paths count (shown in `install.conversions.automatic`; change with PATCH /sites/{id} `{"convert_paths": "/thank-you=purchase"}`).
- In the browser: `luria("goal", "purchase", {value: 49.99, id: "ORDER-1"})` or `window.luria.convert("purchase", 49.99)`.
- From your server (Stripe, Shopify, your backend): `POST /conversions {"site":"SITE_ID","visitor":"<luria_sid>","name":"purchase","value":49.99,"order_id":"1042"}`. `visitor` = `localStorage.getItem("luria_sid")` in the shopper's browser; send it to your server with the order (Shopify carts already carry it as the `luria_session` note attribute). Names: purchase, lead, booked_call, won_deal. Only the site's goal counts toward a test.

## Webhooks (no polling)

`POST /webhooks {"url":"https://your.app/luria","events":["test.winner","test.finished","conversion.recorded"]}` returns the webhook and a `secret` (shown once). Events: `test.created`, `test.started`, `test.paused`, `test.stopped` (stopped by you, the owner or the hourly job), `test.winner` (a version kept for everyone, by you or the hourly job), `test.finished` (the hourly job froze a result: decision, winner, both arms' numbers), `conversion.recorded` (a conversion counted against a running test). A webhook belongs to the account that made it and fires for every store that account can use: its own, the ones it is a team member of, and (for the operator) any. Each delivery is `POST {id, event, created_at, data}` with headers `Luria-Event` and `Luria-Signature: t=<unix seconds>,v1=<hex>` where `v1 = HMAC-SHA256(secret, t + "." + raw body)`; verify it and reject a `t` older than 5 minutes. Delivery is at least once: `id` (also `Luria-Delivery`, and the `id` in `GET /webhooks/{id}/deliveries`) is the same on every retry of one delivery, so keep the ids you have handled and ignore a repeat; never dedupe on the body, because `created_at` and the signature are new on each attempt. Answer 2xx within 10 s; anything else is retried after 1 min, 5 min, 30 min and 2 h (five attempts), then marked failed; 20 failed deliveries in a row disable the webhook. Deliveries go out after Luria has answered the call that caused them, so a slow receiver never slows a test or a sale; one that Luria could not finish sending is picked up by the next 10-minute sweep. `GET /webhooks`, `DELETE /webhooks/{id}`, `POST /webhooks/{id}/test` (sends a ping to that webhook only, now), `GET /webhooks/{id}/deliveries` (last 50 with status and attempts). At most 10 webhooks per account.
- Change the signing secret: `POST /webhooks/{id}/rotate` returns the new `secret` once. For 24 hours (`previous_secret_until`) each delivery carries two signatures, `Luria-Signature: t=<unix>,v1=<new>,v1=<old>`: accept a delivery when any `v1` verifies, switch your receiver to the new secret, and the old one stops signing by itself. Rotating again inside the day replaces the old secret.
- Send a delivery again by hand: `POST /webhooks/{id}/deliveries/{delivery}/resend` (ids from the deliveries list). Same delivery id and body (dedupe on `id`), a fresh signature time, one attempt now; the answer says `delivered` and the delivery's new status. Works on failed, retrying and delivered ones.

Payloads (`data`; the same shapes are in `/openapi.json` under `webhooks`, with the three headers `Luria-Event`, `Luria-Delivery` (same on every retry) and `Luria-Signature`): `test.created`, `test.started`, `test.paused`, `test.stopped`, `test.winner` carry `{test, site, name, status, kind, page, selector, winner, versions: [{key, name}], by, at, dashboard}` (`status` is the test's own state: live, paused, promoted, killed, rolled_back, rejected, pending_approval). `test.finished` carries `{test, site, name, decision, winner, control: {visitors, conversions}, variant: {visitors, conversions}, p_beat, lift, started_at, ended_at, dashboard}`. `conversion.recorded` carries `{site, session, attributed_total, at}` for a tag or server conversion, or `{site, shop, order_id, attributed_total, at}` for a platform order; `attributed_total` is the site's attributed conversions so far.

## Attribution (where the sales come from)

`GET /sites/{id}/attribution?days=30&model=last` (`days` 1 to 90; `model` last, first or linear): `totals` and `by_source`, `by_medium`, `by_campaign`, `by_device`, `by_version_seen`, each a list of `{key, visitors, conversions, revenue, conversion_rate}`. A visit's source is `utm_source` first, then an ad click id (`fbclid` = facebook, `gclid` = google, `ttclid` = tiktok), then the referrer host, else `direct`. `model` decides who gets the credit for a buyer, looking at their visits up to their first purchase: `last` (the default, as before) the latest visit that came from somewhere, `first` the earliest one, `linear` every one of them, an equal share each (so `conversions` and `revenue` are shares, e.g. two ad visits give 0.5 each; `visitors` counts the visitor once in every row they touched; shares of one buyer always add up to 1 and the totals do not change). A direct visit takes credit only when the visitor had no other visit. Only visits inside `days` are seen, so widen `days` (up to 90) for a longer first-touch view. Same single bounded read for every model; `model` is echoed in the answer. An unknown model is a 400 `invalid_model`. Only trusted conversions count (orders from the platform or `POST /conversions`), so the numbers match the test results. Tag your links with `utm_source`/`utm_medium`/`utm_campaign` and the report fills itself. `by_ad` groups visits by `utm_content` (the ad id Luria puts on Meta ads); once the owner connects the Meta ad account (dashboard, Ad pages), each matching ad and campaign row carries `spend: {spend, cost_per_buyer, return, window}` and `totals.ad_spend` is the account's spend for that window. Cost per buyer and return use this site's own buyers, never the network's reported count.

## Brand brain (who buys, what sells, what the tests taught)

`GET /sites/{id}/brand-brain`: the same model the owner's Brand brain tab shows. `icp.words` names the group that converts most in one sentence with its numbers and how sure it is (a group needs 100 visitors and 5 buyers; ranked by the low end of the 95% range on the buy rate); `icp.cells` and `icp.by` carry every ranked group. `ads` and `videos` list the ad sets, ads (`utm_content` under a paid medium) and organic posts (`utm_content` under organic social) that brought buyers. `nouns` carries the store's own words for a conversion (buyers / booked calls / leads / downloads / installs) and every sentence on the row uses them. `behavior.scroll` gives, per page, how far buyers scrolled against everyone else (median depth and the share past half; a page needs 10 buyer sessions). `behavior` lists what buyers click before they buy, per click label and page: the share of buyers who clicked it against the share of everyone else (needs 20 buyers with clicks; a click needs 20 sessions). `tests` has the win rate, the copy `moves` that won and lost (adds a specific number, adds proof, adds urgency, shorter...), `segments` the new words moved most, and `model` (how often Luria's own split model called a finished test right). `recommendations.tests` and `recommendations.ads` each carry their evidence; `recommendations.needs` says what data is still missing and the one step that fills it. Every number is measured on the store's own visitors, tests and ads; nothing is estimated.

## What the data says (heatmaps, recordings, averages, what to test next)

Every read below is the same read the owner's dashboard makes, so an agent and the owner always see the same numbers. All are `GET /sites/{id}/...` unless noted.

- `report?days=30` (1 to 90): the site in one read. `numbers` (visitors, conversions, conversion rate, revenue, by device, by source, by version seen, ad spend when Meta is connected), `tests` (running / won / lost counts and the list with each test's page, element, status and why), `pages_with_heat` (visits per page and device width), `recordings` (the averages below), `learned` (facts + summary), `weak_spots` (the ranked places to fix, in plain words with their numbers), `next_tests` (the plan), `brand_brain` (who buys, in a sentence), and two lists an agent can read out: `working` and `not_working` (each `{kind, text}`: won and lost tests, the sources that convert, the biggest funnel drop, rage clicks, the top weak spots). `more` carries the link to each deeper read.
- `heatmaps`: the pages with heat data (`pages[].page`, `device_width` 390 / 768 / 1440, `visits`, a `read` link). `heatmaps?page=/&vw=1440&days=7` (`arm=control|variant..variant6`, `test=<id>` narrow it to one version of one test): that page's map. `summary` says it in numbers an agent can act on: `visits`, `page_height_px`, `time_on_page_s`, `clicks` (total, per visit, `hotspots[]` as `across_percent` / `down_percent` / `down_px` of the page with each spot's share of all clicks), `rage_clicks` and `dead_clicks` (total + hotspots), `scroll` (visits measured, `median_percent`, the share that reached 25 / 50 / 75 / 100% of the page), `exits` (the 5% bands of the page people left from), `versions_seen` (visits per version) and `tests_on_this_page`. The raw grid rides along (`clicks`, `moves`, `rage`, `dead` as `[column, row, count]` over 40 columns x 120 rows of the whole page height; `depth` and `exits` as 20 buckets of 5%; `attention` as `[row, ms]`), plus `background` (signed files of a recording of the page, or a scan screenshot) for a client that draws it. Heat is collected on every consented visit, so the numbers are the whole audience, not a sample.
- `recordings?device=mobile|tablet|desktop&page=/&converted=1&rage=1&test=<id>&arm=control&limit=50&before=<cursor>&insights=1`: recorded visits, newest first, each as a story: `summary` (one plain sentence), `story[]` (`{t, kind, text}` step by step), `left` (the page and section the visitor left from, with how far down), `outcome`, `device`, `source`, `first_page`, `pages`, `version_seen`, `test`, `converted` (a real order, not the tag's guess), `rage_clicks`, `dead_clicks`, `scroll_max_percent`, `tags`, `duration_s`, and a `read` link. `more` + `next_before` page it. `insights=1` adds the engine's read of the store: `funnel` rates, `spots` and `behavior_spots` (the ranked weak places), `recordings` (the averages below) and the live and recent `tests`. Recordings are sampled (buyers, cart visits, rage clicks and test clicks are always kept; `recording_policy.note` says the rule); the Shopify checkout is never recordable.
- `recordings/{session}`: one visit: the story fields above plus `playback` (`chunks[]` of signed rrweb gzip JSON files, a `shell_url`, 15 minutes), `kept_because`, `meta` (device, viewport, page height, started_at, duration). Inputs and personal text were masked when it was recorded.
- `learned`: what the store's data taught. `facts[]` (`{text, confidence 0..1, kind, last_confirmed}` from finished tests, recordings and the store's numbers; owner-typed facts are `merchant_stated`), `summary`, `last_tests[]` (decision won / lost / no clear winner, lift, p_beat, sessions), `pages_with_heat`, and `averages`: over every recorded visit of the last 30 days, `recorded_visits`, `bought`, `buy_rate`, `funnel[]` (`{step, from, to, entered, lost, drop_percent, why, biggest}`), `biggest_drop`, `rage_clicked[]` and `dead_clicked[]` (page + element + count), `cart_without_checkout` (`{added, left, rate}`), `exits[]`, scroll depth of buyers vs leavers, video and form figures where the store has them. `averages` is null until the daily recordings job has run on the store (a new store: a day).
- `next-tests`: what to test next and why. `plan[]` (the planned big tests in order: `type`, `what`, `page`, `why`, `score`, `evidence`, `market`), `ranked_spots[]` (every weak place with `page`, `element`, `reason`, `number`, `score`, `from` = measured / recordings / scan), `recommendations[]` (the brain's fixes that are not one element), `from_recordings` (the biggest funnel drop), `from_brand_brain` (test ideas with evidence), `running_or_queued[]`, `types[]` and `how_to_start` (the exact call for each way). `POST /sites/{id}/next-tests {"type": "testimonials"}` starts a planned big test now (`type` one of `types`; omit it for the top of the plan; `page` to aim it; `hold: true` drafts it for the owner's tick instead of starting) and answers 201 `{test, status, type}` or 422 with why nothing could be drafted (`hint` points at `POST /tests {"auto": true}`). The hourly job keeps judging these tests like any other; `GET /tests/{id}` reads the result.

## Ad pages (one landing page per ad, three versions, split tested)

The same feature as the dashboard's Ad pages tab: a page built for one ad on the store's OWN product page (a short `?lr=` link the ad points at), in the layout that works for that kind of ad (listicle for audience / problem ads, offer-first for offer ads), written from the ad's words, the store's real product, photos and reviews, and the store's own facts only (no invented offers or numbers). Three versions are split tested from real visits; Luria crowns a winner and writes a challenger each round unless the owner pins one.

- `GET /sites/{id}/ads`: the connected Meta ad account's ads with `numbers` (spend, clicks, purchases, revenue) and each ad's `page` if one exists. Not connected: `connected: false` plus `needs_access` with the dashboard link where the owner presses Connect Meta. `POST /sites/{id}/ads/sync` re-reads Meta (once every 5 minutes; 404 `not_connected` without a connection).
- `GET /sites/{id}/pages`: every page with `visitors`, `clicks`, `conversions`, `revenue`, `judged_on`, `round`, `winner`, `hold`, `link` (the one to put in the ad; Meta fills `meta_params` per ad), `mode` (onsite on the store's own page, hosted when the tag is not live), `arms[]` (per version: `key`, `label`, `angle`, `why`, `share` of traffic, `sessions`, `clicks`, `click_rate`, `conversions`, `buy_rate`, `preview` link), `meta` (the Meta ad it was made from, `in_meta`, `can_swap`) and `free_tests` (the site's allowance: each page uses one free split test).
- `POST /sites/{id}/pages`: make and build a page (201; 30 to 90 s). From a connected Meta ad: `{"ad_id": "<id from /ads>"}`. From any ad's words: `{"name": "Spring ad", "ad": {"headline": "...", "primary_text": "...", "description": "...", "link": "https://store/products/x", "cta": "Shop now"}, "audience": "who it targets", "product_url": "..."}` (`product_url` picks the product on a store with several; `offer_line` adds the one offer the store really makes; `build: false` makes the row only). Answers `page` with `versions[]` (`letter` a / b / c, `angle`, `why`, `layout`, `headline`, `subhead`, `eyebrow`, `bullets`, `cta`, `quote`, `sections[]`, `offer`, `final`, `preview`). 402 `out_of_credits` / plan needed when the site's free split tests are used up (`needs_access` says where the owner picks a plan). 502 when the writer could not produce a page that passes the store's truth checks (the row exists; `.../rebuild` tries again).
- `GET /sites/{id}/pages/{page}`: one page, numbers and words.
- `POST /sites/{id}/pages/{page}/{action}`: `choose {"version": "a|b|c", "hold": true}` pins a version (hold = stop testing challengers against it; the pick is recorded as that round's decision so the page keeps learning), `edit {"version": "b", "request": "say the 30-day return policy in the headline"}` changes that version in your words under the same truth checks (30 an hour per store), `improve` lets Luria test challengers again, `rebuild` writes three fresh versions, `pause` / `resume` / `archive` (after `choose`, `pause` or `archive`, every shopper sees the change within 5 minutes), `send-to-meta` points the Meta ad at the page (a new creative with the link + tracking; Meta can take up to a minute; pages made from ad words answer 404), `undo-meta` puts the ad's original link back (202 `queued` when Meta is busy; done within the hour).

## Status codes

`200` OK. `201` created (a new account, a new site, a test, a webhook). `202` accepted (`POST /tests {"auto": true}`: Luria is writing the test; poll `GET /tests`). `400` a field is missing or wrong (`hint` says what to send). `401` key missing, wrong or revoked. `402` out of credits (`needs_access` holds the payment link flow). `403` this key may not do that (store owner only, an owner-chosen setting, a read-only or one-site key past its limits). `404` unknown site, test or webhook for this key. `405` the path does not take that method. `409` clashes with what exists (an email that has an account, a store another account owns, a test that cannot start or stop, an Idempotency-Key whose first request is still running: retry in a moment). `422` an Idempotency-Key reused for a different request. `429` too many requests (`Retry-After` seconds). `502` a model Luria calls did not answer. `503` not switched on yet / not healthy. `/openapi.json` declares the exact set per operation, and a test fails when a handler answers a status it does not list.

Error `code`s (stable snake_case; a code is never renamed, new ones are only added): `invalid_request` (400, the default), `missing_field`, `invalid_url`, `invalid_goal`, `invalid_platform`, `invalid_events`, `unknown_version`, `invalid_model`, `key_needs_scope`, `practice_unsupported` (400); `invalid_api_key` (401); `out_of_credits` (402); `forbidden`, `owner_only` (the store's owner only), `operator_only`, `owner_choice` (the owner set this themselves), `key_read_only` (a read-only key tried a write), `key_restricted` (a limited key tried an account-wide call), `practice_unsupported` (a practice key tried what practice mode cannot do) (403); `not_found`, `site_not_found`, `test_not_found`, `webhook_not_found`, `delivery_not_found`, `unknown_endpoint`, `unknown_action`, `not_connected`, `key_not_found` (404); `method_not_allowed` (405); `conflict`, `account_exists`, `store_exists`, `invalid_test_state`, `key_limit`, `idempotency_key_busy` (409); `unprocessable`, `idempotency_key_reused` (422); `rate_limited` (429); `internal_error` (500); `upstream_error` (502); `unavailable`, `payments_unavailable` (503). Any other 4xx/5xx still carries the code of its status.

## Limited keys (one site, read only)

A key made in the dashboard (Settings > API key) has full access to its account. A key can instead be limited to one site and/or to reading:

- `read_only: true`: GET calls only. Any POST, PATCH, PUT or DELETE answers 403 `key_read_only`. Good for a reporting dashboard or a BI tool.
- `site: "<site id>"`: the key reaches that one site and nothing else: another site's id answers 404 `site_not_found`, `GET /me` lists only that site, and what is account-wide answers 403 `key_restricted` (webhooks, keys, adding or erasing a site, `dashboard-link`, buying credits). Good for an agency tool or an agent that owns one store.

The owner picks the limits when making a key in the dashboard. An unrestricted key can also make limited ones for its sub-agents: `POST /keys {"label": "reporting", "read_only": true, "site": "SITE_ID"}` returns the new `key` once, with its `scope` (a key made over the API is always limited, so a leaked key cannot copy itself into a full one). `GET /keys` lists keys with their scope (never the secrets), `DELETE /keys/{id}` revokes the calling key or one it made (the keys it made go with it). `GET /me` shows `key: {id, label, site, read_only, test}` for the key you called with. Existing keys are unchanged: full access. A limited key works on `/api/v1` only; the MCP server and the other key routes refuse it.

## Practice mode (lk_test_ keys)

A key that starts `lk_test_` is a practice key. An unrestricted key makes one: `POST /keys {"test": true, "label": "ci"}` (the dashboard's key form can too). It works on the same endpoints, but in a separate practice world:

- `POST /sites` makes a site marked `"sandbox": true`. The same address as your real store is fine: the practice site is a different site. It has no dashboard page (`dashboard: null`), `verify` answers `installed: true` without looking at any page, and it never appears to your live keys or in the dashboard (and the practice key never sees your live sites).
- Tests, versions, `pause` / `resume` / `stop` / `promote`, conversions and webhooks all work and are stored, so you can build and test an integration end to end. Webhooks made with a practice key receive only practice events, and live webhooks never receive any.
- Nothing is served: a practice site's tag changes no visitor's page (the snippet and `/api/patches` do not know the site). No visitor reaches it, so results stay at zero, and nothing counts toward credits, billing, the brand brain or Luria's learning; no email is sent for it.
- Not available (403 `practice_unsupported`): `/personalize`, the brand brain, connecting a platform, buying credits, the dashboard link, `/models`, `/keys`. `auto: true` tests and `auto_tests` answer 400 `practice_unsupported`.
- `GET /me` shows `key.test: true`. `DELETE /sites/{id}` erases a practice site; deleting your account erases its practice world.

## Client libraries (TypeScript, Python)

Two small clients, generated from `/openapi.json` so they never drift from it, no dependencies, public (no key to download):

- TypeScript / JavaScript: `https://www.luriart.com/api/v1/sdk/luria.ts` (save it into your project; Node 22+, Bun, Deno, browsers and Workers run it; plain `.js` projects can strip the types).
- Python 3: `https://www.luriart.com/api/v1/sdk/luria.py` (standard library only).

```
import { Luria, LuriaError, verifyWebhook } from "./luria.ts";
const luria = new Luria({ apiKey: process.env.LURIA_KEY });          // lk_test_... for practice mode
const { test } = await luria.createTest({ site: "SITE_ID", page: "/", selector: "h1", variants: [{ name: "B", text: "..." }] }, { idempotencyKey: "order-1042" });
const results = await luria.getAttribution("SITE_ID", { model: "linear" });
// luria.lastRateLimit = { limit, remaining, reset }; a failed call throws LuriaError { status, code, hint, retryAfter }
```

```
from luria import Luria, LuriaError, verify_webhook
luria = Luria(api_key=os.environ["LURIA_KEY"])
luria.create_test(site="SITE_ID", page="/", selector="h1", variants=[{"name": "B", "text": "..."}], idempotency_key="order-1042")
```

One method per operation in `/openapi.json` (the method name is its `operationId`: `createTest`, `getTest`, `actOnTest`, `recordConversion`, `getAttribution`, ... / `create_test`, `act_on_test`, ...). `verifyWebhook(secret, rawBody, signatureHeader)` / `verify_webhook(...)` check a webhook delivery's `Luria-Signature` (pass the raw body; a timestamp older than 5 minutes is refused). `node scripts/gen-sdk.mjs <dir>` writes the same files for publishing a package.

## Safe retries and paging

- Send `Idempotency-Key: <any unique string>` on `POST /tests` (including `{"auto": true}`) and `POST /conversions`; a retry with the same key and the same request from the same API key replays the first answer (`"replayed": true`) for 24 hours, so a timeout never makes a second test, a second 200-credit charge or a double conversion. The key is claimed before the work starts: the same key on a different request (other path or body) answers 422, and a retry that arrives while the first is still running answers 409 with `Retry-After` (send it again in a moment and you get the first answer). An error answer does not use the key up: fix the request and send it again with the same key. Without a key, two `auto: true` calls that arrive together still charge once (the second answers that a test is already being written). Browsers may send the header cross-origin (CORS allows it).
- `GET /tests?site={id}&limit=20` is newest first; when more exist the answer carries `next_before`, pass it as `&before=` for the next page.
- `GET /health` (no key): `{"ok": true}` with 200 when Luria is up (database reads, every background job ran on time), 503 otherwise. Check it before a long run.
- `GET /openapi.json` (no key): this API as OpenAPI 3.1, including the webhook payloads, for SDK generators and tool loaders.

## Platforms

- Any HTML site, Next.js, React, Vue, Webflow, WordPress, Wix, Squarespace, Framer, Kajabi, ClickFunnels, BigCommerce: the tag. `install.builders` says where to paste it in each builder.
- Shopify: the tag in layout/theme.liquid before `</head>`, plus `install.shopify_pixel` pasted as a custom pixel (Settings > Customer events > Add custom pixel, Save, Connect) so every order counts with its value. No app and no store login.
- Every site, Cloudflare-hosted ones included, installs with the tag above: there is no separate Cloudflare connect step.
- GoHighLevel: the tag in every funnel and website: Settings > Head tracking code, after anything already there, Save. Bookings from GoHighLevel calendars count on their own. Connecting GoHighLevel in the dashboard is optional (it adds CRM outcomes such as won deals).
- Single-page apps: add `data-luria-spa` to the tag so route changes count as page views.

## Credits

- 1 credit = 1 visitor on 1 day who saw a running test (any version, the original included).
- A test Luria writes itself (`auto: true`): 200 credits.
- $10 per 1,000 credits. New accounts start with 1,000 free.
- `GET /credits`: balance, prices, the latest charges. `POST /credits/checkout {"amount_usd": 50}` returns a Stripe link for the owner to pay.
- At 0 credits, running tests pause (every shopper sees the original page within 5 minutes), measuring continues, and `POST /tests` answers 402 until a top-up.

## All endpoints

- `GET /` this list as JSON
- `POST /signup {email, url?, goal?, name?, agent?}` (`agent` = a label stored with the key, like "claude-code")
- `GET /me` credits and every site
- `POST /sites {url, goal?, platform?, convert_paths?, auto_tests?}` add a site (returns `install`). `goal` is one of Sales, Booked calls, Leads / emails, Lead magnet downloads, App downloads; a goal the platform does not take answers 400 with the ones it does.
- `GET /sites/{id}` install state, connections, tests
- `PATCH /sites/{id} {goal?, convert_paths?, auto_tests?, status?}` (`auto_tests: true` = Luria starts its own tests, 200 credits each; `status: "paused"` = kill switch, every test off; it can take up to 5 minutes for every shopper to see the original)
- `POST /sites/{id}/verify`
- `GET|POST /sites/{id}/connect`
- `GET /tests?site={id}` every test with results
- `POST /tests` create (see step 3)
- `GET /tests/{id}`
- `POST /tests/{id}/pause | resume | stop | promote | start` (after pause, stop or promote, every shopper sees the change within 5 minutes; no delete: tests stay in the history; `PATCH /sites/{id} {"status":"paused"}` turns a whole site off). `promote` with a `version` the test does not have answers 400 and changes nothing.
- `DELETE /sites/{id}` erases the site and everything about it: the store's owner only (a team member's key gets 403).
- Limits: 300 calls a minute per key; past it, 429 with `Retry-After` (the key still works after the wait). Every answer to a key carries `X-RateLimit-Limit` (300), `X-RateLimit-Remaining` (calls left in the current minute) and `X-RateLimit-Reset` (unix seconds when the oldest counted call leaves the window and `Remaining` goes up; on a 429 it is the same moment `Retry-After` names). Counted per server instance, so a key spread over many instances can see a slightly higher real limit. Browsers can read these headers cross-origin.
- `POST /conversions`
- `POST /personalize` changes for one visitor
- `GET /sites/{id}/attribution?days=30&model=last|first|linear` sales by source, campaign, device and version seen
- `GET /sites/{id}/ad-fit?days=30&target=20` ad vs landing page: which half is weak per Meta ad, the ad's promises the page never says, URL tag health
- `GET /sites/{id}/brand-brain` who converts most, the ads and posts that sell, what the tests taught, next tests and ads
- `GET /sites/{id}/report?days=30` the site in one read: numbers, tests, heat pages, recording averages, learned facts, weak spots, the plan, what is working and what is not
- `GET /sites/{id}/heatmaps[?page=/&vw=1440&days=7&arm=&test=]` pages with heat, or one page's map with a plain summary
- `GET /sites/{id}/recordings[?device&page&converted&rage&test&arm&limit&before&insights]`, `GET /sites/{id}/recordings/{session}` recorded visits as stories (+ signed playback)
- `GET /sites/{id}/learned` facts, last tests and the averages over every recorded visit
- `GET|POST /sites/{id}/next-tests` what to test next and why; POST `{type?, page?, hold?}` starts a planned big test
- `GET /sites/{id}/ads`, `POST /sites/{id}/ads/sync` the Meta ad account's ads with numbers
- `GET|POST /sites/{id}/pages`, `GET /sites/{id}/pages/{page}`, `POST /sites/{id}/pages/{page}/choose|edit|improve|rebuild|pause|resume|archive|send-to-meta|undo-meta` ad pages (choose, pause and archive reach every shopper within 5 minutes)
- `GET|POST /webhooks`, `DELETE /webhooks/{id}`, `POST /webhooks/{id}/test`, `POST /webhooks/{id}/rotate`, `GET /webhooks/{id}/deliveries`, `POST /webhooks/{id}/deliveries/{delivery}/resend`
- `GET|POST /keys {label?, read_only?, site?, test?}`, `DELETE /keys/{id}` limited and practice keys (see Limited keys, Practice mode); needs an unrestricted key
- `GET /credits`, `POST /credits/checkout {amount_usd}`
- `POST /dashboard-link` emails the owner a sign-in link
- `GET /health` (no key) up or not; `GET /openapi.json` (no key) the machine-readable contract; `GET /sdk/luria.ts` and `GET /sdk/luria.py` (no key) the generated clients

## Rules Luria enforces

- A version changes words and looks only: `style` may set colour, background, type, spacing, borders, radius, shadow; nothing that moves, resizes or hides an element, and no url() values. A change that breaks this is refused with a reason.
- Visitors keep the same version every visit. The original always keeps at least 10% of traffic while a test runs.
- A version is called a winner at 95% chance of beating the original with enough visitors on both sides.
- Rate limits: 600 calls a minute per IP, 300 a minute per key, 5 signups an hour per IP.