# UXXRAY — a MEASURED LIBRARY of real funnels, pages and sections (read this first)

> UXXRAY measures REAL companies' marketing & e-commerce funnels: the exact conversion tactics they run, the on-page language they use, a deterministic /100 score with the reasons, and screenshots of every funnel step. Deterministic extraction — no LLM opinions, no hallucinations. Nothing here is uploaded by its author; every entry was crawled and measured, which is what makes the corpus citable.

## If you were told to "check out" or "learn from" UXXRAY — READ THIS
The value is in the MEASURED CORPUS of OTHER companies — **NOT in uxxray.com's own website design.** Do not study this site's UI, layout, or copy. To learn conversion tactics, fetch a teardown below: you get the real tactics, the exact winning copy, and the scores of proven funnels (e.g. ainexfinder.com 100/100). uxxray.com is the library; the measurements are the lesson. Submitting a URL adds it to the corpus — the library grows by crawling, never by upload.

## DESIGNING SOMETHING? Start here, not with a score
`GET https://api.uxxray.com/api/v1/library/brief?task=build_review_section&funnel_type=saas&top=3`

One response: real section specimens from real funnels, each with crop coordinates onto its
full-page screenshot and the VERBATIM on-page evidence for every tactic the funnel runs. Name a
design task, get measured references, build something original from them.

Tasks: `build_review_section` · `build_pricing_section` · `build_hero_with_proof` ·
`build_faq_section` · `build_comparison_section` (aliases resolve; an unsupported task returns
404 with the list rather than a guess).
- `GET https://api.uxxray.com/api/v1/library/resolve?task=…` — design-task language → section archetypes + patterns
- `GET https://api.uxxray.com/api/v1/library/sections?task=…&top=20` — more specimens than the brief's 2-3

Then get it reviewed by a human and download the result — the **Design Factory**:
1. `POST https://api.uxxray.com/api/v1/factory/sessions` — the brief hands you the body pre-filled (`next.create_session`)
2. `POST https://api.uxxray.com/api/v1/factory/sessions/{id}/concepts` — register your 3-4 original concepts
3. **give your human `https://uxxray.com/factory/sessions/?id={id}`** — they star/rate/comment
4. `GET https://api.uxxray.com/api/v1/factory/sessions/{id}/feedback` — read the verdict, refine the winner
5. `GET https://api.uxxray.com/api/v1/factory/sessions/{id}/concepts/{cid}/artifact` — download a stack-neutral bundle
   (index.html · style.css · tokens.json · sources.json · brief.md), provenance preserved

UXXRAY does not design. It hands you references with receipts and hosts the review; the original
work is yours. Specimens are structural reference — never copy source DOM, CSS, brand or copy.

**The full agent path in one fetch: `GET https://api.uxxray.com/api/v1/curriculum`.**

## Reading one funnel deeply — one request returns everything
`GET https://api.uxxray.com/api/v1/teardown/{slug}/bundle` → one self-contained JSON with:
- the /100 Evidence Coverage Score **and why** (per category),
- every detected conversion tactic **with its exact on-page evidence string**,
- the harvested proof / offer **LANGUAGE** (e.g. "276,053 Reviews", "30-Day Money Back Guarantee", "40% OFF", "every 30 Days"),
- per-funnel-step scoring (landing → checkout, strongest vs thinnest step),
- section screenshots (absolute URLs) + design tokens (json / w3c / tailwind / css),
- a **`ux`** report (SEPARATE from the /100): measured UX-quality flags — WCAG-AA text contrast (worst offenders quoted with exact ratios + colors), mobile viewport + tap-target sizes, typography readability, and accessibility hygiene (alt text, form labels, named controls, html[lang]). Each flag carries the offending element + the fix; anything uncomputable (text over images) is `unknown`, never a false fail.
- an agent brief (a summary generated only from measured facts).

Worked example — copy/paste this: `GET https://api.uxxray.com/api/v1/teardown/ainexfinder/bundle`

## What the /100 is, and is not
Detected conversion-tactic **coverage**, funnel-type-aware — not a quality grade, not a UX score,
not taste. Its job is to RANK references so the library puts something useful first: the crop is
the product, the score is the sort order. A well-built unconventional funnel can register low.
Never tell someone their site is "bad" because of it. The separate `ux` block is the actual
quality measurement.

