{
  "name": "Espresso Steals public API",
  "version": "v1",
  "description": "Free, read-only espresso-gear price intelligence: current prices, 2+ years of daily price history, and computed BUY calls checked against each product's own history. Every response carries provenance (observed_at, source, method).",
  "endpoints": {
    "GET /api/v1/deals": "Today's verified deals (genuine lows only). Default order is category-balanced (machines, grinders, accessories, brewers interleaved; not prefix-stable across limits). Params: ?limit=1..50 (default 10), ?order=score for best-scored first.",
    "GET /api/v1/verdict/{asin|slug}": "Is today's price good? Current price, typical price, all-time low, a BUY call (or no call) with numeric evidence.",
    "GET /api/v1/history/{asin|slug}": "Full daily price series for one product (ascending dates).",
    "GET /api/v1/builds": "Complete espresso setups we publish — today's best-value build (slug deal-of-the-day), our picks under $300/$500/$1,000/$2,000, creator builds — each with the question it answers, a one-sentence answer with live totals, and compatibility. Params: ?limit=1..50 (default 20).",
    "GET /api/v1/builds/{slug}": "One build in full: every item with price, reference, verdict and buy link; live totals; portafilter compatibility warnings; provenance.",
    "GET /api/v1/track-record": "Our graded accuracy: every published BUY scored against what the price actually did at 30/60/90 days, next to the always-buy baseline on the same rows, misses and weak products included. Check this before trusting /verdict."
  },
  "mcp": {
    "url": "https://espressosteals.com/api/mcp",
    "transport": "streamable-http (stateless, JSON responses, no auth)",
    "tools": [
      "list_slots",
      "search_catalog",
      "get_product"
    ],
    "description": "The same catalog as tools for an MCP client: search tracked gear by slot/words/price/brand/on-sale, get one product's sentiment, sizing, verdict and links. Claude Code: `claude mcp add --transport http espresso https://espressosteals.com/api/mcp`."
  },
  "examples": [
    "https://espressosteals.com/api/v1/deals?limit=5",
    "https://espressosteals.com/api/v1/verdict/B07JVD78TT",
    "https://espressosteals.com/api/v1/history/breville-bambino-plus",
    "https://espressosteals.com/api/v1/builds/deal-of-the-day",
    "https://espressosteals.com/api/v1/builds/best-under-500"
  ],
  "conventions": {
    "identifiers": "Products are addressable by Amazon ASIN or by our URL slug — both work in every {key} position.",
    "provenance": "observed_at = date of newest price observation; last_confirmed_at = when our ingest last verified the live price; stale=true means treat the verdict as unreliable and check the live price.",
    "verdicts": "'buy' = at/near a genuine historical low; the only call we make. 'no_call' = not at a low; we make no prediction about where it goes next, and verdict.stats carries the measured history (drops per year, typical dip). 'stale' = check the live price. 'not_tracked' = Amazon retired or replaced the listing and we stopped polling it; price.current is the last price we confirmed (dated by provenance.observed_at), not today's. Computed from the product's own history — never from list prices."
  },
  "terms": "Free for any use with attribution ('price data: espressosteals.com'). No key required. Rate limit: be reasonable; cache 15 minutes. Contact: deals@espressosteals.com",
  "site": "https://espressosteals.com"
}