# nested

> nested (https://nested.deals) is a US shopping search. Describe a product, paste a product link, or drop a photo, and it returns live listings from thousands of stores side by side, plus cheaper dupes and lookalikes. It compares and links out; it never checks out or buys.

Last reviewed: 2026-09-27
Full reference with example responses: https://nested.deals/llms-full.txt
Human-readable explainer: https://nested.deals/how-it-works

Powered by: Shopify Global Catalog via UCP (Universal Commerce Protocol) for live listings and similarity; Google Shopping via an Apify actor for big-box coverage; OpenRouter models for dupe-query rewriting; Parallel (Search + Task APIs) and Exa (Search + Contents) for legacy deep hunts.

## Fast path for agents

All routes are GET, keyless, return JSON, and send `Cache-Control: no-store`.

1. `GET /api/live-search?q=<text>[&max=<whole USD>]` — instant results (~0.5 s) from the Shopify Global Catalog.
2. Pick a result and keep its `id` (`gid://shopify/p/...`).
3. `GET /api/similar?id=<gid>&mode=cheaper` — cheaper lookalikes; `mode=similar` — same style at any price.
4. Send the shopper to `https://nested.deals/find?q=<text>[&max=<USD>]` for the visual grid, or to the result's `url` (the store's own page).

Other routes:

- `GET /api/live-search?q=<text>&source=google` — the slower big-store wave (~4 s, metered; 12 per hour per visitor). Links in this wave open Google Shopping's product page (`via: "google_shopping"`).
- `GET /api/link-preview?url=<https product page>` — reads one public product page (JSON-LD / Open Graph) and returns `item` {title, url, host, imageUrl, priceCents, currency, brand, siteName} plus a suggested `query`.
- `GET /api/discover?dept=home|style|beauty|tech|outdoors|pets[&child=<id>][&seed=<0..>]` — the homepage discovery wall as `tiles`.

## Result fields (live-search, similar, discover)

- `results[]` (discover: `tiles[]`): `id`, `title`, `merchant`, `merchantDomain`, `url`, `imageUrl`, `priceCents` (integer cents), `currency`, `rating`, `ratingCount`, `available`, `condition`, optional `via`.
- `plan.kind`: `direct` or `dupe`. Queries containing "dupe", "alternative", "similar to", "cheaper than", etc. become dupe searches: `original[]` holds the named product, `originalPriceCents` its median price, and `results[]` only brand-free items priced at least ~10% below it.
- `max` (1 to 100000 whole dollars) wins over any "under $X" in the text. Upstream filters match any variant, so results are re-filtered to the shown price.
- `totalCount` is the catalog's match count, not the number returned.

## Limits and errors

- Rate limits are per visitor: 20/min for live-search, similar and link-preview; 15/min for discover; 12/hour for `source=google`. Exceeding returns 429 `{ "error": "..." }`.
- 400 = bad input, 404 = big-store wave switched off, 502/503 = upstream catalog busy or down. Back off; do not retry in a tight loop.
- Errors are always `{ "error": "<human sentence>" }`.

## WebMCP (in-browser agents)

Every page registers WebMCP tools via `document.modelContext.registerTool` when the browser supports it (W3C WebML CG draft; Chrome early preview):

- `search_products` {query, max_price_usd?, limit?} — Answer (read-only).
- `find_cheaper` {product_id, limit?} — Answer (read-only).
- `find_similar` {product_id, limit?} — Answer (read-only).
- `open_results` {query, max_price_usd?} — Action: navigates the tab to /find. Reversible; buys nothing.

## Rules

- Results are live and must not be cached, stored, or republished as a dataset (catalog terms). Fetch again instead.
- Images are hot-linked from the merchant's CDN; don't re-host them.
- Stores are the source of truth for price, stock, variants, shipping, tax and returns. Say "listed at", not "guaranteed", and link to the store.
- Don't present nested as the seller, and don't claim nested found the "lowest price anywhere".
- `/api/` is disallowed for crawlers in robots.txt. Call it on behalf of a shopper, at human pace; don't bulk-crawl.
- Don't automate sign-in, CAPTCHA, or Turnstile. Account features (saves, price alerts) are for people.

## Legacy deep hunts (read-only)

Older, sign-in-only "deep hunts" used Parallel and Exa to research retailer pages. Their public results stay readable:

- `GET /api/browse[?cursor=]` — public hunts; `GET /api/search/<uuid>` — one hunt's structured state; `https://nested.deals/s/<uuid>` — shareable page.
- Hunt offers carry `evidence_tier` (`verified_retailer` = price-checked on the retailer page; `provisional_web` = web evidence only) and `match_tier` (`exact` or `unknown`). Never present provisional evidence as verified.
- `POST /api/search` requires a real signed-in session and is not an agent API.