# Luria: split testing API 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: 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.
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.
- Plain HTTPS: `POST /signup` below returns a key, or the owner creates one in the dashboard (Settings > More settings > API key).

## 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 Shopify or GoHighLevel one-click connects (the owner clicks in the dashboard; the tag alone already runs tests).

## 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"}'
```
Also `/pause`, `/resume`, `/stop` (back to the original; 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.

## 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>`; orders through POST /conversions from your orders/paid webhook. (The full Shopify app is set up by Luria's team: hello@luriart.com.)
- Cloudflare-hosted sites: `GET /sites/{id}/connect` lists the inputs, `POST /sites/{id}/connect {"platform":"cloudflare","inputs":{...}}` serves tests from the edge with no flicker.
- GoHighLevel: the owner connects it in the dashboard (Connections).
- 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 (shoppers see the original page), 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 within seconds)
- `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` (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}/brand-brain` who converts most, the ads and posts that sell, what the tests taught, next tests and ads
- `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.