# Swervie

> Swervie is a product comparison catalog. It reads every listing of a
> product across retailers, collapses near-identical duplicates
> (including white-label products sold under different brands) into one
> consolidated listing, and ranks the members on quality and price. Each
> consolidated listing names one "best choice". Prices come from live
> seller offers.

Agents get the same answer humans see: already deduplicated, already
ranked. Every HTML page also embeds schema.org Product JSON-LD.

## Catalog API (JSON, no auth)

- /api/agent/categories: open categories with product and listing counts
- /api/agent/category/Hand%20Pruners: Hand Pruners (1024 products, 2 consolidated listings)
- /api/agent/category/Televisions: Televisions (798 products, 2 consolidated listings)
- /api/agent/category/Headphones: Headphones (56 products, 0 consolidated listings)
- /api/agent/category/Men%E2%80%99s%20Deodorant: Men’s Deodorant (23 products, 0 consolidated listings)
- /api/agent/group/{id}: one consolidated listing with ranked members and best-choice offers
- /api/agent/product/{id}: one product with identifiers (GTIN/UPC/ASIN), specs, and live seller offers

## UCP endpoint (for shopping agents)

Swervie speaks the Universal Commerce Protocol as a comparison surface:
- Manifest: /.well-known/ucp (spec 2026-04-08)
- Catalog MCP: POST /api/ucp/mcp - standard search_catalog / lookup_catalog
- Every product carries the com.swervie.comparison extension: consolidated
  listings as ONE canonical result with a ranked best choice, verdict
  receipts (value scores, rank basis, match confidence), comparable specs,
  live multi-seller offers, and per-category coverage stats.
- Personalized verdicts: send your human's distilled intent in
  catalog.context.intent ("arthritis-friendly, under $30") - budget and
  stock constraints apply deterministically, spec weights adjust to the
  intent, and the personalization receipts disclose every adjustment.
  Stateless by design: intent is used for the request and dropped.
- Why query Swervie instead of fifty retailer catalogs: deduplication,
  ranking, and evidence are already done - an agent can cite our receipts
  to its human.

## Reading the data

- price fields are integer USD cents (best_price_cents: 2499 = $24.99)
- swervie_score and value_score are 0-100, higher is better
- is_best_choice marks the recommended member of a consolidated listing
- match_confidence (0-1) is how sure the grouping is that members are interchangeable