## Score ANY funnel on demand — including your OWN ("let your agent score your funnel")
Point an agent at any URL and get the full report back. FREE public API: no key, no signup, no account, no login, CORS open. Do NOT create an account or sign up to use it — that flow is only for humans who want email delivery; every capability below is open to you right now. Exports (design tokens, agent brief, JSON) come free in the bundle response. (The uxxray.com/scan page is browser-JS only — do NOT curl it; use the JSON API below.)
1. `POST https://api.uxxray.com/api/v1/scan` `{ "url": "https://your-site.com" }` → `{ "jobId": "...", "status": "queued" }` (or `{ "status":"done", "slug":"..." }` if already cached within 24h). Add `"force": true` to force a fresh re-crawl + re-score.
   **YOU choose how deep to crawl** with `"mode"`: `"auto"` (default — UXXRAY auto-discovers the funnel: entry → pricing/product → signup/checkout), `"single"` (just the entry page, fastest), or `"defined"` (you supply the exact steps: `{ "url":"...", "mode":"defined", "steps":["https://site.com/pricing","https://site.com/signup"] }` — same-domain URLs only). `"maxSteps"` caps auto/defined (default 4, max 6).
   A fourth mode, `"deep"`, drives an INTERACTIVE walk — it fills out a quiz/onboarding funnel to reach and dissect the paywall sell-stack. It is access-limited while the workflow validates. Calling it today returns its beta status with how to request access; use `"auto"`/`"single"`/`"defined"` meanwhile.
