{"openapi":"3.1.0","servers":[{"url":"https://api.crushrewards.dev"}],"info":{"title":"Crush Rewards — Pricing Intelligence API","version":"1.0.0","description":"Real-time competitive pricing data across US and Canadian e-commerce retailers (Amazon, Walmart, Best Buy, Target, etc.). Serves price comparisons, deal alerts, brand tracking, promotional intelligence, and market analytics to AI agents via x402 and MPP micropayments.","x-guidance":"This API has three endpoint groups organized by use case:\n\n**Shopper endpoints** ($0.01/query): Use these for price comparisons and deal hunting. Start with /v1/shopper/best-price?q=<product> to find the cheapest option across retailers. Use /v1/shopper/deal-finder?category=<category> to find discounted products. Use /v1/shopper/price-drop-alert?q=<product> to check for recent price drops.\n\n**Marketing endpoints** ($0.01/query): Use these for competitive analysis. /v1/marketing/competitive-landscape?category=<category> shows all products in a category with pricing. /v1/marketing/brand-tracker?brand=<brand> tracks a brand's pricing over time. /v1/marketing/share-of-shelf?category=<category> shows brand market share.\n\n**Analyst endpoints** ($0.02/query): Use these for market-level insights. /v1/analyst/inflation?category=<category> shows price trends over time. /v1/analyst/price-dispersion?category=<category> shows price spread across retailers.\n\nAll endpoints accept an optional 'country' parameter (us or ca, defaults to us). Query parameters use 'q' for free-text search and 'category' for category-level queries."},"x-faremeter-assets":{"solana-usdc":{"chain":"solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp","token":"EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v","decimals":6,"recipient":"2hYY7wHhXsoWnskQRzYFUNH7YboXNMEqbGnAFHpRuB2W"},"base-usdc":{"chain":"eip155:8453","token":"0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913","decimals":6,"recipient":"0xe2e662cF219025AFC0C9Bf850b6a2B0a0b5517fe"},"tempo-usdc":{"chain":"tempo","token":"0x20c000000000000000000000b9537d11c60e8b50","decimals":6,"recipient":"0xe2e662cF219025AFC0C9Bf850b6a2B0a0b5517fe"}},"paths":{"/v1/shopper/best-price":{"get":{"operationId":"getBestPrice","summary":"Find the best price for a product across retailers","description":"Find the lowest current price for a product across Amazon, Walmart, Costco, Home Depot, Nordstrom, and IKEA in US and Canada. Returns the cheapest option plus other retailer prices for comparison.","tags":["Shopper"],"x-faremeter-pricing":{"rates":{"solana-usdc":"10000","base-usdc":"10000","tempo-usdc":"10000"},"rules":[{"match":"$","capture":"1"}]},"x-payment-info":{"amount":"10000","currency":"0x20c000000000000000000000b9537d11c60e8b50","description":"Shopper pricing query - $0.01 per request","intent":"charge","method":"tempo","methods":[{"method":"tempo","intent":"charge","currency":"0x20c000000000000000000000b9537d11c60e8b50","decimals":6,"amount":"10000","settlement":"Tempo Allegro USDC.e","role":"primary"}],"price":{"mode":"fixed","currency":"USD","amount":"0.010000"},"protocols":[{"x402":{}},{"mpp":{"method":"tempo","intent":"charge","currency":"USDC","amount":"10000","recipient":"0xe2e662cF219025AFC0C9Bf850b6a2B0a0b5517fe"}}]},"x-sla":{"p50_ms":80,"p99_ms":250,"freshness_seconds_max":300,"idempotency":"safe","cache_hint":"public"},"x-retry-policy":{"min_backoff_seconds":1,"max_backoff_seconds":30,"max_attempts":5,"jitter_required":true,"idempotency_safe":true},"parameters":[{"name":"q","in":"query","required":true,"schema":{"type":"string","minLength":1},"description":"Search query (product name, keyword, or category term)","example":"airpods"},{"name":"country","in":"query","required":false,"schema":{"type":"string","enum":["us","ca"],"default":"us"},"description":"Country (us or ca)","example":"us"},{"name":"retailer","in":"query","required":false,"schema":{"type":"string","enum":["amazon","walmart","costco","homedepot","nordstrom","ikea"]},"description":"Filter to a specific retailer","example":"amazon"},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","default":10,"maximum":50},"description":"Max results to return (default 10, max 50)","example":10}],"responses":{"200":{"description":"Best price result","content":{"application/json":{"schema":{"type":"object","properties":{"query":{"type":"string"},"country":{"type":"string"},"currency":{"type":"string"},"best_price":{"type":"object","properties":{"product_name":{"type":"string"},"retailer":{"type":"string"},"price":{"type":"number"},"list_price":{"type":"number","nullable":true},"savings_pct":{"type":"number","nullable":true},"in_stock":{"type":"boolean"},"condition":{"type":"string","enum":["new","refurbished","used","unknown"],"description":"Derived from product name + retailer URL signals (e.g. Walmart 'Restored', Amazon Renewed). Defaults to 'new' when no condition signal is present."},"scraped_at":{"type":"string","format":"date-time"}}},"other_prices":{"type":"array","items":{"type":"object","properties":{"retailer":{"type":"string"},"price":{"type":"number"},"in_stock":{"type":"boolean"},"condition":{"type":"string","enum":["new","refurbished","used","unknown"]}}}}}}}}},"402":{"description":"Payment Required"}},"x-input-schema":{"type":"object","additionalProperties":false,"required":["q"],"properties":{"q":{"type":"string","minLength":1,"description":"Search query (product name, keyword, or category term)","example":"airpods"},"country":{"type":"string","enum":["us","ca"],"default":"us","description":"Country (us or ca)","example":"us"},"retailer":{"type":"string","enum":["amazon","walmart","costco","homedepot","nordstrom","ikea"],"description":"Filter to a specific retailer","example":"amazon"},"limit":{"type":"integer","default":10,"maximum":50,"description":"Max results to return (default 10, max 50)","example":10}}},"requestBody":{"required":false,"description":"Query parameters as JSON (alternative to URL query string for agents that prefer body-based invocation).","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["q"],"properties":{"q":{"type":"string","minLength":1,"description":"Search query (product name, keyword, or category term)","example":"airpods"},"country":{"type":"string","enum":["us","ca"],"default":"us","description":"Country (us or ca)","example":"us"},"retailer":{"type":"string","enum":["amazon","walmart","costco","homedepot","nordstrom","ikea"],"description":"Filter to a specific retailer","example":"amazon"},"limit":{"type":"integer","default":10,"maximum":50,"description":"Max results to return (default 10, max 50)","example":10}}}}}}}},"/v1/shopper/price-history":{"get":{"operationId":"getPriceHistory","summary":"Get price history for a product over time","description":"Get historical price observations for a product within a date range. Returns current price, period low/high/avg, trend (rising/falling/stable), good-deal flag, and an observation time-series for charting.","tags":["Shopper"],"x-faremeter-pricing":{"rates":{"solana-usdc":"10000","base-usdc":"10000","tempo-usdc":"10000"},"rules":[{"match":"$","capture":"1"}]},"x-payment-info":{"amount":"10000","currency":"0x20c000000000000000000000b9537d11c60e8b50","description":"Shopper pricing query - $0.01 per request","intent":"charge","method":"tempo","methods":[{"method":"tempo","intent":"charge","currency":"0x20c000000000000000000000b9537d11c60e8b50","decimals":6,"amount":"10000","settlement":"Tempo Allegro USDC.e","role":"primary"}],"price":{"mode":"fixed","currency":"USD","amount":"0.010000"},"protocols":[{"x402":{}},{"mpp":{"method":"tempo","intent":"charge","currency":"USDC","amount":"10000","recipient":"0xe2e662cF219025AFC0C9Bf850b6a2B0a0b5517fe"}}]},"x-sla":{"p50_ms":80,"p99_ms":250,"freshness_seconds_max":300,"idempotency":"safe","cache_hint":"public"},"x-retry-policy":{"min_backoff_seconds":1,"max_backoff_seconds":30,"max_attempts":5,"jitter_required":true,"idempotency_safe":true},"parameters":[{"name":"q","in":"query","required":true,"schema":{"type":"string","minLength":1},"description":"Search query (product name, keyword, or category term)","example":"airpods"},{"name":"country","in":"query","required":false,"schema":{"type":"string","enum":["us","ca"],"default":"us"},"description":"Country (us or ca)","example":"us"},{"name":"retailer","in":"query","required":false,"schema":{"type":"string","enum":["amazon","walmart","costco","homedepot","nordstrom","ikea"]},"description":"Filter to a specific retailer","example":"amazon"},{"name":"from","in":"query","required":false,"schema":{"type":"string","format":"date"},"description":"Start date (ISO 8601, defaults to 30 days ago)","example":"2026-04-01"},{"name":"to","in":"query","required":false,"schema":{"type":"string","format":"date"},"description":"End date (ISO 8601, defaults to now)","example":"2026-05-01"}],"responses":{"200":{"description":"Price history","content":{"application/json":{"schema":{"type":"object","properties":{"query":{"type":"string"},"history":{"type":"array","items":{"type":"object"}}}}}}},"402":{"description":"Payment Required"}},"x-input-schema":{"type":"object","additionalProperties":false,"required":["q"],"properties":{"q":{"type":"string","minLength":1,"description":"Search query (product name, keyword, or category term)","example":"airpods"},"country":{"type":"string","enum":["us","ca"],"default":"us","description":"Country (us or ca)","example":"us"},"retailer":{"type":"string","enum":["amazon","walmart","costco","homedepot","nordstrom","ikea"],"description":"Filter to a specific retailer","example":"amazon"},"from":{"type":"string","format":"date","description":"Start date (ISO 8601, defaults to 30 days ago)","example":"2026-04-01"},"to":{"type":"string","format":"date","description":"End date (ISO 8601, defaults to now)","example":"2026-05-01"}}},"requestBody":{"required":false,"description":"Query parameters as JSON (alternative to URL query string for agents that prefer body-based invocation).","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["q"],"properties":{"q":{"type":"string","minLength":1,"description":"Search query (product name, keyword, or category term)","example":"airpods"},"country":{"type":"string","enum":["us","ca"],"default":"us","description":"Country (us or ca)","example":"us"},"retailer":{"type":"string","enum":["amazon","walmart","costco","homedepot","nordstrom","ikea"],"description":"Filter to a specific retailer","example":"amazon"},"from":{"type":"string","format":"date","description":"Start date (ISO 8601, defaults to 30 days ago)","example":"2026-04-01"},"to":{"type":"string","format":"date","description":"End date (ISO 8601, defaults to now)","example":"2026-05-01"}}}}}}}},"/v1/shopper/deal-finder":{"get":{"operationId":"findDeals","summary":"Find discounted products in a category","description":"Discover actively-promoted discounted products in a category above a minimum discount threshold. Returns deals ranked by discount depth with price, list price, and retailer.","tags":["Shopper"],"x-faremeter-pricing":{"rates":{"solana-usdc":"10000","base-usdc":"10000","tempo-usdc":"10000"},"rules":[{"match":"$","capture":"1"}]},"x-payment-info":{"amount":"10000","currency":"0x20c000000000000000000000b9537d11c60e8b50","description":"Shopper pricing query - $0.01 per request","intent":"charge","method":"tempo","methods":[{"method":"tempo","intent":"charge","currency":"0x20c000000000000000000000b9537d11c60e8b50","decimals":6,"amount":"10000","settlement":"Tempo Allegro USDC.e","role":"primary"}],"price":{"mode":"fixed","currency":"USD","amount":"0.010000"},"protocols":[{"x402":{}},{"mpp":{"method":"tempo","intent":"charge","currency":"USDC","amount":"10000","recipient":"0xe2e662cF219025AFC0C9Bf850b6a2B0a0b5517fe"}}]},"x-sla":{"p50_ms":80,"p99_ms":250,"freshness_seconds_max":300,"idempotency":"safe","cache_hint":"public"},"x-retry-policy":{"min_backoff_seconds":1,"max_backoff_seconds":30,"max_attempts":5,"jitter_required":true,"idempotency_safe":true},"parameters":[{"name":"category","in":"query","required":true,"schema":{"type":"string","minLength":1},"description":"Product category (e.g., electronics, grocery, beauty). Fuzzy human-readable input — the resolver maps it through tier 1-4 (id → exact name → trigram → embedding kNN) to a canonical category_id. Pair with `category_id` if you have a deterministic id from a prior call.","example":"electronics"},{"name":"country","in":"query","required":false,"schema":{"type":"string","enum":["us","ca"],"default":"us"},"description":"Country (us or ca)","example":"us"},{"name":"retailer","in":"query","required":false,"schema":{"type":"string","enum":["amazon","walmart","costco","homedepot","nordstrom","ikea"]},"description":"Filter to a specific retailer","example":"amazon"},{"name":"min_discount_pct","in":"query","required":false,"schema":{"type":"integer","default":10},"description":"Minimum discount percentage (default 10)","example":10},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","default":20,"maximum":50},"description":"Max results to return (default 20, max 50)","example":20}],"responses":{"200":{"description":"Deals found","content":{"application/json":{"schema":{"type":"object","properties":{"category":{"type":"string"},"deals":{"type":"array","items":{"type":"object"}}}}}}},"402":{"description":"Payment Required"}},"x-input-schema":{"type":"object","additionalProperties":false,"required":["category"],"properties":{"category":{"type":"string","minLength":1,"description":"Product category (e.g., electronics, grocery, beauty). Fuzzy human-readable input — the resolver maps it through tier 1-4 (id → exact name → trigram → embedding kNN) to a canonical category_id. Pair with `category_id` if you have a deterministic id from a prior call.","example":"electronics"},"country":{"type":"string","enum":["us","ca"],"default":"us","description":"Country (us or ca)","example":"us"},"retailer":{"type":"string","enum":["amazon","walmart","costco","homedepot","nordstrom","ikea"],"description":"Filter to a specific retailer","example":"amazon"},"min_discount_pct":{"type":"integer","default":10,"description":"Minimum discount percentage (default 10)","example":10},"limit":{"type":"integer","default":20,"maximum":50,"description":"Max results to return (default 20, max 50)","example":20}}},"requestBody":{"required":false,"description":"Query parameters as JSON (alternative to URL query string for agents that prefer body-based invocation).","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["category"],"properties":{"category":{"type":"string","minLength":1,"description":"Product category (e.g., electronics, grocery, beauty). Fuzzy human-readable input — the resolver maps it through tier 1-4 (id → exact name → trigram → embedding kNN) to a canonical category_id. Pair with `category_id` if you have a deterministic id from a prior call.","example":"electronics"},"country":{"type":"string","enum":["us","ca"],"default":"us","description":"Country (us or ca)","example":"us"},"retailer":{"type":"string","enum":["amazon","walmart","costco","homedepot","nordstrom","ikea"],"description":"Filter to a specific retailer","example":"amazon"},"min_discount_pct":{"type":"integer","default":10,"description":"Minimum discount percentage (default 10)","example":10},"limit":{"type":"integer","default":20,"maximum":50,"description":"Max results to return (default 20, max 50)","example":20}}}}}}}},"/v1/shopper/price-drop-alert":{"get":{"operationId":"getPriceDropAlert","summary":"Check for recent price drops on a product","description":"Check whether a product's current price is below its rolling average within a configurable lookback window. Returns current price vs. the average across the window plus the lowest-seen price and date. Response field `avg_price_last_30d` is a fixed name for backwards compatibility; the value is always computed across the configured `lookback_days` window.","tags":["Shopper"],"x-faremeter-pricing":{"rates":{"solana-usdc":"10000","base-usdc":"10000","tempo-usdc":"10000"},"rules":[{"match":"$","capture":"1"}]},"x-payment-info":{"amount":"10000","currency":"0x20c000000000000000000000b9537d11c60e8b50","description":"Shopper pricing query - $0.01 per request","intent":"charge","method":"tempo","methods":[{"method":"tempo","intent":"charge","currency":"0x20c000000000000000000000b9537d11c60e8b50","decimals":6,"amount":"10000","settlement":"Tempo Allegro USDC.e","role":"primary"}],"price":{"mode":"fixed","currency":"USD","amount":"0.010000"},"protocols":[{"x402":{}},{"mpp":{"method":"tempo","intent":"charge","currency":"USDC","amount":"10000","recipient":"0xe2e662cF219025AFC0C9Bf850b6a2B0a0b5517fe"}}]},"x-sla":{"p50_ms":80,"p99_ms":250,"freshness_seconds_max":300,"idempotency":"safe","cache_hint":"public"},"x-retry-policy":{"min_backoff_seconds":1,"max_backoff_seconds":30,"max_attempts":5,"jitter_required":true,"idempotency_safe":true},"parameters":[{"name":"q","in":"query","required":true,"schema":{"type":"string","minLength":1},"description":"Search query (product name, keyword, or category term)","example":"airpods"},{"name":"country","in":"query","required":false,"schema":{"type":"string","enum":["us","ca"],"default":"us"},"description":"Country (us or ca)","example":"us"},{"name":"retailer","in":"query","required":false,"schema":{"type":"string","enum":["amazon","walmart","costco","homedepot","nordstrom","ikea"]},"description":"Filter to a specific retailer","example":"amazon"},{"name":"lookback_days","in":"query","required":false,"schema":{"type":"integer","default":30},"description":"Days to look back for price drops (default 30)","example":30}],"responses":{"200":{"description":"Price drop alerts","content":{"application/json":{"schema":{"type":"object","properties":{"query":{"type":"string"},"drops":{"type":"array","items":{"type":"object"}}}}}}},"402":{"description":"Payment Required"}},"x-input-schema":{"type":"object","additionalProperties":false,"required":["q"],"properties":{"q":{"type":"string","minLength":1,"description":"Search query (product name, keyword, or category term)","example":"airpods"},"country":{"type":"string","enum":["us","ca"],"default":"us","description":"Country (us or ca)","example":"us"},"retailer":{"type":"string","enum":["amazon","walmart","costco","homedepot","nordstrom","ikea"],"description":"Filter to a specific retailer","example":"amazon"},"lookback_days":{"type":"integer","default":30,"description":"Days to look back for price drops (default 30)","example":30}}},"requestBody":{"required":false,"description":"Query parameters as JSON (alternative to URL query string for agents that prefer body-based invocation).","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["q"],"properties":{"q":{"type":"string","minLength":1,"description":"Search query (product name, keyword, or category term)","example":"airpods"},"country":{"type":"string","enum":["us","ca"],"default":"us","description":"Country (us or ca)","example":"us"},"retailer":{"type":"string","enum":["amazon","walmart","costco","homedepot","nordstrom","ikea"],"description":"Filter to a specific retailer","example":"amazon"},"lookback_days":{"type":"integer","default":30,"description":"Days to look back for price drops (default 30)","example":30}}}}}}}},"/v1/marketing/competitive-landscape":{"get":{"operationId":"getCompetitiveLandscape","summary":"View all products and pricing in a category","description":"View every product and its current pricing within a category across retailers. Sortable by price, rating, or review count for competitive benchmarking. Cursor-paginated.","tags":["Marketing"],"x-faremeter-pricing":{"rates":{"solana-usdc":"10000","base-usdc":"10000","tempo-usdc":"10000"},"rules":[{"match":"$","capture":"1"}]},"x-payment-info":{"amount":"10000","currency":"0x20c000000000000000000000b9537d11c60e8b50","description":"Marketing/competitive analysis query - $0.01 per request","intent":"charge","method":"tempo","methods":[{"method":"tempo","intent":"charge","currency":"0x20c000000000000000000000b9537d11c60e8b50","decimals":6,"amount":"10000","settlement":"Tempo Allegro USDC.e","role":"primary"}],"price":{"mode":"fixed","currency":"USD","amount":"0.010000"},"protocols":[{"x402":{}},{"mpp":{"method":"tempo","intent":"charge","currency":"USDC","amount":"10000","recipient":"0xe2e662cF219025AFC0C9Bf850b6a2B0a0b5517fe"}}]},"x-sla":{"p50_ms":100,"p99_ms":350,"freshness_seconds_max":7200,"idempotency":"safe","cache_hint":"public"},"x-retry-policy":{"min_backoff_seconds":2,"max_backoff_seconds":60,"max_attempts":4,"jitter_required":true,"idempotency_safe":true},"parameters":[{"name":"category","in":"query","required":true,"schema":{"type":"string","minLength":1},"description":"Product category (e.g., electronics, grocery, beauty). Fuzzy human-readable input — the resolver maps it through tier 1-4 (id → exact name → trigram → embedding kNN) to a canonical category_id. Pair with `category_id` if you have a deterministic id from a prior call.","example":"electronics"},{"name":"country","in":"query","required":false,"schema":{"type":"string","enum":["us","ca"],"default":"us"},"description":"Country (us or ca)","example":"us"},{"name":"retailer","in":"query","required":false,"schema":{"type":"string","enum":["amazon","walmart","costco","homedepot","nordstrom","ikea"]},"description":"Filter to a specific retailer","example":"amazon"},{"name":"sort_by","in":"query","required":false,"schema":{"type":"string","enum":["price_asc","price_desc","rating","reviews"],"default":"price_asc"},"description":"Sort order","example":"price_asc"},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","default":20,"maximum":50},"description":"Max results to return (default 20, max 50)","example":20}],"responses":{"200":{"description":"Competitive landscape","content":{"application/json":{"schema":{"type":"object"}}}},"402":{"description":"Payment Required"}},"x-input-schema":{"type":"object","additionalProperties":false,"required":["category"],"properties":{"category":{"type":"string","minLength":1,"description":"Product category (e.g., electronics, grocery, beauty). Fuzzy human-readable input — the resolver maps it through tier 1-4 (id → exact name → trigram → embedding kNN) to a canonical category_id. Pair with `category_id` if you have a deterministic id from a prior call.","example":"electronics"},"country":{"type":"string","enum":["us","ca"],"default":"us","description":"Country (us or ca)","example":"us"},"retailer":{"type":"string","enum":["amazon","walmart","costco","homedepot","nordstrom","ikea"],"description":"Filter to a specific retailer","example":"amazon"},"sort_by":{"type":"string","enum":["price_asc","price_desc","rating","reviews"],"default":"price_asc","description":"Sort order","example":"price_asc"},"limit":{"type":"integer","default":20,"maximum":50,"description":"Max results to return (default 20, max 50)","example":20}}},"requestBody":{"required":false,"description":"Query parameters as JSON (alternative to URL query string for agents that prefer body-based invocation).","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["category"],"properties":{"category":{"type":"string","minLength":1,"description":"Product category (e.g., electronics, grocery, beauty). Fuzzy human-readable input — the resolver maps it through tier 1-4 (id → exact name → trigram → embedding kNN) to a canonical category_id. Pair with `category_id` if you have a deterministic id from a prior call.","example":"electronics"},"country":{"type":"string","enum":["us","ca"],"default":"us","description":"Country (us or ca)","example":"us"},"retailer":{"type":"string","enum":["amazon","walmart","costco","homedepot","nordstrom","ikea"],"description":"Filter to a specific retailer","example":"amazon"},"sort_by":{"type":"string","enum":["price_asc","price_desc","rating","reviews"],"default":"price_asc","description":"Sort order","example":"price_asc"},"limit":{"type":"integer","default":20,"maximum":50,"description":"Max results to return (default 20, max 50)","example":20}}}}}}}},"/v1/marketing/brand-tracker":{"get":{"operationId":"trackBrand","summary":"Track a brand's pricing and presence over time","description":"Track a brand's average/min/max price, product count, in-stock count, and promo count day-by-day across a date range.","tags":["Marketing"],"x-faremeter-pricing":{"rates":{"solana-usdc":"10000","base-usdc":"10000","tempo-usdc":"10000"},"rules":[{"match":"$","capture":"1"}]},"x-payment-info":{"amount":"10000","currency":"0x20c000000000000000000000b9537d11c60e8b50","description":"Marketing/competitive analysis query - $0.01 per request","intent":"charge","method":"tempo","methods":[{"method":"tempo","intent":"charge","currency":"0x20c000000000000000000000b9537d11c60e8b50","decimals":6,"amount":"10000","settlement":"Tempo Allegro USDC.e","role":"primary"}],"price":{"mode":"fixed","currency":"USD","amount":"0.010000"},"protocols":[{"x402":{}},{"mpp":{"method":"tempo","intent":"charge","currency":"USDC","amount":"10000","recipient":"0xe2e662cF219025AFC0C9Bf850b6a2B0a0b5517fe"}}]},"x-sla":{"p50_ms":100,"p99_ms":350,"freshness_seconds_max":7200,"idempotency":"safe","cache_hint":"public"},"x-retry-policy":{"min_backoff_seconds":2,"max_backoff_seconds":60,"max_attempts":4,"jitter_required":true,"idempotency_safe":true},"parameters":[{"name":"brand","in":"query","required":true,"schema":{"type":"string","minLength":1},"description":"Brand name (e.g., Sony, Samsung, Nike)","example":"Apple"},{"name":"country","in":"query","required":false,"schema":{"type":"string","enum":["us","ca"],"default":"us"},"description":"Country (us or ca)","example":"us"},{"name":"from","in":"query","required":false,"schema":{"type":"string","format":"date"},"description":"Start date (ISO 8601, defaults to 30 days ago)","example":"2026-04-01"},{"name":"to","in":"query","required":false,"schema":{"type":"string","format":"date"},"description":"End date (ISO 8601, defaults to now)","example":"2026-05-01"}],"responses":{"200":{"description":"Brand tracking data","content":{"application/json":{"schema":{"type":"object"}}}},"402":{"description":"Payment Required"}},"x-input-schema":{"type":"object","additionalProperties":false,"required":["brand"],"properties":{"brand":{"type":"string","minLength":1,"description":"Brand name (e.g., Sony, Samsung, Nike)","example":"Apple"},"country":{"type":"string","enum":["us","ca"],"default":"us","description":"Country (us or ca)","example":"us"},"from":{"type":"string","format":"date","description":"Start date (ISO 8601, defaults to 30 days ago)","example":"2026-04-01"},"to":{"type":"string","format":"date","description":"End date (ISO 8601, defaults to now)","example":"2026-05-01"}}},"requestBody":{"required":false,"description":"Query parameters as JSON (alternative to URL query string for agents that prefer body-based invocation).","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["brand"],"properties":{"brand":{"type":"string","minLength":1,"description":"Brand name (e.g., Sony, Samsung, Nike)","example":"Apple"},"country":{"type":"string","enum":["us","ca"],"default":"us","description":"Country (us or ca)","example":"us"},"from":{"type":"string","format":"date","description":"Start date (ISO 8601, defaults to 30 days ago)","example":"2026-04-01"},"to":{"type":"string","format":"date","description":"End date (ISO 8601, defaults to now)","example":"2026-05-01"}}}}}}}},"/v1/marketing/promo-intelligence":{"get":{"operationId":"getPromoIntelligence","summary":"Analyze promotional activity in a category","description":"Analyze promotional activity within a category - promo frequency, average and max discount depth - over a date range. Pivot the breakdown with `aggregate_by`: default `brand` ranks brands within the category; `retailer` ranks retailers (use together with `brand=<name>` to answer 'which retailers run the deepest promos on Brand X in Category Y'). The response key mirrors the dimension: `brands: [...]` or `retailers: [...]`.","tags":["Marketing"],"x-faremeter-pricing":{"rates":{"solana-usdc":"10000","base-usdc":"10000","tempo-usdc":"10000"},"rules":[{"match":"$","capture":"1"}]},"x-payment-info":{"amount":"10000","currency":"0x20c000000000000000000000b9537d11c60e8b50","description":"Marketing/competitive analysis query - $0.01 per request","intent":"charge","method":"tempo","methods":[{"method":"tempo","intent":"charge","currency":"0x20c000000000000000000000b9537d11c60e8b50","decimals":6,"amount":"10000","settlement":"Tempo Allegro USDC.e","role":"primary"}],"price":{"mode":"fixed","currency":"USD","amount":"0.010000"},"protocols":[{"x402":{}},{"mpp":{"method":"tempo","intent":"charge","currency":"USDC","amount":"10000","recipient":"0xe2e662cF219025AFC0C9Bf850b6a2B0a0b5517fe"}}]},"x-sla":{"p50_ms":100,"p99_ms":350,"freshness_seconds_max":7200,"idempotency":"safe","cache_hint":"public"},"x-retry-policy":{"min_backoff_seconds":2,"max_backoff_seconds":60,"max_attempts":4,"jitter_required":true,"idempotency_safe":true},"parameters":[{"name":"category","in":"query","required":true,"schema":{"type":"string","minLength":1},"description":"Product category (e.g., electronics, grocery, beauty). Fuzzy human-readable input — the resolver maps it through tier 1-4 (id → exact name → trigram → embedding kNN) to a canonical category_id. Pair with `category_id` if you have a deterministic id from a prior call.","example":"electronics"},{"name":"country","in":"query","required":false,"schema":{"type":"string","enum":["us","ca"],"default":"us"},"description":"Country (us or ca)","example":"us"},{"name":"brand","in":"query","required":false,"schema":{"type":"string","minLength":1},"description":"Optional brand filter — limit aggregation to products of this brand (case-insensitive)","example":"Apple"},{"name":"aggregate_by","in":"query","required":false,"schema":{"type":"string","enum":["brand","retailer"],"default":"brand"},"description":"Group-by dimension. `brand` (default) ranks brands within the category. `retailer` ranks retailers — pair with `brand` to answer 'which retailers run the deepest promos on Brand X'.","example":"retailer"},{"name":"from","in":"query","required":false,"schema":{"type":"string","format":"date"},"description":"Start date (ISO 8601, defaults to 30 days ago)","example":"2026-04-01"},{"name":"to","in":"query","required":false,"schema":{"type":"string","format":"date"},"description":"End date (ISO 8601, defaults to now)","example":"2026-05-01"}],"responses":{"200":{"description":"Promo intelligence","content":{"application/json":{"schema":{"type":"object"}}}},"402":{"description":"Payment Required"}},"x-input-schema":{"type":"object","additionalProperties":false,"required":["category"],"properties":{"category":{"type":"string","minLength":1,"description":"Product category (e.g., electronics, grocery, beauty). Fuzzy human-readable input — the resolver maps it through tier 1-4 (id → exact name → trigram → embedding kNN) to a canonical category_id. Pair with `category_id` if you have a deterministic id from a prior call.","example":"electronics"},"country":{"type":"string","enum":["us","ca"],"default":"us","description":"Country (us or ca)","example":"us"},"brand":{"type":"string","minLength":1,"description":"Optional brand filter — limit aggregation to products of this brand (case-insensitive)","example":"Apple"},"aggregate_by":{"type":"string","enum":["brand","retailer"],"default":"brand","description":"Group-by dimension. `brand` (default) ranks brands within the category. `retailer` ranks retailers — pair with `brand` to answer 'which retailers run the deepest promos on Brand X'.","example":"retailer"},"from":{"type":"string","format":"date","description":"Start date (ISO 8601, defaults to 30 days ago)","example":"2026-04-01"},"to":{"type":"string","format":"date","description":"End date (ISO 8601, defaults to now)","example":"2026-05-01"}}},"requestBody":{"required":false,"description":"Query parameters as JSON (alternative to URL query string for agents that prefer body-based invocation).","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["category"],"properties":{"category":{"type":"string","minLength":1,"description":"Product category (e.g., electronics, grocery, beauty). Fuzzy human-readable input — the resolver maps it through tier 1-4 (id → exact name → trigram → embedding kNN) to a canonical category_id. Pair with `category_id` if you have a deterministic id from a prior call.","example":"electronics"},"country":{"type":"string","enum":["us","ca"],"default":"us","description":"Country (us or ca)","example":"us"},"brand":{"type":"string","minLength":1,"description":"Optional brand filter — limit aggregation to products of this brand (case-insensitive)","example":"Apple"},"aggregate_by":{"type":"string","enum":["brand","retailer"],"default":"brand","description":"Group-by dimension. `brand` (default) ranks brands within the category. `retailer` ranks retailers — pair with `brand` to answer 'which retailers run the deepest promos on Brand X'.","example":"retailer"},"from":{"type":"string","format":"date","description":"Start date (ISO 8601, defaults to 30 days ago)","example":"2026-04-01"},"to":{"type":"string","format":"date","description":"End date (ISO 8601, defaults to now)","example":"2026-05-01"}}}}}}}},"/v1/marketing/share-of-shelf":{"get":{"operationId":"getShareOfShelf","summary":"See brand market share within a category","description":"Measure each brand's market share within a category by product count. Shows digital shelf dominance.","tags":["Marketing"],"x-faremeter-pricing":{"rates":{"solana-usdc":"10000","base-usdc":"10000","tempo-usdc":"10000"},"rules":[{"match":"$","capture":"1"}]},"x-payment-info":{"amount":"10000","currency":"0x20c000000000000000000000b9537d11c60e8b50","description":"Marketing/competitive analysis query - $0.01 per request","intent":"charge","method":"tempo","methods":[{"method":"tempo","intent":"charge","currency":"0x20c000000000000000000000b9537d11c60e8b50","decimals":6,"amount":"10000","settlement":"Tempo Allegro USDC.e","role":"primary"}],"price":{"mode":"fixed","currency":"USD","amount":"0.010000"},"protocols":[{"x402":{}},{"mpp":{"method":"tempo","intent":"charge","currency":"USDC","amount":"10000","recipient":"0xe2e662cF219025AFC0C9Bf850b6a2B0a0b5517fe"}}]},"x-sla":{"p50_ms":100,"p99_ms":350,"freshness_seconds_max":7200,"idempotency":"safe","cache_hint":"public"},"x-retry-policy":{"min_backoff_seconds":2,"max_backoff_seconds":60,"max_attempts":4,"jitter_required":true,"idempotency_safe":true},"parameters":[{"name":"category","in":"query","required":true,"schema":{"type":"string","minLength":1},"description":"Product category (e.g., electronics, grocery, beauty). Fuzzy human-readable input — the resolver maps it through tier 1-4 (id → exact name → trigram → embedding kNN) to a canonical category_id. Pair with `category_id` if you have a deterministic id from a prior call.","example":"electronics"},{"name":"category_id","in":"query","required":false,"schema":{"type":"integer","minimum":1},"description":"Deterministic category id. When set, bypasses the fuzzy resolver cascade and uses tier 1 (id lookup) directly. Agents that learned a canonical id from a prior call's `resolved.category_id` should pin it here for round-trip stability.","example":1},{"name":"country","in":"query","required":false,"schema":{"type":"string","enum":["us","ca"],"default":"us"},"description":"Country (us or ca)","example":"us"}],"responses":{"200":{"description":"Share of shelf data","content":{"application/json":{"schema":{"type":"object"}}}},"402":{"description":"Payment Required"}},"x-input-schema":{"type":"object","additionalProperties":false,"required":["category"],"properties":{"category":{"type":"string","minLength":1,"description":"Product category (e.g., electronics, grocery, beauty). Fuzzy human-readable input — the resolver maps it through tier 1-4 (id → exact name → trigram → embedding kNN) to a canonical category_id. Pair with `category_id` if you have a deterministic id from a prior call.","example":"electronics"},"category_id":{"type":"integer","minimum":1,"description":"Deterministic category id. When set, bypasses the fuzzy resolver cascade and uses tier 1 (id lookup) directly. Agents that learned a canonical id from a prior call's `resolved.category_id` should pin it here for round-trip stability.","example":1},"country":{"type":"string","enum":["us","ca"],"default":"us","description":"Country (us or ca)","example":"us"}}},"requestBody":{"required":false,"description":"Query parameters as JSON (alternative to URL query string for agents that prefer body-based invocation).","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["category"],"properties":{"category":{"type":"string","minLength":1,"description":"Product category (e.g., electronics, grocery, beauty). Fuzzy human-readable input — the resolver maps it through tier 1-4 (id → exact name → trigram → embedding kNN) to a canonical category_id. Pair with `category_id` if you have a deterministic id from a prior call.","example":"electronics"},"category_id":{"type":"integer","minimum":1,"description":"Deterministic category id. When set, bypasses the fuzzy resolver cascade and uses tier 1 (id lookup) directly. Agents that learned a canonical id from a prior call's `resolved.category_id` should pin it here for round-trip stability.","example":1},"country":{"type":"string","enum":["us","ca"],"default":"us","description":"Country (us or ca)","example":"us"}}}}}}}},"/v1/marketing/price-positioning":{"get":{"operationId":"getPricePositioning","summary":"Analyze a brand's price positioning vs competitors","description":"Compare a brand's average price to the category average/median and classify positioning as premium, mid-range, or value.","tags":["Marketing"],"x-faremeter-pricing":{"rates":{"solana-usdc":"10000","base-usdc":"10000","tempo-usdc":"10000"},"rules":[{"match":"$","capture":"1"}]},"x-payment-info":{"amount":"10000","currency":"0x20c000000000000000000000b9537d11c60e8b50","description":"Marketing/competitive analysis query - $0.01 per request","intent":"charge","method":"tempo","methods":[{"method":"tempo","intent":"charge","currency":"0x20c000000000000000000000b9537d11c60e8b50","decimals":6,"amount":"10000","settlement":"Tempo Allegro USDC.e","role":"primary"}],"price":{"mode":"fixed","currency":"USD","amount":"0.010000"},"protocols":[{"x402":{}},{"mpp":{"method":"tempo","intent":"charge","currency":"USDC","amount":"10000","recipient":"0xe2e662cF219025AFC0C9Bf850b6a2B0a0b5517fe"}}]},"x-sla":{"p50_ms":100,"p99_ms":350,"freshness_seconds_max":7200,"idempotency":"safe","cache_hint":"public"},"x-retry-policy":{"min_backoff_seconds":2,"max_backoff_seconds":60,"max_attempts":4,"jitter_required":true,"idempotency_safe":true},"parameters":[{"name":"brand","in":"query","required":true,"schema":{"type":"string","minLength":1},"description":"Brand name (e.g., Sony, Samsung, Nike)","example":"Apple"},{"name":"country","in":"query","required":false,"schema":{"type":"string","enum":["us","ca"],"default":"us"},"description":"Country (us or ca)","example":"us"},{"name":"category","in":"query","required":false,"schema":{"type":"string","minLength":1},"description":"Product category (e.g., electronics, grocery, beauty). Fuzzy human-readable input — the resolver maps it through tier 1-4 (id → exact name → trigram → embedding kNN) to a canonical category_id. Pair with `category_id` if you have a deterministic id from a prior call.","example":"electronics"}],"responses":{"200":{"description":"Price positioning data","content":{"application/json":{"schema":{"type":"object"}}}},"402":{"description":"Payment Required"}},"x-input-schema":{"type":"object","additionalProperties":false,"required":["brand"],"properties":{"brand":{"type":"string","minLength":1,"description":"Brand name (e.g., Sony, Samsung, Nike)","example":"Apple"},"country":{"type":"string","enum":["us","ca"],"default":"us","description":"Country (us or ca)","example":"us"},"category":{"type":"string","minLength":1,"description":"Product category (e.g., electronics, grocery, beauty). Fuzzy human-readable input — the resolver maps it through tier 1-4 (id → exact name → trigram → embedding kNN) to a canonical category_id. Pair with `category_id` if you have a deterministic id from a prior call.","example":"electronics"}}},"requestBody":{"required":false,"description":"Query parameters as JSON (alternative to URL query string for agents that prefer body-based invocation).","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["brand"],"properties":{"brand":{"type":"string","minLength":1,"description":"Brand name (e.g., Sony, Samsung, Nike)","example":"Apple"},"country":{"type":"string","enum":["us","ca"],"default":"us","description":"Country (us or ca)","example":"us"},"category":{"type":"string","minLength":1,"description":"Product category (e.g., electronics, grocery, beauty). Fuzzy human-readable input — the resolver maps it through tier 1-4 (id → exact name → trigram → embedding kNN) to a canonical category_id. Pair with `category_id` if you have a deterministic id from a prior call.","example":"electronics"}}}}}}}},"/v1/analyst/inflation":{"get":{"operationId":"getInflation","summary":"Track price inflation trends in a category or department","description":"Track category-level price inflation with configurable daily, weekly, or monthly granularity. Returns period-over-period change and overall change.","tags":["Analyst"],"x-faremeter-pricing":{"rates":{"solana-usdc":"20000","base-usdc":"20000","tempo-usdc":"20000"},"rules":[{"match":"$","capture":"1"}]},"x-payment-info":{"amount":"20000","currency":"0x20c000000000000000000000b9537d11c60e8b50","description":"Analyst/market-level query - $0.02 per request","intent":"charge","method":"tempo","methods":[{"method":"tempo","intent":"charge","currency":"0x20c000000000000000000000b9537d11c60e8b50","decimals":6,"amount":"20000","settlement":"Tempo Allegro USDC.e","role":"primary"}],"price":{"mode":"fixed","currency":"USD","amount":"0.020000"},"protocols":[{"x402":{}},{"mpp":{"method":"tempo","intent":"charge","currency":"USDC","amount":"20000","recipient":"0xe2e662cF219025AFC0C9Bf850b6a2B0a0b5517fe"}}]},"x-sla":{"p50_ms":150,"p99_ms":500,"freshness_seconds_max":86400,"idempotency":"safe","cache_hint":"public"},"x-retry-policy":{"min_backoff_seconds":5,"max_backoff_seconds":120,"max_attempts":3,"jitter_required":true,"idempotency_safe":true},"parameters":[{"name":"category","in":"query","required":false,"schema":{"type":"string","minLength":1},"description":"Product category (e.g., electronics, grocery, beauty). Fuzzy human-readable input — the resolver maps it through tier 1-4 (id → exact name → trigram → embedding kNN) to a canonical category_id. Pair with `category_id` if you have a deterministic id from a prior call.","example":"electronics"},{"name":"category_id","in":"query","required":false,"schema":{"type":"integer","minimum":1},"description":"Deterministic category id. When set, bypasses the fuzzy resolver cascade and uses tier 1 (id lookup) directly. Agents that learned a canonical id from a prior call's `resolved.category_id` should pin it here for round-trip stability.","example":1},{"name":"department","in":"query","required":false,"schema":{"type":"string","minLength":1},"description":"Coarse depth-1 BrowseNodes department label (e.g., 'Electronics', 'Grocery', 'Toys & Games'). Exact-match, case-sensitive Title Case. Optional alongside `category`; either parameter alone or both together are accepted. Use this for stable cross-agent queries where the leaf-level category is too noisy.","example":"Electronics"},{"name":"country","in":"query","required":false,"schema":{"type":"string","enum":["us","ca"],"default":"us"},"description":"Country (us or ca)","example":"us"},{"name":"from","in":"query","required":false,"schema":{"type":"string","format":"date"},"description":"Start date (ISO 8601, defaults to 30 days ago)","example":"2026-04-01"},{"name":"to","in":"query","required":false,"schema":{"type":"string","format":"date"},"description":"End date (ISO 8601, defaults to now)","example":"2026-05-01"},{"name":"granularity","in":"query","required":false,"schema":{"type":"string","enum":["daily","weekly","monthly"],"default":"weekly"},"description":"Time granularity for the series","example":"weekly"}],"responses":{"200":{"description":"Inflation data","content":{"application/json":{"schema":{"type":"object"}}}},"402":{"description":"Payment Required"}},"x-input-schema":{"type":"object","additionalProperties":false,"properties":{"category":{"type":"string","minLength":1,"description":"Product category (e.g., electronics, grocery, beauty). Fuzzy human-readable input — the resolver maps it through tier 1-4 (id → exact name → trigram → embedding kNN) to a canonical category_id. Pair with `category_id` if you have a deterministic id from a prior call.","example":"electronics"},"category_id":{"type":"integer","minimum":1,"description":"Deterministic category id. When set, bypasses the fuzzy resolver cascade and uses tier 1 (id lookup) directly. Agents that learned a canonical id from a prior call's `resolved.category_id` should pin it here for round-trip stability.","example":1},"department":{"type":"string","minLength":1,"description":"Coarse depth-1 BrowseNodes department label (e.g., 'Electronics', 'Grocery', 'Toys & Games'). Exact-match, case-sensitive Title Case. Optional alongside `category`; either parameter alone or both together are accepted. Use this for stable cross-agent queries where the leaf-level category is too noisy.","example":"Electronics"},"country":{"type":"string","enum":["us","ca"],"default":"us","description":"Country (us or ca)","example":"us"},"from":{"type":"string","format":"date","description":"Start date (ISO 8601, defaults to 30 days ago)","example":"2026-04-01"},"to":{"type":"string","format":"date","description":"End date (ISO 8601, defaults to now)","example":"2026-05-01"},"granularity":{"type":"string","enum":["daily","weekly","monthly"],"default":"weekly","description":"Time granularity for the series","example":"weekly"}}},"requestBody":{"required":false,"description":"Query parameters as JSON (alternative to URL query string for agents that prefer body-based invocation).","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"category":{"type":"string","minLength":1,"description":"Product category (e.g., electronics, grocery, beauty). Fuzzy human-readable input — the resolver maps it through tier 1-4 (id → exact name → trigram → embedding kNN) to a canonical category_id. Pair with `category_id` if you have a deterministic id from a prior call.","example":"electronics"},"category_id":{"type":"integer","minimum":1,"description":"Deterministic category id. When set, bypasses the fuzzy resolver cascade and uses tier 1 (id lookup) directly. Agents that learned a canonical id from a prior call's `resolved.category_id` should pin it here for round-trip stability.","example":1},"department":{"type":"string","minLength":1,"description":"Coarse depth-1 BrowseNodes department label (e.g., 'Electronics', 'Grocery', 'Toys & Games'). Exact-match, case-sensitive Title Case. Optional alongside `category`; either parameter alone or both together are accepted. Use this for stable cross-agent queries where the leaf-level category is too noisy.","example":"Electronics"},"country":{"type":"string","enum":["us","ca"],"default":"us","description":"Country (us or ca)","example":"us"},"from":{"type":"string","format":"date","description":"Start date (ISO 8601, defaults to 30 days ago)","example":"2026-04-01"},"to":{"type":"string","format":"date","description":"End date (ISO 8601, defaults to now)","example":"2026-05-01"},"granularity":{"type":"string","enum":["daily","weekly","monthly"],"default":"weekly","description":"Time granularity for the series","example":"weekly"}}}}}}}},"/v1/analyst/price-dispersion":{"get":{"operationId":"getPriceDispersion","summary":"Analyze price spread across retailers for a category or department","description":"Analyze price spread within a category - mean, stddev, coefficient of variation, and percentiles (p10..p90) with IQR outlier exclusion.","tags":["Analyst"],"x-faremeter-pricing":{"rates":{"solana-usdc":"20000","base-usdc":"20000","tempo-usdc":"20000"},"rules":[{"match":"$","capture":"1"}]},"x-payment-info":{"amount":"20000","currency":"0x20c000000000000000000000b9537d11c60e8b50","description":"Analyst/market-level query - $0.02 per request","intent":"charge","method":"tempo","methods":[{"method":"tempo","intent":"charge","currency":"0x20c000000000000000000000b9537d11c60e8b50","decimals":6,"amount":"20000","settlement":"Tempo Allegro USDC.e","role":"primary"}],"price":{"mode":"fixed","currency":"USD","amount":"0.020000"},"protocols":[{"x402":{}},{"mpp":{"method":"tempo","intent":"charge","currency":"USDC","amount":"20000","recipient":"0xe2e662cF219025AFC0C9Bf850b6a2B0a0b5517fe"}}]},"x-sla":{"p50_ms":150,"p99_ms":500,"freshness_seconds_max":86400,"idempotency":"safe","cache_hint":"public"},"x-retry-policy":{"min_backoff_seconds":5,"max_backoff_seconds":120,"max_attempts":3,"jitter_required":true,"idempotency_safe":true},"parameters":[{"name":"category","in":"query","required":false,"schema":{"type":"string","minLength":1},"description":"Product category (e.g., electronics, grocery, beauty). Fuzzy human-readable input — the resolver maps it through tier 1-4 (id → exact name → trigram → embedding kNN) to a canonical category_id. Pair with `category_id` if you have a deterministic id from a prior call.","example":"electronics"},{"name":"category_id","in":"query","required":false,"schema":{"type":"integer","minimum":1},"description":"Deterministic category id. When set, bypasses the fuzzy resolver cascade and uses tier 1 (id lookup) directly. Agents that learned a canonical id from a prior call's `resolved.category_id` should pin it here for round-trip stability.","example":1},{"name":"department","in":"query","required":false,"schema":{"type":"string","minLength":1},"description":"Coarse depth-1 BrowseNodes department label (e.g., 'Electronics', 'Grocery', 'Toys & Games'). Exact-match, case-sensitive Title Case. Optional alongside `category`; either parameter alone or both together are accepted. Use this for stable cross-agent queries where the leaf-level category is too noisy.","example":"Electronics"},{"name":"country","in":"query","required":false,"schema":{"type":"string","enum":["us","ca"],"default":"us"},"description":"Country (us or ca)","example":"us"}],"responses":{"200":{"description":"Price dispersion data","content":{"application/json":{"schema":{"type":"object"}}}},"402":{"description":"Payment Required"}},"x-input-schema":{"type":"object","additionalProperties":false,"properties":{"category":{"type":"string","minLength":1,"description":"Product category (e.g., electronics, grocery, beauty). Fuzzy human-readable input — the resolver maps it through tier 1-4 (id → exact name → trigram → embedding kNN) to a canonical category_id. Pair with `category_id` if you have a deterministic id from a prior call.","example":"electronics"},"category_id":{"type":"integer","minimum":1,"description":"Deterministic category id. When set, bypasses the fuzzy resolver cascade and uses tier 1 (id lookup) directly. Agents that learned a canonical id from a prior call's `resolved.category_id` should pin it here for round-trip stability.","example":1},"department":{"type":"string","minLength":1,"description":"Coarse depth-1 BrowseNodes department label (e.g., 'Electronics', 'Grocery', 'Toys & Games'). Exact-match, case-sensitive Title Case. Optional alongside `category`; either parameter alone or both together are accepted. Use this for stable cross-agent queries where the leaf-level category is too noisy.","example":"Electronics"},"country":{"type":"string","enum":["us","ca"],"default":"us","description":"Country (us or ca)","example":"us"}}},"requestBody":{"required":false,"description":"Query parameters as JSON (alternative to URL query string for agents that prefer body-based invocation).","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"category":{"type":"string","minLength":1,"description":"Product category (e.g., electronics, grocery, beauty). Fuzzy human-readable input — the resolver maps it through tier 1-4 (id → exact name → trigram → embedding kNN) to a canonical category_id. Pair with `category_id` if you have a deterministic id from a prior call.","example":"electronics"},"category_id":{"type":"integer","minimum":1,"description":"Deterministic category id. When set, bypasses the fuzzy resolver cascade and uses tier 1 (id lookup) directly. Agents that learned a canonical id from a prior call's `resolved.category_id` should pin it here for round-trip stability.","example":1},"department":{"type":"string","minLength":1,"description":"Coarse depth-1 BrowseNodes department label (e.g., 'Electronics', 'Grocery', 'Toys & Games'). Exact-match, case-sensitive Title Case. Optional alongside `category`; either parameter alone or both together are accepted. Use this for stable cross-agent queries where the leaf-level category is too noisy.","example":"Electronics"},"country":{"type":"string","enum":["us","ca"],"default":"us","description":"Country (us or ca)","example":"us"}}}}}}}},"/v1/analyst/retailer-index":{"get":{"operationId":"getRetailerIndex","summary":"Price index for a specific retailer over time","description":"Compute a normalized price index (retailer avg / category avg) for a specific retailer day-by-day versus its category baseline.","tags":["Analyst"],"x-faremeter-pricing":{"rates":{"solana-usdc":"20000","base-usdc":"20000","tempo-usdc":"20000"},"rules":[{"match":"$","capture":"1"}]},"x-payment-info":{"amount":"20000","currency":"0x20c000000000000000000000b9537d11c60e8b50","description":"Analyst/market-level query - $0.02 per request","intent":"charge","method":"tempo","methods":[{"method":"tempo","intent":"charge","currency":"0x20c000000000000000000000b9537d11c60e8b50","decimals":6,"amount":"20000","settlement":"Tempo Allegro USDC.e","role":"primary"}],"price":{"mode":"fixed","currency":"USD","amount":"0.020000"},"protocols":[{"x402":{}},{"mpp":{"method":"tempo","intent":"charge","currency":"USDC","amount":"20000","recipient":"0xe2e662cF219025AFC0C9Bf850b6a2B0a0b5517fe"}}]},"x-sla":{"p50_ms":150,"p99_ms":500,"freshness_seconds_max":86400,"idempotency":"safe","cache_hint":"public"},"x-retry-policy":{"min_backoff_seconds":5,"max_backoff_seconds":120,"max_attempts":3,"jitter_required":true,"idempotency_safe":true},"parameters":[{"name":"retailer","in":"query","required":true,"schema":{"type":"string"},"description":"Retailer name (e.g., amazon, walmart)","example":"amazon"},{"name":"country","in":"query","required":false,"schema":{"type":"string","enum":["us","ca"],"default":"us"},"description":"Country (us or ca)","example":"us"},{"name":"category","in":"query","required":false,"schema":{"type":"string","minLength":1},"description":"Product category (e.g., electronics, grocery, beauty). Fuzzy human-readable input — the resolver maps it through tier 1-4 (id → exact name → trigram → embedding kNN) to a canonical category_id. Pair with `category_id` if you have a deterministic id from a prior call.","example":"electronics"},{"name":"category_id","in":"query","required":false,"schema":{"type":"integer","minimum":1},"description":"Deterministic category id. When set, bypasses the fuzzy resolver cascade and uses tier 1 (id lookup) directly. Agents that learned a canonical id from a prior call's `resolved.category_id` should pin it here for round-trip stability.","example":1},{"name":"department","in":"query","required":false,"schema":{"type":"string","minLength":1},"description":"Coarse depth-1 BrowseNodes department label (e.g., 'Electronics', 'Grocery', 'Toys & Games'). Exact-match, case-sensitive Title Case. Optional alongside `category`; either parameter alone or both together are accepted. Use this for stable cross-agent queries where the leaf-level category is too noisy.","example":"Electronics"},{"name":"from","in":"query","required":false,"schema":{"type":"string","format":"date"},"description":"Start date (ISO 8601, defaults to 30 days ago)","example":"2026-04-01"},{"name":"to","in":"query","required":false,"schema":{"type":"string","format":"date"},"description":"End date (ISO 8601, defaults to now)","example":"2026-05-01"}],"responses":{"200":{"description":"Retailer index data","content":{"application/json":{"schema":{"type":"object"}}}},"402":{"description":"Payment Required"}},"x-input-schema":{"type":"object","additionalProperties":false,"required":["retailer"],"properties":{"retailer":{"type":"string","description":"Retailer name (e.g., amazon, walmart)","example":"amazon"},"country":{"type":"string","enum":["us","ca"],"default":"us","description":"Country (us or ca)","example":"us"},"category":{"type":"string","minLength":1,"description":"Product category (e.g., electronics, grocery, beauty). Fuzzy human-readable input — the resolver maps it through tier 1-4 (id → exact name → trigram → embedding kNN) to a canonical category_id. Pair with `category_id` if you have a deterministic id from a prior call.","example":"electronics"},"category_id":{"type":"integer","minimum":1,"description":"Deterministic category id. When set, bypasses the fuzzy resolver cascade and uses tier 1 (id lookup) directly. Agents that learned a canonical id from a prior call's `resolved.category_id` should pin it here for round-trip stability.","example":1},"department":{"type":"string","minLength":1,"description":"Coarse depth-1 BrowseNodes department label (e.g., 'Electronics', 'Grocery', 'Toys & Games'). Exact-match, case-sensitive Title Case. Optional alongside `category`; either parameter alone or both together are accepted. Use this for stable cross-agent queries where the leaf-level category is too noisy.","example":"Electronics"},"from":{"type":"string","format":"date","description":"Start date (ISO 8601, defaults to 30 days ago)","example":"2026-04-01"},"to":{"type":"string","format":"date","description":"End date (ISO 8601, defaults to now)","example":"2026-05-01"}}},"requestBody":{"required":false,"description":"Query parameters as JSON (alternative to URL query string for agents that prefer body-based invocation).","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["retailer"],"properties":{"retailer":{"type":"string","description":"Retailer name (e.g., amazon, walmart)","example":"amazon"},"country":{"type":"string","enum":["us","ca"],"default":"us","description":"Country (us or ca)","example":"us"},"category":{"type":"string","minLength":1,"description":"Product category (e.g., electronics, grocery, beauty). Fuzzy human-readable input — the resolver maps it through tier 1-4 (id → exact name → trigram → embedding kNN) to a canonical category_id. Pair with `category_id` if you have a deterministic id from a prior call.","example":"electronics"},"category_id":{"type":"integer","minimum":1,"description":"Deterministic category id. When set, bypasses the fuzzy resolver cascade and uses tier 1 (id lookup) directly. Agents that learned a canonical id from a prior call's `resolved.category_id` should pin it here for round-trip stability.","example":1},"department":{"type":"string","minLength":1,"description":"Coarse depth-1 BrowseNodes department label (e.g., 'Electronics', 'Grocery', 'Toys & Games'). Exact-match, case-sensitive Title Case. Optional alongside `category`; either parameter alone or both together are accepted. Use this for stable cross-agent queries where the leaf-level category is too noisy.","example":"Electronics"},"from":{"type":"string","format":"date","description":"Start date (ISO 8601, defaults to 30 days ago)","example":"2026-04-01"},"to":{"type":"string","format":"date","description":"End date (ISO 8601, defaults to now)","example":"2026-05-01"}}}}}}}},"/v1/analyst/category-summary":{"get":{"operationId":"getCategorySummary","summary":"High-level summary statistics for a category or department","description":"High-level category statistics - product/brand/retailer counts, pricing (avg/min/max/median), avg rating, promo rate, in-stock rate, and top brands.","tags":["Analyst"],"x-faremeter-pricing":{"rates":{"solana-usdc":"20000","base-usdc":"20000","tempo-usdc":"20000"},"rules":[{"match":"$","capture":"1"}]},"x-payment-info":{"amount":"20000","currency":"0x20c000000000000000000000b9537d11c60e8b50","description":"Analyst/market-level query - $0.02 per request","intent":"charge","method":"tempo","methods":[{"method":"tempo","intent":"charge","currency":"0x20c000000000000000000000b9537d11c60e8b50","decimals":6,"amount":"20000","settlement":"Tempo Allegro USDC.e","role":"primary"}],"price":{"mode":"fixed","currency":"USD","amount":"0.020000"},"protocols":[{"x402":{}},{"mpp":{"method":"tempo","intent":"charge","currency":"USDC","amount":"20000","recipient":"0xe2e662cF219025AFC0C9Bf850b6a2B0a0b5517fe"}}]},"x-sla":{"p50_ms":150,"p99_ms":500,"freshness_seconds_max":86400,"idempotency":"safe","cache_hint":"public"},"x-retry-policy":{"min_backoff_seconds":5,"max_backoff_seconds":120,"max_attempts":3,"jitter_required":true,"idempotency_safe":true},"parameters":[{"name":"category","in":"query","required":false,"schema":{"type":"string","minLength":1},"description":"Product category (e.g., electronics, grocery, beauty). Fuzzy human-readable input — the resolver maps it through tier 1-4 (id → exact name → trigram → embedding kNN) to a canonical category_id. Pair with `category_id` if you have a deterministic id from a prior call.","example":"electronics"},{"name":"category_id","in":"query","required":false,"schema":{"type":"integer","minimum":1},"description":"Deterministic category id. When set, bypasses the fuzzy resolver cascade and uses tier 1 (id lookup) directly. Agents that learned a canonical id from a prior call's `resolved.category_id` should pin it here for round-trip stability.","example":1},{"name":"department","in":"query","required":false,"schema":{"type":"string","minLength":1},"description":"Coarse depth-1 BrowseNodes department label (e.g., 'Electronics', 'Grocery', 'Toys & Games'). Exact-match, case-sensitive Title Case. Optional alongside `category`; either parameter alone or both together are accepted. Use this for stable cross-agent queries where the leaf-level category is too noisy.","example":"Electronics"},{"name":"country","in":"query","required":false,"schema":{"type":"string","enum":["us","ca"],"default":"us"},"description":"Country (us or ca)","example":"us"}],"responses":{"200":{"description":"Category summary","content":{"application/json":{"schema":{"type":"object"}}}},"402":{"description":"Payment Required"}},"x-input-schema":{"type":"object","additionalProperties":false,"properties":{"category":{"type":"string","minLength":1,"description":"Product category (e.g., electronics, grocery, beauty). Fuzzy human-readable input — the resolver maps it through tier 1-4 (id → exact name → trigram → embedding kNN) to a canonical category_id. Pair with `category_id` if you have a deterministic id from a prior call.","example":"electronics"},"category_id":{"type":"integer","minimum":1,"description":"Deterministic category id. When set, bypasses the fuzzy resolver cascade and uses tier 1 (id lookup) directly. Agents that learned a canonical id from a prior call's `resolved.category_id` should pin it here for round-trip stability.","example":1},"department":{"type":"string","minLength":1,"description":"Coarse depth-1 BrowseNodes department label (e.g., 'Electronics', 'Grocery', 'Toys & Games'). Exact-match, case-sensitive Title Case. Optional alongside `category`; either parameter alone or both together are accepted. Use this for stable cross-agent queries where the leaf-level category is too noisy.","example":"Electronics"},"country":{"type":"string","enum":["us","ca"],"default":"us","description":"Country (us or ca)","example":"us"}}},"requestBody":{"required":false,"description":"Query parameters as JSON (alternative to URL query string for agents that prefer body-based invocation).","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"category":{"type":"string","minLength":1,"description":"Product category (e.g., electronics, grocery, beauty). Fuzzy human-readable input — the resolver maps it through tier 1-4 (id → exact name → trigram → embedding kNN) to a canonical category_id. Pair with `category_id` if you have a deterministic id from a prior call.","example":"electronics"},"category_id":{"type":"integer","minimum":1,"description":"Deterministic category id. When set, bypasses the fuzzy resolver cascade and uses tier 1 (id lookup) directly. Agents that learned a canonical id from a prior call's `resolved.category_id` should pin it here for round-trip stability.","example":1},"department":{"type":"string","minLength":1,"description":"Coarse depth-1 BrowseNodes department label (e.g., 'Electronics', 'Grocery', 'Toys & Games'). Exact-match, case-sensitive Title Case. Optional alongside `category`; either parameter alone or both together are accepted. Use this for stable cross-agent queries where the leaf-level category is too noisy.","example":"Electronics"},"country":{"type":"string","enum":["us","ca"],"default":"us","description":"Country (us or ca)","example":"us"}}}}}}}}},"components":{"schemas":{"GetBestPriceInput":{"type":"object","additionalProperties":false,"required":["q"],"properties":{"q":{"type":"string","minLength":1,"description":"Search query (product name, keyword, or category term)","example":"airpods"},"country":{"type":"string","enum":["us","ca"],"default":"us","description":"Country (us or ca)","example":"us"},"retailer":{"type":"string","enum":["amazon","walmart","costco","homedepot","nordstrom","ikea"],"description":"Filter to a specific retailer","example":"amazon"},"limit":{"type":"integer","default":10,"maximum":50,"description":"Max results to return (default 10, max 50)","example":10}}},"GetPriceHistoryInput":{"type":"object","additionalProperties":false,"required":["q"],"properties":{"q":{"type":"string","minLength":1,"description":"Search query (product name, keyword, or category term)","example":"airpods"},"country":{"type":"string","enum":["us","ca"],"default":"us","description":"Country (us or ca)","example":"us"},"retailer":{"type":"string","enum":["amazon","walmart","costco","homedepot","nordstrom","ikea"],"description":"Filter to a specific retailer","example":"amazon"},"from":{"type":"string","format":"date","description":"Start date (ISO 8601, defaults to 30 days ago)","example":"2026-04-01"},"to":{"type":"string","format":"date","description":"End date (ISO 8601, defaults to now)","example":"2026-05-01"}}},"FindDealsInput":{"type":"object","additionalProperties":false,"required":["category"],"properties":{"category":{"type":"string","minLength":1,"description":"Product category (e.g., electronics, grocery, beauty). Fuzzy human-readable input — the resolver maps it through tier 1-4 (id → exact name → trigram → embedding kNN) to a canonical category_id. Pair with `category_id` if you have a deterministic id from a prior call.","example":"electronics"},"country":{"type":"string","enum":["us","ca"],"default":"us","description":"Country (us or ca)","example":"us"},"retailer":{"type":"string","enum":["amazon","walmart","costco","homedepot","nordstrom","ikea"],"description":"Filter to a specific retailer","example":"amazon"},"min_discount_pct":{"type":"integer","default":10,"description":"Minimum discount percentage (default 10)","example":10},"limit":{"type":"integer","default":20,"maximum":50,"description":"Max results to return (default 20, max 50)","example":20}}},"GetPriceDropAlertInput":{"type":"object","additionalProperties":false,"required":["q"],"properties":{"q":{"type":"string","minLength":1,"description":"Search query (product name, keyword, or category term)","example":"airpods"},"country":{"type":"string","enum":["us","ca"],"default":"us","description":"Country (us or ca)","example":"us"},"retailer":{"type":"string","enum":["amazon","walmart","costco","homedepot","nordstrom","ikea"],"description":"Filter to a specific retailer","example":"amazon"},"lookback_days":{"type":"integer","default":30,"description":"Days to look back for price drops (default 30)","example":30}}},"GetCompetitiveLandscapeInput":{"type":"object","additionalProperties":false,"required":["category"],"properties":{"category":{"type":"string","minLength":1,"description":"Product category (e.g., electronics, grocery, beauty). Fuzzy human-readable input — the resolver maps it through tier 1-4 (id → exact name → trigram → embedding kNN) to a canonical category_id. Pair with `category_id` if you have a deterministic id from a prior call.","example":"electronics"},"country":{"type":"string","enum":["us","ca"],"default":"us","description":"Country (us or ca)","example":"us"},"retailer":{"type":"string","enum":["amazon","walmart","costco","homedepot","nordstrom","ikea"],"description":"Filter to a specific retailer","example":"amazon"},"sort_by":{"type":"string","enum":["price_asc","price_desc","rating","reviews"],"default":"price_asc","description":"Sort order","example":"price_asc"},"limit":{"type":"integer","default":20,"maximum":50,"description":"Max results to return (default 20, max 50)","example":20}}},"TrackBrandInput":{"type":"object","additionalProperties":false,"required":["brand"],"properties":{"brand":{"type":"string","minLength":1,"description":"Brand name (e.g., Sony, Samsung, Nike)","example":"Apple"},"country":{"type":"string","enum":["us","ca"],"default":"us","description":"Country (us or ca)","example":"us"},"from":{"type":"string","format":"date","description":"Start date (ISO 8601, defaults to 30 days ago)","example":"2026-04-01"},"to":{"type":"string","format":"date","description":"End date (ISO 8601, defaults to now)","example":"2026-05-01"}}},"GetPromoIntelligenceInput":{"type":"object","additionalProperties":false,"required":["category"],"properties":{"category":{"type":"string","minLength":1,"description":"Product category (e.g., electronics, grocery, beauty). Fuzzy human-readable input — the resolver maps it through tier 1-4 (id → exact name → trigram → embedding kNN) to a canonical category_id. Pair with `category_id` if you have a deterministic id from a prior call.","example":"electronics"},"country":{"type":"string","enum":["us","ca"],"default":"us","description":"Country (us or ca)","example":"us"},"brand":{"type":"string","minLength":1,"description":"Optional brand filter — limit aggregation to products of this brand (case-insensitive)","example":"Apple"},"aggregate_by":{"type":"string","enum":["brand","retailer"],"default":"brand","description":"Group-by dimension. `brand` (default) ranks brands within the category. `retailer` ranks retailers — pair with `brand` to answer 'which retailers run the deepest promos on Brand X'.","example":"retailer"},"from":{"type":"string","format":"date","description":"Start date (ISO 8601, defaults to 30 days ago)","example":"2026-04-01"},"to":{"type":"string","format":"date","description":"End date (ISO 8601, defaults to now)","example":"2026-05-01"}}},"GetShareOfShelfInput":{"type":"object","additionalProperties":false,"required":["category"],"properties":{"category":{"type":"string","minLength":1,"description":"Product category (e.g., electronics, grocery, beauty). Fuzzy human-readable input — the resolver maps it through tier 1-4 (id → exact name → trigram → embedding kNN) to a canonical category_id. Pair with `category_id` if you have a deterministic id from a prior call.","example":"electronics"},"category_id":{"type":"integer","minimum":1,"description":"Deterministic category id. When set, bypasses the fuzzy resolver cascade and uses tier 1 (id lookup) directly. Agents that learned a canonical id from a prior call's `resolved.category_id` should pin it here for round-trip stability.","example":1},"country":{"type":"string","enum":["us","ca"],"default":"us","description":"Country (us or ca)","example":"us"}}},"GetPricePositioningInput":{"type":"object","additionalProperties":false,"required":["brand"],"properties":{"brand":{"type":"string","minLength":1,"description":"Brand name (e.g., Sony, Samsung, Nike)","example":"Apple"},"country":{"type":"string","enum":["us","ca"],"default":"us","description":"Country (us or ca)","example":"us"},"category":{"type":"string","minLength":1,"description":"Product category (e.g., electronics, grocery, beauty). Fuzzy human-readable input — the resolver maps it through tier 1-4 (id → exact name → trigram → embedding kNN) to a canonical category_id. Pair with `category_id` if you have a deterministic id from a prior call.","example":"electronics"}}},"GetInflationInput":{"type":"object","additionalProperties":false,"properties":{"category":{"type":"string","minLength":1,"description":"Product category (e.g., electronics, grocery, beauty). Fuzzy human-readable input — the resolver maps it through tier 1-4 (id → exact name → trigram → embedding kNN) to a canonical category_id. Pair with `category_id` if you have a deterministic id from a prior call.","example":"electronics"},"category_id":{"type":"integer","minimum":1,"description":"Deterministic category id. When set, bypasses the fuzzy resolver cascade and uses tier 1 (id lookup) directly. Agents that learned a canonical id from a prior call's `resolved.category_id` should pin it here for round-trip stability.","example":1},"department":{"type":"string","minLength":1,"description":"Coarse depth-1 BrowseNodes department label (e.g., 'Electronics', 'Grocery', 'Toys & Games'). Exact-match, case-sensitive Title Case. Optional alongside `category`; either parameter alone or both together are accepted. Use this for stable cross-agent queries where the leaf-level category is too noisy.","example":"Electronics"},"country":{"type":"string","enum":["us","ca"],"default":"us","description":"Country (us or ca)","example":"us"},"from":{"type":"string","format":"date","description":"Start date (ISO 8601, defaults to 30 days ago)","example":"2026-04-01"},"to":{"type":"string","format":"date","description":"End date (ISO 8601, defaults to now)","example":"2026-05-01"},"granularity":{"type":"string","enum":["daily","weekly","monthly"],"default":"weekly","description":"Time granularity for the series","example":"weekly"}}},"GetPriceDispersionInput":{"type":"object","additionalProperties":false,"properties":{"category":{"type":"string","minLength":1,"description":"Product category (e.g., electronics, grocery, beauty). Fuzzy human-readable input — the resolver maps it through tier 1-4 (id → exact name → trigram → embedding kNN) to a canonical category_id. Pair with `category_id` if you have a deterministic id from a prior call.","example":"electronics"},"category_id":{"type":"integer","minimum":1,"description":"Deterministic category id. When set, bypasses the fuzzy resolver cascade and uses tier 1 (id lookup) directly. Agents that learned a canonical id from a prior call's `resolved.category_id` should pin it here for round-trip stability.","example":1},"department":{"type":"string","minLength":1,"description":"Coarse depth-1 BrowseNodes department label (e.g., 'Electronics', 'Grocery', 'Toys & Games'). Exact-match, case-sensitive Title Case. Optional alongside `category`; either parameter alone or both together are accepted. Use this for stable cross-agent queries where the leaf-level category is too noisy.","example":"Electronics"},"country":{"type":"string","enum":["us","ca"],"default":"us","description":"Country (us or ca)","example":"us"}}},"GetRetailerIndexInput":{"type":"object","additionalProperties":false,"required":["retailer"],"properties":{"retailer":{"type":"string","description":"Retailer name (e.g., amazon, walmart)","example":"amazon"},"country":{"type":"string","enum":["us","ca"],"default":"us","description":"Country (us or ca)","example":"us"},"category":{"type":"string","minLength":1,"description":"Product category (e.g., electronics, grocery, beauty). Fuzzy human-readable input — the resolver maps it through tier 1-4 (id → exact name → trigram → embedding kNN) to a canonical category_id. Pair with `category_id` if you have a deterministic id from a prior call.","example":"electronics"},"category_id":{"type":"integer","minimum":1,"description":"Deterministic category id. When set, bypasses the fuzzy resolver cascade and uses tier 1 (id lookup) directly. Agents that learned a canonical id from a prior call's `resolved.category_id` should pin it here for round-trip stability.","example":1},"department":{"type":"string","minLength":1,"description":"Coarse depth-1 BrowseNodes department label (e.g., 'Electronics', 'Grocery', 'Toys & Games'). Exact-match, case-sensitive Title Case. Optional alongside `category`; either parameter alone or both together are accepted. Use this for stable cross-agent queries where the leaf-level category is too noisy.","example":"Electronics"},"from":{"type":"string","format":"date","description":"Start date (ISO 8601, defaults to 30 days ago)","example":"2026-04-01"},"to":{"type":"string","format":"date","description":"End date (ISO 8601, defaults to now)","example":"2026-05-01"}}},"GetCategorySummaryInput":{"type":"object","additionalProperties":false,"properties":{"category":{"type":"string","minLength":1,"description":"Product category (e.g., electronics, grocery, beauty). Fuzzy human-readable input — the resolver maps it through tier 1-4 (id → exact name → trigram → embedding kNN) to a canonical category_id. Pair with `category_id` if you have a deterministic id from a prior call.","example":"electronics"},"category_id":{"type":"integer","minimum":1,"description":"Deterministic category id. When set, bypasses the fuzzy resolver cascade and uses tier 1 (id lookup) directly. Agents that learned a canonical id from a prior call's `resolved.category_id` should pin it here for round-trip stability.","example":1},"department":{"type":"string","minLength":1,"description":"Coarse depth-1 BrowseNodes department label (e.g., 'Electronics', 'Grocery', 'Toys & Games'). Exact-match, case-sensitive Title Case. Optional alongside `category`; either parameter alone or both together are accepted. Use this for stable cross-agent queries where the leaf-level category is too noisy.","example":"Electronics"},"country":{"type":"string","enum":["us","ca"],"default":"us","description":"Country (us or ca)","example":"us"}}}}}}