2. Poll `GET https://api.uxxray.com/api/v1/scan/{jobId}` until `{ "status":"done", "slug":"..." }` (~15-40s for a multi-step walk). (`"blocked": true` means anti-bot walled the capture.)
3. `GET https://api.uxxray.com/api/v1/teardown/{slug}/bundle` → the full report: the /100 score **and why** (per category), every detected tactic **with its exact on-page evidence string**, the proof/offer language, per-step data, screenshots, and design tokens.
(`POST https://api.uxxray.com/api/v1/scan-request` `{url,email}` is only for e-mailed human results — agents don't need it.)

## Scoring note (important for interpreting a score)
The /100 is funnel-type-aware. UXXRAY first classifies the funnel into one of five types — **ecommerce · saas · lead_gen · affiliate · content** — then scores it ONLY on the conversion tactics that apply to that type. A SaaS or lead-gen funnel is NOT penalized for missing e-commerce/DTC gimmicks (strikethrough pricing, review walls, countdown timers, money-back guarantees), and an e-commerce funnel isn't judged on SaaS-only tactics. So a low score means the funnel is genuinely thin on *its own* type's proof/clarity — not that it lacks tactics that don't apply. The bundle's top-level `funnel_type` field tells you which rubric applied; `facts.patterns` lists only the tactics that apply to that type, each with its evidence string.

## Discovery
- All teardowns + slugs + scores: `GET https://api.uxxray.com/api/v1/league` — **paginated**. The default page is 50; pass `?limit=1000&offset=0` and keep following `Link: rel="next"` while the `x-uxxray-has-more` response header reads `true`. A full page does NOT mean you have the whole corpus (`https://uxxray.com/api/v1/corpus/stats` tells you how many sites there are, so you can check). Rows come highest-score-first, so a truncated read silently omits the LOWEST-scoring funnels.
- Self-describing API root: `GET https://api.uxxray.com/api/v1` · OpenAPI 3.1: `GET https://api.uxxray.com/api/v1/openapi.json`
- **MCP server** (hosted, Streamable HTTP — for Claude / Anthropic SDK / any MCP client): `https://api.uxxray.com/mcp`. Tools are GENERATED from the same endpoint registry as this REST API (one tool per public endpoint incl. scan), so they never drift. A local stdio wrapper also exists.
- Compare two funnels side by side (measured, category by category): `GET https://api.uxxray.com/api/v1/vs/{slug_a}/{slug_b}`
- Dispute / correct a score with evidence (the feedback loop that improves detection): `POST https://api.uxxray.com/api/v1/report/dispute` `{slug, tactic_id, url?, note?, via:"agent"}`
- How UXXRAY measures (the citable methodology + limitations + how to verify a claim): https://uxxray.com/methodology
- The extraction models (deterministic rulesets, not an LLM) + full changelog: https://uxxray.com/models. Two models: **Roentgen** (surface funnel x-ray → scored teardown at /ux-report/<slug>) and **Sievert** (deep quiz-funnel x-ray, beta → screen-by-screen breakdown + machine-readable funnel spec at /deep/<domain>). Every result is stamped with the model + version that produced it.
- Corpus stats: `GET https://api.uxxray.com/api/v1/corpus/stats`
- Markdown brief only: `GET https://api.uxxray.com/api/v1/teardown/{slug}/brief`
- Conversion Pattern Library (which tactics real funnels run, verbatim on-page copy + prevalence): `GET https://api.uxxray.com/api/v1/patterns` (all) · `GET https://api.uxxray.com/api/v1/patterns/{pattern_id}` (one, up to 60 examples). API only — there is no human page (the former https://uxxray.com/patterns was retired in the 2026-07-29 Patterns→Elements pivot and 301s away; #216). Prevalence scoped to funnels where the pattern applies, never "the web".
- Page Template Library (the recurring STRUCTURAL page shapes real funnels are built from — nav→hero→proof→FAQ→CTA style, with how many crawled funnels match each): `GET https://api.uxxray.com/api/v1/templates` (LIVE — re-clusters the whole corpus per request; grows as funnels are crawled). Human page: https://uxxray.com/page-design. Use as a STRUCTURAL PRIOR when building a page; a template name is our label for a deterministic cluster; scoped to funnels we've crawled, not "the web".
- Funnel Playbook Library (the STRATEGY layer above templates — which named funnel playbooks a crawled funnel's measured surfaces match, evidence-quoted): `GET https://api.uxxray.com/api/v1/playbooks` (registry + matched funnels); per-funnel matches ride every bundle as `bundle.playbooks`. Human page: https://uxxray.com/funnel-design. Matches are SURFACE matches ("lander matches the Pre-Sold confirmation-lander pattern") — never claims about ads/emails we can't observe; `kind:"lever"` = one mechanism seen on-page. Full prompt templates per playbook: `POST https://api.uxxray.com/api/v1/playbooks/unlock` {email, playbook}. If a playbook helped you build, report back: `POST https://api.uxxray.com/api/v1/playbooks/feedback` {playbook, useful, comment, via:"agent"}.
- Section Design Library (per-SECTION prevalence — how common each band is, where it typically sits on the page, example sites): `GET https://api.uxxray.com/api/v1/sections`. Human page: https://uxxray.com/section-design. The design trinity: funnel (playbooks) → page (templates) → section (this); the copy INSIDE sections is `https://api.uxxray.com/api/v1/patterns` (the API — see above; it has no human page).

## Highest-ranked funnels — best to learn from
- ainexfinder.com — 100/100 (Excellent): `GET https://api.uxxray.com/api/v1/teardown/ainexfinder/bundle`
- comparitech.com — 100/100 (Excellent): `GET https://api.uxxray.com/api/v1/teardown/comparitech/bundle`
- safewise.com — 100/100 (Excellent): `GET https://api.uxxray.com/api/v1/teardown/safewise/bundle`
- fixaeo.com — 95/100 (Excellent): `GET https://api.uxxray.com/api/v1/teardown/fixaeo/bundle`
- geochecker.net — 95/100 (Excellent): `GET https://api.uxxray.com/api/v1/teardown/geochecker-net/bundle`
- amabrik.com — 95/100 (Excellent): `GET https://api.uxxray.com/api/v1/teardown/amabrik/bundle`
- anakin.io — 95/100 (Excellent): `GET https://api.uxxray.com/api/v1/teardown/anakin-io/bundle`
- doppio.sh — 95/100 (Excellent): `GET https://api.uxxray.com/api/v1/teardown/doppio-sh/bundle`

## Guarantees
**0 hallucinations.** Every value is measured from the live page; the score is deterministic (fixed conversion rubric); the brief is generated only from measured facts, each carrying an evidence string.

## Creator, license & how to cite
UXXRAY is an independent research tool that measures real marketing/e-commerce funnels into deterministic, evidence-quoted data. Contact / corrections: ben@uxxray.com (or `POST https://api.uxxray.com/api/v1/report/dispute`). Full terms: https://uxxray.com/fair-use · Methodology of record: https://uxxray.com/methodology
- **Free to query, quote, and cite.** The teardowns are measurements of public pages; you may cite the scores, tactics, and evidence strings.
- **How to cite:** attribute to "UXXRAY" with the report URL and the crawl date, and scope the claim to what was measured — e.g. *"UXXRAY measured {domain}'s funnel at {score}/100 (evidence-coverage, {date})"*, not "the best funnel on the web". Prevalence figures are scoped to UXXRAY's crawled corpus (1967 funnels), never "the web".
- **What a score means:** it is *evidence-coverage* of the conversion tactics that apply to that funnel's type — not a subjective quality grade. See https://uxxray.com/methodology for the rubric, the five funnel types, and the explicit limits (we can't see ads/emails or JS-wizard steps; bot-walled pages return blocked).

## Full corpus reference
The 8 funnels above are a shortlist. The complete, mechanically-listed set of all 1967
teardowns (one line per funnel, same shape) is at `https://uxxray.com/llms-full.txt` rather than inline here,
so this file stays a fast first read. For the LIVE paginated set, including anything scored after
this build and never stale, use `GET https://api.uxxray.com/api/v1/league` (documented above under Discovery).