{"openapi":"3.1.0","servers":[{"url":"https://api.syntalic.com"}],"info":{"title":"Syntalic — Data Analytics for Agentic Commerce ","version":"1.0.0","description":"Competitive pricing data across US and Canadian e-commerce retailers (Amazon, Walmart, Target, Best Buy, Home Depot, 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.\n\nMarketing and analyst responses carry a `meta` block (served_from, freshness_seconds, schema_version) for staleness budgeting and a `resolved` block describing how the category input was matched against the taxonomy. Every response also sends an X-Data-Freshness-Hours header.\n\n**Free pre-payment rejection:** requests that cannot be served are rejected BEFORE any payment challenge — invalid params (400 INVALID_PARAMS), retailers that are not serving-eligible (404 RETAILER_NOT_SERVING_ELIGIBLE, with the catalog quality status and the serving_eligible_retailers list in error.details), and shopper queries that resolve to nothing in the catalog (404 NO_RESULTS). You only pay when the API can actually execute your query. Retailer values are case-insensitive (amazon == Amazon)."},"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/public/stats":{"get":{"operationId":"getPublicStats","summary":"Catalog coverage and freshness stats","description":"Zero-cost aggregate discovery endpoint with catalog coverage, category tree counts, retailer count, and latest priced-data timestamp.","tags":["Public"],"responses":{"200":{"description":"Public catalog stats","content":{"application/json":{"schema":{"type":"object","properties":{"products":{"type":"object","properties":{"unique":{"type":"integer"},"listings":{"type":"integer"}}},"categories":{"type":"object","properties":{"total":{"type":"integer"},"leaves":{"type":"integer"},"max_depth":{"type":"integer"}}},"retailers":{"type":"object","properties":{"total":{"type":"integer"}}},"last_updated":{"type":"string","format":"date-time","nullable":true}}}}}},"500":{"description":"Public discovery error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":true}},"additionalProperties":true}}}}}}}}},"/v1/public/categories":{"get":{"operationId":"listPublicCategories","summary":"Browse public category taxonomy","description":"Zero-cost aggregate category discovery endpoint. Returns category path nodes and rolled-up product counts; row-level product data remains on paid endpoints.","tags":["Public"],"parameters":[{"name":"parent_path","in":"query","required":false,"schema":{"type":"string","minLength":1},"description":"Optional category path whose descendants should be listed","example":"electronics"},{"name":"depth","in":"query","required":false,"schema":{"type":"integer","default":1,"minimum":1,"maximum":3},"description":"Maximum depth below parent_path (default 1, max 3)","example":1},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","default":200,"minimum":1,"maximum":500},"description":"Max results to return (default 200, min 1, max 500)","example":200},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","default":0,"minimum":0},"description":"Pagination offset","example":0}],"responses":{"200":{"description":"Public categories","content":{"application/json":{"schema":{"type":"object","properties":{"items":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"path":{"type":"string"},"depth":{"type":"integer"},"parent_path":{"type":"string","nullable":true},"product_count":{"type":"integer"}}}},"total":{"type":"integer"},"limit":{"type":"integer"},"offset":{"type":"integer"}}}}}},"500":{"description":"Public discovery error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":true}},"additionalProperties":true}}}}}}},"x-input-schema":{"type":"object","additionalProperties":false,"properties":{"parent_path":{"type":"string","minLength":1,"description":"Optional category path whose descendants should be listed","example":"electronics"},"depth":{"type":"integer","default":1,"minimum":1,"maximum":3,"description":"Maximum depth below parent_path (default 1, max 3)","example":1},"limit":{"type":"integer","default":200,"minimum":1,"maximum":500,"description":"Max results to return (default 200, min 1, max 500)","example":200},"offset":{"type":"integer","default":0,"minimum":0,"description":"Pagination offset","example":0}}}}},"/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 retailers in US and Canada. Cross-retailer comparison is entity-matched (barcode-anchored resolution links the same physical product across platforms). Returns the cheapest option plus other retailer prices for comparison. Every price row is labeled match_type: 'entity' (verified same product) or 'title' (text match — may be a variant on broad queries); pass strict=true to restrict the comparison to entity-verified rows only. Comparison rows carry observed_at so mixed-vintage prices are distinguishable.","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":259200,"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},"x-required-any-of":[["q"],["product_uid"],["entity_uid"]],"parameters":[{"name":"q","in":"query","required":false,"schema":{"type":"string","minLength":1},"description":"Search query (product name, keyword, or brand + model). Required unless `product_uid` or `entity_uid` is supplied.","example":"airpods"},{"name":"product_uid","in":"query","required":false,"schema":{"type":"string","minLength":1},"description":"Stable product identifier returned by a prior Syntalic shopper response. When supplied, the endpoint should pin to this listing instead of re-resolving free text.","example":"p_airpods_deal"},{"name":"entity_uid","in":"query","required":false,"schema":{"type":"string","minLength":1},"description":"Stable cross-retailer entity identifier returned by a prior Syntalic shopper response. When supplied, the endpoint should resolve within the same physical-product entity.","example":"e_airpods_deal"},{"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","target","bestbuy","homedepot","costco","ikea","samsclub","cvs","dillards"]},"description":"Filter to a specific retailer platform (long-tail specialty stores are also present; any platform key is accepted)","example":"amazon"},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","default":10,"minimum":1,"maximum":50},"description":"Max results to return (default 10, min 1, max 50)","example":10},{"name":"strict","in":"query","required":false,"schema":{"type":"boolean","default":false},"description":"When true, restrict the comparison to entity-verified listings of the matched product (match_type 'entity' only). Default false also includes title-match rows — useful for broad queries, but may mix product variants.","example":false}],"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_uid":{"type":"string"},"entity_uid":{"type":"string"},"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","nullable":true},"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."},"match_type":{"type":"string","enum":["entity","title"],"description":"'entity' = verified same physical product via cross-platform entity resolution; 'title' = text match (may be a variant on broad queries)."},"scraped_at":{"type":"string","format":"date-time"}}},"other_prices":{"type":"array","items":{"type":"object","properties":{"product_uid":{"type":"string"},"entity_uid":{"type":"string"},"retailer":{"type":"string"},"product_name":{"type":"string"},"price":{"type":"number"},"in_stock":{"type":"boolean","nullable":true},"condition":{"type":"string","enum":["new","refurbished","used","unknown"]},"match_type":{"type":"string","enum":["entity","title"]},"observed_at":{"type":"string","format":"date-time","description":"When this row's price was observed — rows in one comparison can differ in vintage."}}}},"meta":{"type":"object","properties":{"served_from":{"type":"string"},"freshness_seconds":{"type":"number"},"schema_version":{"type":"string"},"computed_at":{"type":"string","format":"date-time"},"price_observed_at_min":{"type":"string","format":"date-time","nullable":true},"price_observed_at_max":{"type":"string","format":"date-time","nullable":true}},"additionalProperties":true}}}}}},"400":{"description":"Invalid query parameters or unsupported enum values. Rejected by preflight BEFORE the payment challenge — no payment is requested or charged for malformed requests.","content":{"application/problem+json":{"schema":{"type":"object","required":["type","title","status"],"properties":{"type":{"type":"string","format":"uri-reference"},"title":{"type":"string","example":"Bad Request"},"status":{"type":"integer","const":400},"detail":{"type":"string"},"instance":{"type":"string"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":true}},"additionalProperties":true}},"additionalProperties":true}}}},"402":{"description":"Payment challenge required before executing paid work","content":{"application/problem+json":{"schema":{"type":"object","required":["type","title","status"],"properties":{"type":{"type":"string","format":"uri-reference"},"title":{"type":"string","example":"Payment Required"},"status":{"type":"integer","const":402},"detail":{"type":"string"},"instance":{"type":"string"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":true}},"additionalProperties":true}},"additionalProperties":true}}}},"404":{"description":"No matching result. error.code distinguishes the cases: NO_RESULTS (the query resolves to nothing in the catalog) or RETAILER_NOT_SERVING_ELIGIBLE (the requested retailer exists but is not serving-eligible — error.details carries its catalog quality_status and the serving_eligible_retailers list to retry against). Structurally-unservable requests are rejected by preflight before any payment challenge.","content":{"application/problem+json":{"schema":{"type":"object","required":["type","title","status"],"properties":{"type":{"type":"string","format":"uri-reference"},"title":{"type":"string","example":"Not Found"},"status":{"type":"integer","const":404},"detail":{"type":"string"},"instance":{"type":"string"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":true}},"additionalProperties":true}},"additionalProperties":true}}}},"429":{"description":"Rate limit exceeded","content":{"application/problem+json":{"schema":{"type":"object","required":["type","title","status"],"properties":{"type":{"type":"string","format":"uri-reference"},"title":{"type":"string","example":"Too Many Requests"},"status":{"type":"integer","const":429},"detail":{"type":"string"},"instance":{"type":"string"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":true}},"additionalProperties":true}},"additionalProperties":true}}}},"500":{"description":"Unexpected server error","content":{"application/problem+json":{"schema":{"type":"object","required":["type","title","status"],"properties":{"type":{"type":"string","format":"uri-reference"},"title":{"type":"string","example":"Internal Server Error"},"status":{"type":"integer","const":500},"detail":{"type":"string"},"instance":{"type":"string"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":true}},"additionalProperties":true}},"additionalProperties":true}}}}},"x-input-schema":{"type":"object","additionalProperties":false,"properties":{"q":{"type":"string","minLength":1,"description":"Search query (product name, keyword, or brand + model). Required unless `product_uid` or `entity_uid` is supplied.","example":"airpods"},"product_uid":{"type":"string","minLength":1,"description":"Stable product identifier returned by a prior Syntalic shopper response. When supplied, the endpoint should pin to this listing instead of re-resolving free text.","example":"p_airpods_deal"},"entity_uid":{"type":"string","minLength":1,"description":"Stable cross-retailer entity identifier returned by a prior Syntalic shopper response. When supplied, the endpoint should resolve within the same physical-product entity.","example":"e_airpods_deal"},"country":{"type":"string","enum":["us","ca"],"default":"us","description":"Country (us or ca)","example":"us"},"retailer":{"type":"string","enum":["amazon","walmart","target","bestbuy","homedepot","costco","ikea","samsclub","cvs","dillards"],"description":"Filter to a specific retailer platform (long-tail specialty stores are also present; any platform key is accepted)","example":"amazon"},"limit":{"type":"integer","default":10,"minimum":1,"maximum":50,"description":"Max results to return (default 10, min 1, max 50)","example":10},"strict":{"type":"boolean","default":false,"description":"When true, restrict the comparison to entity-verified listings of the matched product (match_type 'entity' only). Default false also includes title-match rows — useful for broad queries, but may mix product variants.","example":false}},"anyOf":[{"required":["q"]},{"required":["product_uid"]},{"required":["entity_uid"]}]}}},"/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":259200,"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},"x-required-any-of":[["q"],["product_uid"],["entity_uid"]],"parameters":[{"name":"q","in":"query","required":false,"schema":{"type":"string","minLength":1},"description":"Search query (product name, keyword, or brand + model). Required unless `product_uid` or `entity_uid` is supplied.","example":"airpods"},{"name":"product_uid","in":"query","required":false,"schema":{"type":"string","minLength":1},"description":"Stable product identifier returned by a prior Syntalic shopper response. When supplied, the endpoint should pin to this listing instead of re-resolving free text.","example":"p_airpods_deal"},{"name":"entity_uid","in":"query","required":false,"schema":{"type":"string","minLength":1},"description":"Stable cross-retailer entity identifier returned by a prior Syntalic shopper response. When supplied, the endpoint should resolve within the same physical-product entity.","example":"e_airpods_deal"},{"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","target","bestbuy","homedepot","costco","ikea","samsclub","cvs","dillards"]},"description":"Filter to a specific retailer platform (long-tail specialty stores are also present; any platform key is accepted)","example":"amazon"},{"name":"time_window","in":"query","required":false,"schema":{"type":"string","enum":["last_30_days","last_60_days","last_90_days","month_to_date","previous_month","month_over_month","quarter_to_date","custom"]},"description":"Historical window preset. Explicit `from`/`to` takes precedence and is reported as `custom`; `time_window=custom` requires both `from` and `to`. Date-only ranges use UTC calendar boundaries with inclusive `from` and exclusive `to`.","example":"last_60_days"},{"name":"from","in":"query","required":false,"schema":{"type":"string","format":"date"},"description":"Start date (ISO 8601, defaults to 30 days ago)","example":"2026-05-01"},{"name":"to","in":"query","required":false,"schema":{"type":"string","format":"date"},"description":"End date (ISO 8601, defaults to now)","example":"2026-06-01"}],"responses":{"200":{"description":"Price history","content":{"application/json":{"schema":{"type":"object","properties":{"query":{"type":"string"},"country":{"type":"string"},"currency":{"type":"string"},"product_uid":{"type":"string"},"entity_uid":{"type":"string"},"product_name":{"type":"string"},"retailer":{"type":"string"},"condition":{"type":"string"},"current_price":{"type":"number"},"period_low":{"type":"number"},"period_high":{"type":"number"},"period_avg":{"type":"number"},"is_good_deal":{"type":"boolean","nullable":true},"trend":{"type":"string","nullable":true},"insufficient_history":{"type":"boolean"},"observation_count":{"type":"integer"},"scope":{"type":"string","enum":["entity","listing"],"nullable":true},"member_count":{"type":"integer","nullable":true},"window":{"type":"object","properties":{"preset":{"type":"string"},"from":{"type":"string","format":"date"},"to":{"type":"string","format":"date"},"granularity":{"type":"string","nullable":true},"comparison_from":{"type":"string","format":"date","nullable":true},"comparison_to":{"type":"string","format":"date","nullable":true},"timezone":{"type":"string","example":"UTC"}},"additionalProperties":true},"observations":{"type":"array","items":{"type":"object","properties":{"date":{"type":"string","format":"date"},"price":{"type":"number"}}}},"meta":{"type":"object","properties":{"served_from":{"type":"string"},"freshness_seconds":{"type":"number"},"schema_version":{"type":"string"},"computed_at":{"type":"string","format":"date-time"},"price_observed_at_min":{"type":"string","format":"date-time","nullable":true},"price_observed_at_max":{"type":"string","format":"date-time","nullable":true}},"additionalProperties":true}}}}}},"400":{"description":"Invalid query parameters or unsupported enum values. Rejected by preflight BEFORE the payment challenge — no payment is requested or charged for malformed requests.","content":{"application/problem+json":{"schema":{"type":"object","required":["type","title","status"],"properties":{"type":{"type":"string","format":"uri-reference"},"title":{"type":"string","example":"Bad Request"},"status":{"type":"integer","const":400},"detail":{"type":"string"},"instance":{"type":"string"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":true}},"additionalProperties":true}},"additionalProperties":true}}}},"402":{"description":"Payment challenge required before executing paid work","content":{"application/problem+json":{"schema":{"type":"object","required":["type","title","status"],"properties":{"type":{"type":"string","format":"uri-reference"},"title":{"type":"string","example":"Payment Required"},"status":{"type":"integer","const":402},"detail":{"type":"string"},"instance":{"type":"string"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":true}},"additionalProperties":true}},"additionalProperties":true}}}},"404":{"description":"No matching result. error.code distinguishes the cases: NO_RESULTS (the query resolves to nothing in the catalog) or RETAILER_NOT_SERVING_ELIGIBLE (the requested retailer exists but is not serving-eligible — error.details carries its catalog quality_status and the serving_eligible_retailers list to retry against). Structurally-unservable requests are rejected by preflight before any payment challenge.","content":{"application/problem+json":{"schema":{"type":"object","required":["type","title","status"],"properties":{"type":{"type":"string","format":"uri-reference"},"title":{"type":"string","example":"Not Found"},"status":{"type":"integer","const":404},"detail":{"type":"string"},"instance":{"type":"string"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":true}},"additionalProperties":true}},"additionalProperties":true}}}},"429":{"description":"Rate limit exceeded","content":{"application/problem+json":{"schema":{"type":"object","required":["type","title","status"],"properties":{"type":{"type":"string","format":"uri-reference"},"title":{"type":"string","example":"Too Many Requests"},"status":{"type":"integer","const":429},"detail":{"type":"string"},"instance":{"type":"string"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":true}},"additionalProperties":true}},"additionalProperties":true}}}},"500":{"description":"Unexpected server error","content":{"application/problem+json":{"schema":{"type":"object","required":["type","title","status"],"properties":{"type":{"type":"string","format":"uri-reference"},"title":{"type":"string","example":"Internal Server Error"},"status":{"type":"integer","const":500},"detail":{"type":"string"},"instance":{"type":"string"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":true}},"additionalProperties":true}},"additionalProperties":true}}}}},"x-input-schema":{"type":"object","additionalProperties":false,"properties":{"q":{"type":"string","minLength":1,"description":"Search query (product name, keyword, or brand + model). Required unless `product_uid` or `entity_uid` is supplied.","example":"airpods"},"product_uid":{"type":"string","minLength":1,"description":"Stable product identifier returned by a prior Syntalic shopper response. When supplied, the endpoint should pin to this listing instead of re-resolving free text.","example":"p_airpods_deal"},"entity_uid":{"type":"string","minLength":1,"description":"Stable cross-retailer entity identifier returned by a prior Syntalic shopper response. When supplied, the endpoint should resolve within the same physical-product entity.","example":"e_airpods_deal"},"country":{"type":"string","enum":["us","ca"],"default":"us","description":"Country (us or ca)","example":"us"},"retailer":{"type":"string","enum":["amazon","walmart","target","bestbuy","homedepot","costco","ikea","samsclub","cvs","dillards"],"description":"Filter to a specific retailer platform (long-tail specialty stores are also present; any platform key is accepted)","example":"amazon"},"time_window":{"type":"string","enum":["last_30_days","last_60_days","last_90_days","month_to_date","previous_month","month_over_month","quarter_to_date","custom"],"description":"Historical window preset. Explicit `from`/`to` takes precedence and is reported as `custom`; `time_window=custom` requires both `from` and `to`. Date-only ranges use UTC calendar boundaries with inclusive `from` and exclusive `to`.","example":"last_60_days"},"from":{"type":"string","format":"date","description":"Start date (ISO 8601, defaults to 30 days ago)","example":"2026-05-01"},"to":{"type":"string","format":"date","description":"End date (ISO 8601, defaults to now)","example":"2026-06-01"}},"anyOf":[{"required":["q"]},{"required":["product_uid"]},{"required":["entity_uid"]}]}}},"/v1/shopper/deal-finder":{"get":{"operationId":"findDeals","summary":"Find discounted products in a category","description":"Discover discounted in-stock products in a category above a minimum discount threshold (discount = current price below the retailer's list price). Quality-gated: unbranded listings, sub-$5 items, and discounts above 70% (the inflated-list-price spam signature) are excluded. Ranked by discount depth weighted by log(price), so meaningful discounts on real products outrank deep cuts on trinkets. Each deal carries observed_at (when its price was seen).","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":259200,"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. Accepts a human-readable name (e.g. 'electronics', 'beauty') or a taxonomy slug path (e.g. 'electronics/headphones'); matched against the catalog's category tree (exact node, subtree, or path substring).","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","target","bestbuy","homedepot","costco","ikea","samsclub","cvs","dillards"]},"description":"Filter to a specific retailer platform (long-tail specialty stores are also present; any platform key is accepted)","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,"minimum":1,"maximum":50},"description":"Max results to return (default 20, min 1, max 50)","example":20}],"responses":{"200":{"description":"Deals found","content":{"application/json":{"schema":{"type":"object","properties":{"category":{"type":"string"},"country":{"type":"string"},"currency":{"type":"string"},"deals":{"type":"array","items":{"type":"object","properties":{"product_uid":{"type":"string"},"entity_uid":{"type":"string"},"product_id":{"type":"string"},"product_name":{"type":"string"},"brand":{"type":"string","nullable":true},"retailer":{"type":"string"},"price":{"type":"number"},"list_price":{"type":"number","nullable":true},"discount_pct":{"type":"number","nullable":true},"star_rating":{"type":"number","nullable":true},"review_count":{"type":"integer","nullable":true},"promo_flag":{"type":"boolean"},"in_stock":{"type":"boolean","nullable":true},"condition":{"type":"string"},"match_type":{"type":"string"},"observed_at":{"type":"string","format":"date-time"},"scraped_at":{"type":"string","format":"date-time"}},"additionalProperties":true}},"total_deals_found":{"type":"integer"},"meta":{"type":"object","properties":{"served_from":{"type":"string"},"freshness_seconds":{"type":"number"},"schema_version":{"type":"string"},"computed_at":{"type":"string","format":"date-time"},"price_observed_at_min":{"type":"string","format":"date-time","nullable":true},"price_observed_at_max":{"type":"string","format":"date-time","nullable":true}},"additionalProperties":true}}}}}},"400":{"description":"Invalid query parameters or unsupported enum values. Rejected by preflight BEFORE the payment challenge — no payment is requested or charged for malformed requests.","content":{"application/problem+json":{"schema":{"type":"object","required":["type","title","status"],"properties":{"type":{"type":"string","format":"uri-reference"},"title":{"type":"string","example":"Bad Request"},"status":{"type":"integer","const":400},"detail":{"type":"string"},"instance":{"type":"string"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":true}},"additionalProperties":true}},"additionalProperties":true}}}},"402":{"description":"Payment challenge required before executing paid work","content":{"application/problem+json":{"schema":{"type":"object","required":["type","title","status"],"properties":{"type":{"type":"string","format":"uri-reference"},"title":{"type":"string","example":"Payment Required"},"status":{"type":"integer","const":402},"detail":{"type":"string"},"instance":{"type":"string"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":true}},"additionalProperties":true}},"additionalProperties":true}}}},"404":{"description":"No matching result. error.code distinguishes the cases: NO_RESULTS (the query resolves to nothing in the catalog) or RETAILER_NOT_SERVING_ELIGIBLE (the requested retailer exists but is not serving-eligible — error.details carries its catalog quality_status and the serving_eligible_retailers list to retry against). Structurally-unservable requests are rejected by preflight before any payment challenge.","content":{"application/problem+json":{"schema":{"type":"object","required":["type","title","status"],"properties":{"type":{"type":"string","format":"uri-reference"},"title":{"type":"string","example":"Not Found"},"status":{"type":"integer","const":404},"detail":{"type":"string"},"instance":{"type":"string"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":true}},"additionalProperties":true}},"additionalProperties":true}}}},"429":{"description":"Rate limit exceeded","content":{"application/problem+json":{"schema":{"type":"object","required":["type","title","status"],"properties":{"type":{"type":"string","format":"uri-reference"},"title":{"type":"string","example":"Too Many Requests"},"status":{"type":"integer","const":429},"detail":{"type":"string"},"instance":{"type":"string"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":true}},"additionalProperties":true}},"additionalProperties":true}}}},"500":{"description":"Unexpected server error","content":{"application/problem+json":{"schema":{"type":"object","required":["type","title","status"],"properties":{"type":{"type":"string","format":"uri-reference"},"title":{"type":"string","example":"Internal Server Error"},"status":{"type":"integer","const":500},"detail":{"type":"string"},"instance":{"type":"string"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":true}},"additionalProperties":true}},"additionalProperties":true}}}}},"x-input-schema":{"type":"object","additionalProperties":false,"required":["category"],"properties":{"category":{"type":"string","minLength":1,"description":"Product category. Accepts a human-readable name (e.g. 'electronics', 'beauty') or a taxonomy slug path (e.g. 'electronics/headphones'); matched against the catalog's category tree (exact node, subtree, or path substring).","example":"electronics"},"country":{"type":"string","enum":["us","ca"],"default":"us","description":"Country (us or ca)","example":"us"},"retailer":{"type":"string","enum":["amazon","walmart","target","bestbuy","homedepot","costco","ikea","samsclub","cvs","dillards"],"description":"Filter to a specific retailer platform (long-tail specialty stores are also present; any platform key is accepted)","example":"amazon"},"min_discount_pct":{"type":"integer","default":10,"description":"Minimum discount percentage (default 10)","example":10},"limit":{"type":"integer","default":20,"minimum":1,"maximum":50,"description":"Max results to return (default 20, min 1, 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":259200,"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},"x-required-any-of":[["q"],["product_uid"],["entity_uid"]],"parameters":[{"name":"q","in":"query","required":false,"schema":{"type":"string","minLength":1},"description":"Search query (product name, keyword, or brand + model). Required unless `product_uid` or `entity_uid` is supplied.","example":"airpods"},{"name":"product_uid","in":"query","required":false,"schema":{"type":"string","minLength":1},"description":"Stable product identifier returned by a prior Syntalic shopper response. When supplied, the endpoint should pin to this listing instead of re-resolving free text.","example":"p_airpods_deal"},{"name":"entity_uid","in":"query","required":false,"schema":{"type":"string","minLength":1},"description":"Stable cross-retailer entity identifier returned by a prior Syntalic shopper response. When supplied, the endpoint should resolve within the same physical-product entity.","example":"e_airpods_deal"},{"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","target","bestbuy","homedepot","costco","ikea","samsclub","cvs","dillards"]},"description":"Filter to a specific retailer platform (long-tail specialty stores are also present; any platform key is accepted)","example":"amazon"},{"name":"time_window","in":"query","required":false,"schema":{"type":"string","enum":["last_30_days","last_60_days","last_90_days","month_to_date","previous_month","month_over_month","quarter_to_date","custom"]},"description":"Historical window preset. Explicit `from`/`to` takes precedence and is reported as `custom`; `time_window=custom` requires both `from` and `to`. Date-only ranges use UTC calendar boundaries with inclusive `from` and exclusive `to`.","example":"last_60_days"},{"name":"lookback_days","in":"query","required":false,"schema":{"type":"integer","default":30,"minimum":1},"description":"Days to look back for price drops (default 30). Backwards-compatible alias for matching `last_N_days` windows.","example":30}],"responses":{"200":{"description":"Price drop alert","content":{"application/json":{"schema":{"type":"object","properties":{"query":{"type":"string"},"country":{"type":"string"},"currency":{"type":"string"},"product_uid":{"type":"string"},"entity_uid":{"type":"string"},"product_name":{"type":"string"},"retailer":{"type":"string"},"condition":{"type":"string"},"current_price":{"type":"number"},"avg_price_last_30d":{"type":"number"},"price_vs_avg_pct":{"type":"number"},"is_price_drop":{"type":"boolean"},"lowest_seen":{"type":"number"},"lowest_seen_date":{"type":"string","format":"date"},"insufficient_history":{"type":"boolean"},"observation_count":{"type":"integer"},"scope":{"type":"string","enum":["entity","listing"],"nullable":true},"member_count":{"type":"integer","nullable":true},"window":{"type":"object","properties":{"preset":{"type":"string"},"from":{"type":"string","format":"date"},"to":{"type":"string","format":"date"},"granularity":{"type":"string","nullable":true},"comparison_from":{"type":"string","format":"date","nullable":true},"comparison_to":{"type":"string","format":"date","nullable":true},"timezone":{"type":"string","example":"UTC"}},"additionalProperties":true},"meta":{"type":"object","properties":{"served_from":{"type":"string"},"freshness_seconds":{"type":"number"},"schema_version":{"type":"string"},"computed_at":{"type":"string","format":"date-time"},"price_observed_at_min":{"type":"string","format":"date-time","nullable":true},"price_observed_at_max":{"type":"string","format":"date-time","nullable":true}},"additionalProperties":true}}}}}},"400":{"description":"Invalid query parameters or unsupported enum values. Rejected by preflight BEFORE the payment challenge — no payment is requested or charged for malformed requests.","content":{"application/problem+json":{"schema":{"type":"object","required":["type","title","status"],"properties":{"type":{"type":"string","format":"uri-reference"},"title":{"type":"string","example":"Bad Request"},"status":{"type":"integer","const":400},"detail":{"type":"string"},"instance":{"type":"string"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":true}},"additionalProperties":true}},"additionalProperties":true}}}},"402":{"description":"Payment challenge required before executing paid work","content":{"application/problem+json":{"schema":{"type":"object","required":["type","title","status"],"properties":{"type":{"type":"string","format":"uri-reference"},"title":{"type":"string","example":"Payment Required"},"status":{"type":"integer","const":402},"detail":{"type":"string"},"instance":{"type":"string"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":true}},"additionalProperties":true}},"additionalProperties":true}}}},"404":{"description":"No matching result. error.code distinguishes the cases: NO_RESULTS (the query resolves to nothing in the catalog) or RETAILER_NOT_SERVING_ELIGIBLE (the requested retailer exists but is not serving-eligible — error.details carries its catalog quality_status and the serving_eligible_retailers list to retry against). Structurally-unservable requests are rejected by preflight before any payment challenge.","content":{"application/problem+json":{"schema":{"type":"object","required":["type","title","status"],"properties":{"type":{"type":"string","format":"uri-reference"},"title":{"type":"string","example":"Not Found"},"status":{"type":"integer","const":404},"detail":{"type":"string"},"instance":{"type":"string"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":true}},"additionalProperties":true}},"additionalProperties":true}}}},"429":{"description":"Rate limit exceeded","content":{"application/problem+json":{"schema":{"type":"object","required":["type","title","status"],"properties":{"type":{"type":"string","format":"uri-reference"},"title":{"type":"string","example":"Too Many Requests"},"status":{"type":"integer","const":429},"detail":{"type":"string"},"instance":{"type":"string"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":true}},"additionalProperties":true}},"additionalProperties":true}}}},"500":{"description":"Unexpected server error","content":{"application/problem+json":{"schema":{"type":"object","required":["type","title","status"],"properties":{"type":{"type":"string","format":"uri-reference"},"title":{"type":"string","example":"Internal Server Error"},"status":{"type":"integer","const":500},"detail":{"type":"string"},"instance":{"type":"string"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":true}},"additionalProperties":true}},"additionalProperties":true}}}}},"x-input-schema":{"type":"object","additionalProperties":false,"properties":{"q":{"type":"string","minLength":1,"description":"Search query (product name, keyword, or brand + model). Required unless `product_uid` or `entity_uid` is supplied.","example":"airpods"},"product_uid":{"type":"string","minLength":1,"description":"Stable product identifier returned by a prior Syntalic shopper response. When supplied, the endpoint should pin to this listing instead of re-resolving free text.","example":"p_airpods_deal"},"entity_uid":{"type":"string","minLength":1,"description":"Stable cross-retailer entity identifier returned by a prior Syntalic shopper response. When supplied, the endpoint should resolve within the same physical-product entity.","example":"e_airpods_deal"},"country":{"type":"string","enum":["us","ca"],"default":"us","description":"Country (us or ca)","example":"us"},"retailer":{"type":"string","enum":["amazon","walmart","target","bestbuy","homedepot","costco","ikea","samsclub","cvs","dillards"],"description":"Filter to a specific retailer platform (long-tail specialty stores are also present; any platform key is accepted)","example":"amazon"},"time_window":{"type":"string","enum":["last_30_days","last_60_days","last_90_days","month_to_date","previous_month","month_over_month","quarter_to_date","custom"],"description":"Historical window preset. Explicit `from`/`to` takes precedence and is reported as `custom`; `time_window=custom` requires both `from` and `to`. Date-only ranges use UTC calendar boundaries with inclusive `from` and exclusive `to`.","example":"last_60_days"},"lookback_days":{"type":"integer","default":30,"minimum":1,"description":"Days to look back for price drops (default 30). Backwards-compatible alias for matching `last_N_days` windows.","example":30}},"anyOf":[{"required":["q"]},{"required":["product_uid"]},{"required":["entity_uid"]}]}}},"/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/review sorts are accepted for compatibility and fall back to price ordering). Each item carries a condition label (new/refurbished/used) so refurb listings are distinguishable. Offset-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":604800,"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. Accepts a human-readable name (e.g. 'electronics', 'beauty') or a taxonomy slug path (e.g. 'electronics/headphones'); matched against the catalog's category tree (exact node, subtree, or path substring).","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","target","bestbuy","homedepot","costco","ikea","samsclub","cvs","dillards"]},"description":"Filter to a specific retailer platform (long-tail specialty stores are also present; any platform key is accepted)","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 (rating/reviews accepted for compatibility; fall back to price_asc)","example":"price_asc"},{"name":"cursor","in":"query","required":false,"schema":{"type":"integer","minimum":0},"description":"Pagination cursor — pass the previous response's next_cursor","example":0},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","default":20,"minimum":1,"maximum":50},"description":"Max results to return (default 20, min 1, max 50)","example":20}],"responses":{"200":{"description":"Competitive landscape","content":{"application/json":{"schema":{"type":"object","properties":{"category":{"type":"string"},"country":{"type":"string"},"currency":{"type":"string"},"items":{"type":"array","items":{"type":"object","properties":{"product_uid":{"type":"string"},"entity_uid":{"type":"string"},"product_id":{"type":"string"},"product_name":{"type":"string"},"brand":{"type":"string","nullable":true},"retailer":{"type":"string"},"price":{"type":"number"},"list_price":{"type":"number","nullable":true},"discount_pct":{"type":"number","nullable":true},"star_rating":{"type":"number","nullable":true},"review_count":{"type":"integer","nullable":true},"promo_flag":{"type":"boolean"},"in_stock":{"type":"boolean","nullable":true},"condition":{"type":"string"},"match_type":{"type":"string"},"observed_at":{"type":"string","format":"date-time"},"scraped_at":{"type":"string","format":"date-time"}},"additionalProperties":true}},"next_cursor":{"type":"integer","nullable":true},"has_more":{"type":"boolean"},"resolved":{"type":"object","properties":{"input":{"type":"string"},"category_path":{"type":"string","nullable":true},"department":{"type":"string","nullable":true},"match_source":{"type":"string","nullable":true},"match_confidence":{"type":"number","nullable":true},"alternates":{"type":"array","items":{"type":"object","additionalProperties":true}}},"additionalProperties":true},"meta":{"type":"object","properties":{"served_from":{"type":"string"},"freshness_seconds":{"type":"number"},"schema_version":{"type":"string"},"computed_at":{"type":"string","format":"date-time"},"price_observed_at_min":{"type":"string","format":"date-time","nullable":true},"price_observed_at_max":{"type":"string","format":"date-time","nullable":true}},"additionalProperties":true}}}}}},"400":{"description":"Invalid query parameters or unsupported enum values. Rejected by preflight BEFORE the payment challenge — no payment is requested or charged for malformed requests.","content":{"application/problem+json":{"schema":{"type":"object","required":["type","title","status"],"properties":{"type":{"type":"string","format":"uri-reference"},"title":{"type":"string","example":"Bad Request"},"status":{"type":"integer","const":400},"detail":{"type":"string"},"instance":{"type":"string"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":true}},"additionalProperties":true}},"additionalProperties":true}}}},"402":{"description":"Payment challenge required before executing paid work","content":{"application/problem+json":{"schema":{"type":"object","required":["type","title","status"],"properties":{"type":{"type":"string","format":"uri-reference"},"title":{"type":"string","example":"Payment Required"},"status":{"type":"integer","const":402},"detail":{"type":"string"},"instance":{"type":"string"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":true}},"additionalProperties":true}},"additionalProperties":true}}}},"404":{"description":"No matching result. error.code distinguishes the cases: NO_RESULTS (the query resolves to nothing in the catalog) or RETAILER_NOT_SERVING_ELIGIBLE (the requested retailer exists but is not serving-eligible — error.details carries its catalog quality_status and the serving_eligible_retailers list to retry against). Structurally-unservable requests are rejected by preflight before any payment challenge.","content":{"application/problem+json":{"schema":{"type":"object","required":["type","title","status"],"properties":{"type":{"type":"string","format":"uri-reference"},"title":{"type":"string","example":"Not Found"},"status":{"type":"integer","const":404},"detail":{"type":"string"},"instance":{"type":"string"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":true}},"additionalProperties":true}},"additionalProperties":true}}}},"429":{"description":"Rate limit exceeded","content":{"application/problem+json":{"schema":{"type":"object","required":["type","title","status"],"properties":{"type":{"type":"string","format":"uri-reference"},"title":{"type":"string","example":"Too Many Requests"},"status":{"type":"integer","const":429},"detail":{"type":"string"},"instance":{"type":"string"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":true}},"additionalProperties":true}},"additionalProperties":true}}}},"500":{"description":"Unexpected server error","content":{"application/problem+json":{"schema":{"type":"object","required":["type","title","status"],"properties":{"type":{"type":"string","format":"uri-reference"},"title":{"type":"string","example":"Internal Server Error"},"status":{"type":"integer","const":500},"detail":{"type":"string"},"instance":{"type":"string"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":true}},"additionalProperties":true}},"additionalProperties":true}}}}},"x-input-schema":{"type":"object","additionalProperties":false,"required":["category"],"properties":{"category":{"type":"string","minLength":1,"description":"Product category. Accepts a human-readable name (e.g. 'electronics', 'beauty') or a taxonomy slug path (e.g. 'electronics/headphones'); matched against the catalog's category tree (exact node, subtree, or path substring).","example":"electronics"},"country":{"type":"string","enum":["us","ca"],"default":"us","description":"Country (us or ca)","example":"us"},"retailer":{"type":"string","enum":["amazon","walmart","target","bestbuy","homedepot","costco","ikea","samsclub","cvs","dillards"],"description":"Filter to a specific retailer platform (long-tail specialty stores are also present; any platform key is accepted)","example":"amazon"},"sort_by":{"type":"string","enum":["price_asc","price_desc","rating","reviews"],"default":"price_asc","description":"Sort order (rating/reviews accepted for compatibility; fall back to price_asc)","example":"price_asc"},"cursor":{"type":"integer","minimum":0,"description":"Pagination cursor — pass the previous response's next_cursor","example":0},"limit":{"type":"integer","default":20,"minimum":1,"maximum":50,"description":"Max results to return (default 20, min 1, 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. Brand input matches case-insensitively and across normalization variants (jbl == JBL, tplink == TP-Link). Each point reports insufficient_sample when its basket is under sample_threshold products, plus stable_avg_price computed over only the products priced on every day of the series — use stable_avg_price for trend reads; the all-products average moves with basket composition.","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":604800,"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":"retailer","in":"query","required":false,"schema":{"type":"string","enum":["amazon","walmart","target","bestbuy","homedepot","costco","ikea","samsclub","cvs","dillards"]},"description":"Filter to a specific retailer platform (long-tail specialty stores are also present; any platform key is accepted)","example":"amazon"},{"name":"time_window","in":"query","required":false,"schema":{"type":"string","enum":["last_30_days","last_60_days","last_90_days","month_to_date","previous_month","month_over_month","quarter_to_date","custom"]},"description":"Historical window preset. Explicit `from`/`to` takes precedence and is reported as `custom`; `time_window=custom` requires both `from` and `to`. Date-only ranges use UTC calendar boundaries with inclusive `from` and exclusive `to`.","example":"last_60_days"},{"name":"from","in":"query","required":false,"schema":{"type":"string","format":"date"},"description":"Start date (ISO 8601, defaults to 30 days ago)","example":"2026-05-01"},{"name":"to","in":"query","required":false,"schema":{"type":"string","format":"date"},"description":"End date (ISO 8601, defaults to now)","example":"2026-06-01"}],"responses":{"200":{"description":"Brand tracking data","content":{"application/json":{"schema":{"type":"object","properties":{"brand":{"type":"string"},"country":{"type":"string"},"currency":{"type":"string"},"retailer":{"type":"string","nullable":true},"window":{"type":"object","properties":{"preset":{"type":"string"},"from":{"type":"string","format":"date"},"to":{"type":"string","format":"date"},"granularity":{"type":"string","nullable":true},"comparison_from":{"type":"string","format":"date","nullable":true},"comparison_to":{"type":"string","format":"date","nullable":true},"timezone":{"type":"string","example":"UTC"}},"additionalProperties":true},"sample_threshold":{"type":"integer"},"insufficient_sample_points":{"type":"integer"},"insufficient_sample":{"type":"boolean","description":"True when any series point has a basket below sample_threshold."},"stable_basket_size":{"type":"integer","nullable":true,"description":"Products priced in every period of the series (the basis of stable_avg_price). Null for single-point series."},"time_series":{"type":"array","items":{"type":"object","properties":{"date":{"type":"string","format":"date"},"period":{"type":"string"},"avg_price":{"type":"number","nullable":true},"min_price":{"type":"number","nullable":true},"max_price":{"type":"number","nullable":true},"median_price":{"type":"number","nullable":true},"product_count":{"type":"integer"},"observation_count":{"type":"integer"},"change_pct":{"type":"number","nullable":true},"matched_basket_size":{"type":"integer"},"method":{"type":"string","nullable":true},"in_stock_count":{"type":"integer"},"promo_count":{"type":"integer"},"retailer_avg_price":{"type":"number","nullable":true},"category_avg_price":{"type":"number","nullable":true},"price_index":{"type":"number","nullable":true},"stable_avg_price":{"type":"number","nullable":true,"description":"Average over only the stable basket (products priced in EVERY period of the series) — immune to basket-composition shifts. Null when no product spans the whole series."},"insufficient_sample":{"type":"boolean","description":"True when product_count is below sample_threshold — treat the point as anecdote, not trend."},"sample_threshold":{"type":"integer"}},"additionalProperties":true}},"meta":{"type":"object","properties":{"served_from":{"type":"string"},"freshness_seconds":{"type":"number"},"schema_version":{"type":"string"},"computed_at":{"type":"string","format":"date-time"},"price_observed_at_min":{"type":"string","format":"date-time","nullable":true},"price_observed_at_max":{"type":"string","format":"date-time","nullable":true}},"additionalProperties":true}}}}}},"400":{"description":"Invalid query parameters or unsupported enum values. Rejected by preflight BEFORE the payment challenge — no payment is requested or charged for malformed requests.","content":{"application/problem+json":{"schema":{"type":"object","required":["type","title","status"],"properties":{"type":{"type":"string","format":"uri-reference"},"title":{"type":"string","example":"Bad Request"},"status":{"type":"integer","const":400},"detail":{"type":"string"},"instance":{"type":"string"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":true}},"additionalProperties":true}},"additionalProperties":true}}}},"402":{"description":"Payment challenge required before executing paid work","content":{"application/problem+json":{"schema":{"type":"object","required":["type","title","status"],"properties":{"type":{"type":"string","format":"uri-reference"},"title":{"type":"string","example":"Payment Required"},"status":{"type":"integer","const":402},"detail":{"type":"string"},"instance":{"type":"string"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":true}},"additionalProperties":true}},"additionalProperties":true}}}},"404":{"description":"No matching result. error.code distinguishes the cases: NO_RESULTS (the query resolves to nothing in the catalog) or RETAILER_NOT_SERVING_ELIGIBLE (the requested retailer exists but is not serving-eligible — error.details carries its catalog quality_status and the serving_eligible_retailers list to retry against). Structurally-unservable requests are rejected by preflight before any payment challenge.","content":{"application/problem+json":{"schema":{"type":"object","required":["type","title","status"],"properties":{"type":{"type":"string","format":"uri-reference"},"title":{"type":"string","example":"Not Found"},"status":{"type":"integer","const":404},"detail":{"type":"string"},"instance":{"type":"string"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":true}},"additionalProperties":true}},"additionalProperties":true}}}},"429":{"description":"Rate limit exceeded","content":{"application/problem+json":{"schema":{"type":"object","required":["type","title","status"],"properties":{"type":{"type":"string","format":"uri-reference"},"title":{"type":"string","example":"Too Many Requests"},"status":{"type":"integer","const":429},"detail":{"type":"string"},"instance":{"type":"string"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":true}},"additionalProperties":true}},"additionalProperties":true}}}},"500":{"description":"Unexpected server error","content":{"application/problem+json":{"schema":{"type":"object","required":["type","title","status"],"properties":{"type":{"type":"string","format":"uri-reference"},"title":{"type":"string","example":"Internal Server Error"},"status":{"type":"integer","const":500},"detail":{"type":"string"},"instance":{"type":"string"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":true}},"additionalProperties":true}},"additionalProperties":true}}}}},"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"},"retailer":{"type":"string","enum":["amazon","walmart","target","bestbuy","homedepot","costco","ikea","samsclub","cvs","dillards"],"description":"Filter to a specific retailer platform (long-tail specialty stores are also present; any platform key is accepted)","example":"amazon"},"time_window":{"type":"string","enum":["last_30_days","last_60_days","last_90_days","month_to_date","previous_month","month_over_month","quarter_to_date","custom"],"description":"Historical window preset. Explicit `from`/`to` takes precedence and is reported as `custom`; `time_window=custom` requires both `from` and `to`. Date-only ranges use UTC calendar boundaries with inclusive `from` and exclusive `to`.","example":"last_60_days"},"from":{"type":"string","format":"date","description":"Start date (ISO 8601, defaults to 30 days ago)","example":"2026-05-01"},"to":{"type":"string","format":"date","description":"End date (ISO 8601, defaults to now)","example":"2026-06-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":604800,"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. Accepts a human-readable name (e.g. 'electronics', 'beauty') or a taxonomy slug path (e.g. 'electronics/headphones'); matched against the catalog's category tree (exact node, subtree, or path substring).","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","target","bestbuy","homedepot","costco","ikea","samsclub","cvs","dillards"]},"description":"Filter to a specific retailer platform (long-tail specialty stores are also present; any platform key is accepted)","example":"amazon"},{"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":"time_window","in":"query","required":false,"schema":{"type":"string","enum":["last_30_days","last_60_days","last_90_days","month_to_date","previous_month","month_over_month","quarter_to_date","custom"]},"description":"Historical window preset. Explicit `from`/`to` takes precedence and is reported as `custom`; `time_window=custom` requires both `from` and `to`. Date-only ranges use UTC calendar boundaries with inclusive `from` and exclusive `to`.","example":"last_60_days"},{"name":"from","in":"query","required":false,"schema":{"type":"string","format":"date"},"description":"Start date (ISO 8601, defaults to 30 days ago)","example":"2026-05-01"},{"name":"to","in":"query","required":false,"schema":{"type":"string","format":"date"},"description":"End date (ISO 8601, defaults to now)","example":"2026-06-01"}],"responses":{"200":{"description":"Promo intelligence","content":{"application/json":{"schema":{"type":"object","properties":{"category":{"type":"string"},"country":{"type":"string"},"currency":{"type":"string"},"retailer":{"type":"string","nullable":true},"brand":{"type":"string","nullable":true},"aggregate_by":{"type":"string","enum":["brand","retailer"]},"window":{"type":"object","properties":{"preset":{"type":"string"},"from":{"type":"string","format":"date"},"to":{"type":"string","format":"date"},"granularity":{"type":"string","nullable":true},"comparison_from":{"type":"string","format":"date","nullable":true},"comparison_to":{"type":"string","format":"date","nullable":true},"timezone":{"type":"string","example":"UTC"}},"additionalProperties":true},"brands":{"type":"array","items":{"type":"object","properties":{"brand":{"type":"string","nullable":true},"retailer":{"type":"string","nullable":true},"total_observations":{"type":"integer"},"promo_observations":{"type":"integer"},"promo_frequency_pct":{"type":"number"},"avg_promo_depth_pct":{"type":"number","nullable":true},"max_promo_depth_pct":{"type":"number","nullable":true}},"additionalProperties":true}},"retailers":{"type":"array","items":{"type":"object","properties":{"brand":{"type":"string","nullable":true},"retailer":{"type":"string","nullable":true},"total_observations":{"type":"integer"},"promo_observations":{"type":"integer"},"promo_frequency_pct":{"type":"number"},"avg_promo_depth_pct":{"type":"number","nullable":true},"max_promo_depth_pct":{"type":"number","nullable":true}},"additionalProperties":true}},"resolved":{"type":"object","properties":{"input":{"type":"string"},"category_path":{"type":"string","nullable":true},"department":{"type":"string","nullable":true},"match_source":{"type":"string","nullable":true},"match_confidence":{"type":"number","nullable":true},"alternates":{"type":"array","items":{"type":"object","additionalProperties":true}}},"additionalProperties":true},"meta":{"type":"object","properties":{"served_from":{"type":"string"},"freshness_seconds":{"type":"number"},"schema_version":{"type":"string"},"computed_at":{"type":"string","format":"date-time"},"price_observed_at_min":{"type":"string","format":"date-time","nullable":true},"price_observed_at_max":{"type":"string","format":"date-time","nullable":true}},"additionalProperties":true}}}}}},"400":{"description":"Invalid query parameters or unsupported enum values. Rejected by preflight BEFORE the payment challenge — no payment is requested or charged for malformed requests.","content":{"application/problem+json":{"schema":{"type":"object","required":["type","title","status"],"properties":{"type":{"type":"string","format":"uri-reference"},"title":{"type":"string","example":"Bad Request"},"status":{"type":"integer","const":400},"detail":{"type":"string"},"instance":{"type":"string"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":true}},"additionalProperties":true}},"additionalProperties":true}}}},"402":{"description":"Payment challenge required before executing paid work","content":{"application/problem+json":{"schema":{"type":"object","required":["type","title","status"],"properties":{"type":{"type":"string","format":"uri-reference"},"title":{"type":"string","example":"Payment Required"},"status":{"type":"integer","const":402},"detail":{"type":"string"},"instance":{"type":"string"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":true}},"additionalProperties":true}},"additionalProperties":true}}}},"404":{"description":"No matching result. error.code distinguishes the cases: NO_RESULTS (the query resolves to nothing in the catalog) or RETAILER_NOT_SERVING_ELIGIBLE (the requested retailer exists but is not serving-eligible — error.details carries its catalog quality_status and the serving_eligible_retailers list to retry against). Structurally-unservable requests are rejected by preflight before any payment challenge.","content":{"application/problem+json":{"schema":{"type":"object","required":["type","title","status"],"properties":{"type":{"type":"string","format":"uri-reference"},"title":{"type":"string","example":"Not Found"},"status":{"type":"integer","const":404},"detail":{"type":"string"},"instance":{"type":"string"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":true}},"additionalProperties":true}},"additionalProperties":true}}}},"429":{"description":"Rate limit exceeded","content":{"application/problem+json":{"schema":{"type":"object","required":["type","title","status"],"properties":{"type":{"type":"string","format":"uri-reference"},"title":{"type":"string","example":"Too Many Requests"},"status":{"type":"integer","const":429},"detail":{"type":"string"},"instance":{"type":"string"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":true}},"additionalProperties":true}},"additionalProperties":true}}}},"500":{"description":"Unexpected server error","content":{"application/problem+json":{"schema":{"type":"object","required":["type","title","status"],"properties":{"type":{"type":"string","format":"uri-reference"},"title":{"type":"string","example":"Internal Server Error"},"status":{"type":"integer","const":500},"detail":{"type":"string"},"instance":{"type":"string"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":true}},"additionalProperties":true}},"additionalProperties":true}}}}},"x-input-schema":{"type":"object","additionalProperties":false,"required":["category"],"properties":{"category":{"type":"string","minLength":1,"description":"Product category. Accepts a human-readable name (e.g. 'electronics', 'beauty') or a taxonomy slug path (e.g. 'electronics/headphones'); matched against the catalog's category tree (exact node, subtree, or path substring).","example":"electronics"},"country":{"type":"string","enum":["us","ca"],"default":"us","description":"Country (us or ca)","example":"us"},"retailer":{"type":"string","enum":["amazon","walmart","target","bestbuy","homedepot","costco","ikea","samsclub","cvs","dillards"],"description":"Filter to a specific retailer platform (long-tail specialty stores are also present; any platform key is accepted)","example":"amazon"},"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"},"time_window":{"type":"string","enum":["last_30_days","last_60_days","last_90_days","month_to_date","previous_month","month_over_month","quarter_to_date","custom"],"description":"Historical window preset. Explicit `from`/`to` takes precedence and is reported as `custom`; `time_window=custom` requires both `from` and `to`. Date-only ranges use UTC calendar boundaries with inclusive `from` and exclusive `to`.","example":"last_60_days"},"from":{"type":"string","format":"date","description":"Start date (ISO 8601, defaults to 30 days ago)","example":"2026-05-01"},"to":{"type":"string","format":"date","description":"End date (ISO 8601, defaults to now)","example":"2026-06-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. Brand rows are merged across source variants ('JBL'/'jbl', 'TP-Link'/'tplink') with one canonical display label; placeholder brands (null, 'no', 'Generic') are excluded.","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":604800,"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. Accepts a human-readable name (e.g. 'electronics', 'beauty') or a taxonomy slug path (e.g. 'electronics/headphones'); matched against the catalog's category tree (exact node, subtree, or path substring).","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","target","bestbuy","homedepot","costco","ikea","samsclub","cvs","dillards"]},"description":"Filter to a specific retailer platform (long-tail specialty stores are also present; any platform key is accepted)","example":"amazon"}],"responses":{"200":{"description":"Share of shelf data","content":{"application/json":{"schema":{"type":"object","properties":{"category":{"type":"string"},"country":{"type":"string"},"currency":{"type":"string"},"total_products":{"type":"integer"},"brands":{"type":"array","items":{"type":"object","properties":{"brand":{"type":"string","nullable":true},"product_count":{"type":"integer"},"share_pct":{"type":"number"}},"additionalProperties":true}},"resolved":{"type":"object","properties":{"input":{"type":"string"},"category_path":{"type":"string","nullable":true},"department":{"type":"string","nullable":true},"match_source":{"type":"string","nullable":true},"match_confidence":{"type":"number","nullable":true},"alternates":{"type":"array","items":{"type":"object","additionalProperties":true}}},"additionalProperties":true},"meta":{"type":"object","properties":{"served_from":{"type":"string"},"freshness_seconds":{"type":"number"},"schema_version":{"type":"string"},"computed_at":{"type":"string","format":"date-time"},"price_observed_at_min":{"type":"string","format":"date-time","nullable":true},"price_observed_at_max":{"type":"string","format":"date-time","nullable":true}},"additionalProperties":true}}}}}},"400":{"description":"Invalid query parameters or unsupported enum values. Rejected by preflight BEFORE the payment challenge — no payment is requested or charged for malformed requests.","content":{"application/problem+json":{"schema":{"type":"object","required":["type","title","status"],"properties":{"type":{"type":"string","format":"uri-reference"},"title":{"type":"string","example":"Bad Request"},"status":{"type":"integer","const":400},"detail":{"type":"string"},"instance":{"type":"string"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":true}},"additionalProperties":true}},"additionalProperties":true}}}},"402":{"description":"Payment challenge required before executing paid work","content":{"application/problem+json":{"schema":{"type":"object","required":["type","title","status"],"properties":{"type":{"type":"string","format":"uri-reference"},"title":{"type":"string","example":"Payment Required"},"status":{"type":"integer","const":402},"detail":{"type":"string"},"instance":{"type":"string"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":true}},"additionalProperties":true}},"additionalProperties":true}}}},"404":{"description":"No matching result. error.code distinguishes the cases: NO_RESULTS (the query resolves to nothing in the catalog) or RETAILER_NOT_SERVING_ELIGIBLE (the requested retailer exists but is not serving-eligible — error.details carries its catalog quality_status and the serving_eligible_retailers list to retry against). Structurally-unservable requests are rejected by preflight before any payment challenge.","content":{"application/problem+json":{"schema":{"type":"object","required":["type","title","status"],"properties":{"type":{"type":"string","format":"uri-reference"},"title":{"type":"string","example":"Not Found"},"status":{"type":"integer","const":404},"detail":{"type":"string"},"instance":{"type":"string"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":true}},"additionalProperties":true}},"additionalProperties":true}}}},"429":{"description":"Rate limit exceeded","content":{"application/problem+json":{"schema":{"type":"object","required":["type","title","status"],"properties":{"type":{"type":"string","format":"uri-reference"},"title":{"type":"string","example":"Too Many Requests"},"status":{"type":"integer","const":429},"detail":{"type":"string"},"instance":{"type":"string"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":true}},"additionalProperties":true}},"additionalProperties":true}}}},"500":{"description":"Unexpected server error","content":{"application/problem+json":{"schema":{"type":"object","required":["type","title","status"],"properties":{"type":{"type":"string","format":"uri-reference"},"title":{"type":"string","example":"Internal Server Error"},"status":{"type":"integer","const":500},"detail":{"type":"string"},"instance":{"type":"string"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":true}},"additionalProperties":true}},"additionalProperties":true}}}}},"x-input-schema":{"type":"object","additionalProperties":false,"required":["category"],"properties":{"category":{"type":"string","minLength":1,"description":"Product category. Accepts a human-readable name (e.g. 'electronics', 'beauty') or a taxonomy slug path (e.g. 'electronics/headphones'); matched against the catalog's category tree (exact node, subtree, or path substring).","example":"electronics"},"country":{"type":"string","enum":["us","ca"],"default":"us","description":"Country (us or ca)","example":"us"},"retailer":{"type":"string","enum":["amazon","walmart","target","bestbuy","homedepot","costco","ikea","samsclub","cvs","dillards"],"description":"Filter to a specific retailer platform (long-tail specialty stores are also present; any platform key is accepted)","example":"amazon"}}}}},"/v1/marketing/price-positioning":{"get":{"operationId":"getPricePositioning","summary":"Analyze a brand's price positioning vs competitors","description":"Compare a brand's average current 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":604800,"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. Accepts a human-readable name (e.g. 'electronics', 'beauty') or a taxonomy slug path (e.g. 'electronics/headphones'); matched against the catalog's category tree (exact node, subtree, or path substring).","example":"electronics"},{"name":"retailer","in":"query","required":false,"schema":{"type":"string","enum":["amazon","walmart","target","bestbuy","homedepot","costco","ikea","samsclub","cvs","dillards"]},"description":"Filter to a specific retailer platform (long-tail specialty stores are also present; any platform key is accepted)","example":"amazon"}],"responses":{"200":{"description":"Price positioning data","content":{"application/json":{"schema":{"type":"object","properties":{"brand":{"type":"string"},"category":{"type":"string"},"country":{"type":"string"},"currency":{"type":"string"},"brand_avg_price":{"type":"number","nullable":true},"category_avg_price":{"type":"number","nullable":true},"category_median_price":{"type":"number","nullable":true},"price_index":{"type":"number","nullable":true},"positioning":{"type":"string","enum":["premium","mid-range","value","unknown"]},"product_count":{"type":"integer"},"resolved":{"type":"object","properties":{"input":{"type":"string"},"category_path":{"type":"string","nullable":true},"department":{"type":"string","nullable":true},"match_source":{"type":"string","nullable":true},"match_confidence":{"type":"number","nullable":true},"alternates":{"type":"array","items":{"type":"object","additionalProperties":true}}},"additionalProperties":true},"meta":{"type":"object","properties":{"served_from":{"type":"string"},"freshness_seconds":{"type":"number"},"schema_version":{"type":"string"},"computed_at":{"type":"string","format":"date-time"},"price_observed_at_min":{"type":"string","format":"date-time","nullable":true},"price_observed_at_max":{"type":"string","format":"date-time","nullable":true}},"additionalProperties":true}}}}}},"400":{"description":"Invalid query parameters or unsupported enum values. Rejected by preflight BEFORE the payment challenge — no payment is requested or charged for malformed requests.","content":{"application/problem+json":{"schema":{"type":"object","required":["type","title","status"],"properties":{"type":{"type":"string","format":"uri-reference"},"title":{"type":"string","example":"Bad Request"},"status":{"type":"integer","const":400},"detail":{"type":"string"},"instance":{"type":"string"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":true}},"additionalProperties":true}},"additionalProperties":true}}}},"402":{"description":"Payment challenge required before executing paid work","content":{"application/problem+json":{"schema":{"type":"object","required":["type","title","status"],"properties":{"type":{"type":"string","format":"uri-reference"},"title":{"type":"string","example":"Payment Required"},"status":{"type":"integer","const":402},"detail":{"type":"string"},"instance":{"type":"string"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":true}},"additionalProperties":true}},"additionalProperties":true}}}},"404":{"description":"No matching result. error.code distinguishes the cases: NO_RESULTS (the query resolves to nothing in the catalog) or RETAILER_NOT_SERVING_ELIGIBLE (the requested retailer exists but is not serving-eligible — error.details carries its catalog quality_status and the serving_eligible_retailers list to retry against). Structurally-unservable requests are rejected by preflight before any payment challenge.","content":{"application/problem+json":{"schema":{"type":"object","required":["type","title","status"],"properties":{"type":{"type":"string","format":"uri-reference"},"title":{"type":"string","example":"Not Found"},"status":{"type":"integer","const":404},"detail":{"type":"string"},"instance":{"type":"string"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":true}},"additionalProperties":true}},"additionalProperties":true}}}},"429":{"description":"Rate limit exceeded","content":{"application/problem+json":{"schema":{"type":"object","required":["type","title","status"],"properties":{"type":{"type":"string","format":"uri-reference"},"title":{"type":"string","example":"Too Many Requests"},"status":{"type":"integer","const":429},"detail":{"type":"string"},"instance":{"type":"string"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":true}},"additionalProperties":true}},"additionalProperties":true}}}},"500":{"description":"Unexpected server error","content":{"application/problem+json":{"schema":{"type":"object","required":["type","title","status"],"properties":{"type":{"type":"string","format":"uri-reference"},"title":{"type":"string","example":"Internal Server Error"},"status":{"type":"integer","const":500},"detail":{"type":"string"},"instance":{"type":"string"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":true}},"additionalProperties":true}},"additionalProperties":true}}}}},"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. Accepts a human-readable name (e.g. 'electronics', 'beauty') or a taxonomy slug path (e.g. 'electronics/headphones'); matched against the catalog's category tree (exact node, subtree, or path substring).","example":"electronics"},"retailer":{"type":"string","enum":["amazon","walmart","target","bestbuy","homedepot","costco","ikea","samsclub","cvs","dillards"],"description":"Filter to a specific retailer platform (long-tail specialty stores are also present; any platform key is accepted)","example":"amazon"}}}}},"/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. Period-over-period change_pct uses matched-pairs methodology: only products priced in both consecutive periods count, aggregated as the geometric mean of price relatives (Jevons), so basket-composition shifts don't masquerade as inflation. Each period reports matched_basket_size and method ('matched', or 'naive' avg-vs-avg fallback when fewer than 10 products match); overall_change_pct chains the per-period changes. The catalog refresh cadence is monthly, so granularity=monthly gives the most stable matched baskets.","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":604800,"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},"x-required-any-of":[["category"],["department"]],"parameters":[{"name":"category","in":"query","required":false,"schema":{"type":"string","minLength":1},"description":"Product category. Accepts a human-readable name (e.g. 'electronics', 'beauty') or a taxonomy slug path (e.g. 'electronics/headphones'); matched against the catalog's category tree (exact node, subtree, or path substring). For analyst endpoints, supply either `category` or `department`; both may be supplied to narrow the scope.","example":"electronics"},{"name":"department","in":"query","required":false,"schema":{"type":"string","minLength":1},"description":"Top-level department (root category), e.g. 'Electronics', 'Beauty', 'Home & Kitchen'. Case-insensitive; matched against the category tree's root segment. For analyst endpoints, supply either `category` or `department`; both may be supplied to narrow the scope.","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","target","bestbuy","homedepot","costco","ikea","samsclub","cvs","dillards"]},"description":"Filter to a specific retailer platform (long-tail specialty stores are also present; any platform key is accepted)","example":"amazon"},{"name":"time_window","in":"query","required":false,"schema":{"type":"string","enum":["last_30_days","last_60_days","last_90_days","month_to_date","previous_month","month_over_month","quarter_to_date","custom"]},"description":"Historical window preset. Explicit `from`/`to` takes precedence and is reported as `custom`; `time_window=custom` requires both `from` and `to`. Date-only ranges use UTC calendar boundaries with inclusive `from` and exclusive `to`.","example":"last_60_days"},{"name":"from","in":"query","required":false,"schema":{"type":"string","format":"date"},"description":"Start date (ISO 8601, defaults to 30 days ago)","example":"2026-05-01"},{"name":"to","in":"query","required":false,"schema":{"type":"string","format":"date"},"description":"End date (ISO 8601, defaults to now)","example":"2026-06-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","properties":{"category":{"type":"string","nullable":true},"department":{"type":"string","nullable":true},"country":{"type":"string"},"currency":{"type":"string"},"granularity":{"type":"string","enum":["daily","weekly","monthly"]},"overall_change_pct":{"type":"number","nullable":true},"method":{"type":"string","enum":["matched","naive","mixed"],"nullable":true},"window":{"type":"object","properties":{"preset":{"type":"string"},"from":{"type":"string","format":"date"},"to":{"type":"string","format":"date"},"granularity":{"type":"string","nullable":true},"comparison_from":{"type":"string","format":"date","nullable":true},"comparison_to":{"type":"string","format":"date","nullable":true},"timezone":{"type":"string","example":"UTC"}},"additionalProperties":true},"time_series":{"type":"array","items":{"type":"object","properties":{"date":{"type":"string","format":"date"},"period":{"type":"string"},"avg_price":{"type":"number","nullable":true},"min_price":{"type":"number","nullable":true},"max_price":{"type":"number","nullable":true},"median_price":{"type":"number","nullable":true},"product_count":{"type":"integer"},"observation_count":{"type":"integer"},"change_pct":{"type":"number","nullable":true},"matched_basket_size":{"type":"integer"},"method":{"type":"string","nullable":true},"in_stock_count":{"type":"integer"},"promo_count":{"type":"integer"},"retailer_avg_price":{"type":"number","nullable":true},"category_avg_price":{"type":"number","nullable":true},"price_index":{"type":"number","nullable":true},"stable_avg_price":{"type":"number","nullable":true,"description":"Average over only the stable basket (products priced in EVERY period of the series) — immune to basket-composition shifts. Null when no product spans the whole series."},"insufficient_sample":{"type":"boolean","description":"True when product_count is below sample_threshold — treat the point as anecdote, not trend."},"sample_threshold":{"type":"integer"}},"additionalProperties":true}},"resolved":{"type":"object","properties":{"input":{"type":"string"},"category_path":{"type":"string","nullable":true},"department":{"type":"string","nullable":true},"match_source":{"type":"string","nullable":true},"match_confidence":{"type":"number","nullable":true},"alternates":{"type":"array","items":{"type":"object","additionalProperties":true}}},"additionalProperties":true},"meta":{"type":"object","properties":{"served_from":{"type":"string"},"freshness_seconds":{"type":"number"},"schema_version":{"type":"string"},"computed_at":{"type":"string","format":"date-time"},"price_observed_at_min":{"type":"string","format":"date-time","nullable":true},"price_observed_at_max":{"type":"string","format":"date-time","nullable":true}},"additionalProperties":true}}}}}},"400":{"description":"Invalid query parameters or unsupported enum values. Rejected by preflight BEFORE the payment challenge — no payment is requested or charged for malformed requests.","content":{"application/problem+json":{"schema":{"type":"object","required":["type","title","status"],"properties":{"type":{"type":"string","format":"uri-reference"},"title":{"type":"string","example":"Bad Request"},"status":{"type":"integer","const":400},"detail":{"type":"string"},"instance":{"type":"string"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":true}},"additionalProperties":true}},"additionalProperties":true}}}},"402":{"description":"Payment challenge required before executing paid work","content":{"application/problem+json":{"schema":{"type":"object","required":["type","title","status"],"properties":{"type":{"type":"string","format":"uri-reference"},"title":{"type":"string","example":"Payment Required"},"status":{"type":"integer","const":402},"detail":{"type":"string"},"instance":{"type":"string"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":true}},"additionalProperties":true}},"additionalProperties":true}}}},"404":{"description":"No matching result. error.code distinguishes the cases: NO_RESULTS (the query resolves to nothing in the catalog) or RETAILER_NOT_SERVING_ELIGIBLE (the requested retailer exists but is not serving-eligible — error.details carries its catalog quality_status and the serving_eligible_retailers list to retry against). Structurally-unservable requests are rejected by preflight before any payment challenge.","content":{"application/problem+json":{"schema":{"type":"object","required":["type","title","status"],"properties":{"type":{"type":"string","format":"uri-reference"},"title":{"type":"string","example":"Not Found"},"status":{"type":"integer","const":404},"detail":{"type":"string"},"instance":{"type":"string"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":true}},"additionalProperties":true}},"additionalProperties":true}}}},"429":{"description":"Rate limit exceeded","content":{"application/problem+json":{"schema":{"type":"object","required":["type","title","status"],"properties":{"type":{"type":"string","format":"uri-reference"},"title":{"type":"string","example":"Too Many Requests"},"status":{"type":"integer","const":429},"detail":{"type":"string"},"instance":{"type":"string"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":true}},"additionalProperties":true}},"additionalProperties":true}}}},"500":{"description":"Unexpected server error","content":{"application/problem+json":{"schema":{"type":"object","required":["type","title","status"],"properties":{"type":{"type":"string","format":"uri-reference"},"title":{"type":"string","example":"Internal Server Error"},"status":{"type":"integer","const":500},"detail":{"type":"string"},"instance":{"type":"string"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":true}},"additionalProperties":true}},"additionalProperties":true}}}}},"x-input-schema":{"type":"object","additionalProperties":false,"properties":{"category":{"type":"string","minLength":1,"description":"Product category. Accepts a human-readable name (e.g. 'electronics', 'beauty') or a taxonomy slug path (e.g. 'electronics/headphones'); matched against the catalog's category tree (exact node, subtree, or path substring). For analyst endpoints, supply either `category` or `department`; both may be supplied to narrow the scope.","example":"electronics"},"department":{"type":"string","minLength":1,"description":"Top-level department (root category), e.g. 'Electronics', 'Beauty', 'Home & Kitchen'. Case-insensitive; matched against the category tree's root segment. For analyst endpoints, supply either `category` or `department`; both may be supplied to narrow the scope.","example":"Electronics"},"country":{"type":"string","enum":["us","ca"],"default":"us","description":"Country (us or ca)","example":"us"},"retailer":{"type":"string","enum":["amazon","walmart","target","bestbuy","homedepot","costco","ikea","samsclub","cvs","dillards"],"description":"Filter to a specific retailer platform (long-tail specialty stores are also present; any platform key is accepted)","example":"amazon"},"time_window":{"type":"string","enum":["last_30_days","last_60_days","last_90_days","month_to_date","previous_month","month_over_month","quarter_to_date","custom"],"description":"Historical window preset. Explicit `from`/`to` takes precedence and is reported as `custom`; `time_window=custom` requires both `from` and `to`. Date-only ranges use UTC calendar boundaries with inclusive `from` and exclusive `to`.","example":"last_60_days"},"from":{"type":"string","format":"date","description":"Start date (ISO 8601, defaults to 30 days ago)","example":"2026-05-01"},"to":{"type":"string","format":"date","description":"End date (ISO 8601, defaults to now)","example":"2026-06-01"},"granularity":{"type":"string","enum":["daily","weekly","monthly"],"default":"weekly","description":"Time granularity for the series","example":"weekly"}},"anyOf":[{"required":["category"]},{"required":["department"]}]}}},"/v1/analyst/price-dispersion":{"get":{"operationId":"getPriceDispersion","summary":"Analyze price spread across retailers for a category or department","description":"Analyze the spread of current prices within a category - mean, stddev, coefficient of variation, and percentiles (p10..p90) with IQR outlier exclusion. The population is representativeness-filtered: refurbished/used listings, accessory/parts subtrees, and rows under a category-aware price floor are excluded from headline stats, with the counts disclosed in `excluded`.","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":604800,"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},"x-required-any-of":[["category"],["department"]],"parameters":[{"name":"category","in":"query","required":false,"schema":{"type":"string","minLength":1},"description":"Product category. Accepts a human-readable name (e.g. 'electronics', 'beauty') or a taxonomy slug path (e.g. 'electronics/headphones'); matched against the catalog's category tree (exact node, subtree, or path substring). For analyst endpoints, supply either `category` or `department`; both may be supplied to narrow the scope.","example":"electronics"},{"name":"department","in":"query","required":false,"schema":{"type":"string","minLength":1},"description":"Top-level department (root category), e.g. 'Electronics', 'Beauty', 'Home & Kitchen'. Case-insensitive; matched against the category tree's root segment. For analyst endpoints, supply either `category` or `department`; both may be supplied to narrow the scope.","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","target","bestbuy","homedepot","costco","ikea","samsclub","cvs","dillards"]},"description":"Filter to a specific retailer platform (long-tail specialty stores are also present; any platform key is accepted)","example":"amazon"}],"responses":{"200":{"description":"Price dispersion data","content":{"application/json":{"schema":{"type":"object","properties":{"category":{"type":"string","nullable":true},"department":{"type":"string","nullable":true},"country":{"type":"string"},"currency":{"type":"string"},"avg_price":{"type":"number","nullable":true},"min_price":{"type":"number","nullable":true},"max_price":{"type":"number","nullable":true},"std_dev":{"type":"number","nullable":true},"coeff_of_variation":{"type":"number","nullable":true},"percentiles":{"type":"object","properties":{"p10":{"type":"number","nullable":true},"p25":{"type":"number","nullable":true},"p50":{"type":"number","nullable":true},"p75":{"type":"number","nullable":true},"p90":{"type":"number","nullable":true}}},"product_count":{"type":"integer"},"outliers_excluded":{"type":"integer"},"representative_floor":{"type":"number"},"excluded":{"type":"object","description":"Transparency counts: rows in scope but excluded from the headline statistics by the representativeness policy.","properties":{"below_floor":{"type":"integer"},"refurbished_or_used":{"type":"integer"},"accessory_or_parts":{"type":"integer"},"price_outliers":{"type":"integer"}},"additionalProperties":true},"resolved":{"type":"object","properties":{"input":{"type":"string"},"category_path":{"type":"string","nullable":true},"department":{"type":"string","nullable":true},"match_source":{"type":"string","nullable":true},"match_confidence":{"type":"number","nullable":true},"alternates":{"type":"array","items":{"type":"object","additionalProperties":true}}},"additionalProperties":true},"meta":{"type":"object","properties":{"served_from":{"type":"string"},"freshness_seconds":{"type":"number"},"schema_version":{"type":"string"},"computed_at":{"type":"string","format":"date-time"},"price_observed_at_min":{"type":"string","format":"date-time","nullable":true},"price_observed_at_max":{"type":"string","format":"date-time","nullable":true}},"additionalProperties":true}}}}}},"400":{"description":"Invalid query parameters or unsupported enum values. Rejected by preflight BEFORE the payment challenge — no payment is requested or charged for malformed requests.","content":{"application/problem+json":{"schema":{"type":"object","required":["type","title","status"],"properties":{"type":{"type":"string","format":"uri-reference"},"title":{"type":"string","example":"Bad Request"},"status":{"type":"integer","const":400},"detail":{"type":"string"},"instance":{"type":"string"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":true}},"additionalProperties":true}},"additionalProperties":true}}}},"402":{"description":"Payment challenge required before executing paid work","content":{"application/problem+json":{"schema":{"type":"object","required":["type","title","status"],"properties":{"type":{"type":"string","format":"uri-reference"},"title":{"type":"string","example":"Payment Required"},"status":{"type":"integer","const":402},"detail":{"type":"string"},"instance":{"type":"string"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":true}},"additionalProperties":true}},"additionalProperties":true}}}},"404":{"description":"No matching result. error.code distinguishes the cases: NO_RESULTS (the query resolves to nothing in the catalog) or RETAILER_NOT_SERVING_ELIGIBLE (the requested retailer exists but is not serving-eligible — error.details carries its catalog quality_status and the serving_eligible_retailers list to retry against). Structurally-unservable requests are rejected by preflight before any payment challenge.","content":{"application/problem+json":{"schema":{"type":"object","required":["type","title","status"],"properties":{"type":{"type":"string","format":"uri-reference"},"title":{"type":"string","example":"Not Found"},"status":{"type":"integer","const":404},"detail":{"type":"string"},"instance":{"type":"string"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":true}},"additionalProperties":true}},"additionalProperties":true}}}},"429":{"description":"Rate limit exceeded","content":{"application/problem+json":{"schema":{"type":"object","required":["type","title","status"],"properties":{"type":{"type":"string","format":"uri-reference"},"title":{"type":"string","example":"Too Many Requests"},"status":{"type":"integer","const":429},"detail":{"type":"string"},"instance":{"type":"string"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":true}},"additionalProperties":true}},"additionalProperties":true}}}},"500":{"description":"Unexpected server error","content":{"application/problem+json":{"schema":{"type":"object","required":["type","title","status"],"properties":{"type":{"type":"string","format":"uri-reference"},"title":{"type":"string","example":"Internal Server Error"},"status":{"type":"integer","const":500},"detail":{"type":"string"},"instance":{"type":"string"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":true}},"additionalProperties":true}},"additionalProperties":true}}}}},"x-input-schema":{"type":"object","additionalProperties":false,"properties":{"category":{"type":"string","minLength":1,"description":"Product category. Accepts a human-readable name (e.g. 'electronics', 'beauty') or a taxonomy slug path (e.g. 'electronics/headphones'); matched against the catalog's category tree (exact node, subtree, or path substring). For analyst endpoints, supply either `category` or `department`; both may be supplied to narrow the scope.","example":"electronics"},"department":{"type":"string","minLength":1,"description":"Top-level department (root category), e.g. 'Electronics', 'Beauty', 'Home & Kitchen'. Case-insensitive; matched against the category tree's root segment. For analyst endpoints, supply either `category` or `department`; both may be supplied to narrow the scope.","example":"Electronics"},"country":{"type":"string","enum":["us","ca"],"default":"us","description":"Country (us or ca)","example":"us"},"retailer":{"type":"string","enum":["amazon","walmart","target","bestbuy","homedepot","costco","ikea","samsclub","cvs","dillards"],"description":"Filter to a specific retailer platform (long-tail specialty stores are also present; any platform key is accepted)","example":"amazon"}},"anyOf":[{"required":["category"]},{"required":["department"]}]}}},"/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. Points report insufficient_sample below sample_threshold products plus stable_avg_price over the products priced every day — read trends from the stable series.","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":604800,"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},"x-required-any-of":[["category"],["department"]],"parameters":[{"name":"retailer","in":"query","required":true,"schema":{"type":"string"},"description":"Retailer platform key (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. Accepts a human-readable name (e.g. 'electronics', 'beauty') or a taxonomy slug path (e.g. 'electronics/headphones'); matched against the catalog's category tree (exact node, subtree, or path substring). For analyst endpoints, supply either `category` or `department`; both may be supplied to narrow the scope.","example":"electronics"},{"name":"department","in":"query","required":false,"schema":{"type":"string","minLength":1},"description":"Top-level department (root category), e.g. 'Electronics', 'Beauty', 'Home & Kitchen'. Case-insensitive; matched against the category tree's root segment. For analyst endpoints, supply either `category` or `department`; both may be supplied to narrow the scope.","example":"Electronics"},{"name":"time_window","in":"query","required":false,"schema":{"type":"string","enum":["last_30_days","last_60_days","last_90_days","month_to_date","previous_month","month_over_month","quarter_to_date","custom"]},"description":"Historical window preset. Explicit `from`/`to` takes precedence and is reported as `custom`; `time_window=custom` requires both `from` and `to`. Date-only ranges use UTC calendar boundaries with inclusive `from` and exclusive `to`.","example":"last_60_days"},{"name":"from","in":"query","required":false,"schema":{"type":"string","format":"date"},"description":"Start date (ISO 8601, defaults to 30 days ago)","example":"2026-05-01"},{"name":"to","in":"query","required":false,"schema":{"type":"string","format":"date"},"description":"End date (ISO 8601, defaults to now)","example":"2026-06-01"}],"responses":{"200":{"description":"Retailer index data","content":{"application/json":{"schema":{"type":"object","properties":{"retailer":{"type":"string"},"category":{"type":"string"},"department":{"type":"string","nullable":true},"country":{"type":"string"},"currency":{"type":"string"},"window":{"type":"object","properties":{"preset":{"type":"string"},"from":{"type":"string","format":"date"},"to":{"type":"string","format":"date"},"granularity":{"type":"string","nullable":true},"comparison_from":{"type":"string","format":"date","nullable":true},"comparison_to":{"type":"string","format":"date","nullable":true},"timezone":{"type":"string","example":"UTC"}},"additionalProperties":true},"sample_threshold":{"type":"integer"},"insufficient_sample_points":{"type":"integer"},"insufficient_sample":{"type":"boolean","description":"True when any series point has a basket below sample_threshold."},"stable_basket_size":{"type":"integer","nullable":true,"description":"Products priced in every period of the series (the basis of stable_avg_price). Null for single-point series."},"time_series":{"type":"array","items":{"type":"object","properties":{"date":{"type":"string","format":"date"},"period":{"type":"string"},"avg_price":{"type":"number","nullable":true},"min_price":{"type":"number","nullable":true},"max_price":{"type":"number","nullable":true},"median_price":{"type":"number","nullable":true},"product_count":{"type":"integer"},"observation_count":{"type":"integer"},"change_pct":{"type":"number","nullable":true},"matched_basket_size":{"type":"integer"},"method":{"type":"string","nullable":true},"in_stock_count":{"type":"integer"},"promo_count":{"type":"integer"},"retailer_avg_price":{"type":"number","nullable":true},"category_avg_price":{"type":"number","nullable":true},"price_index":{"type":"number","nullable":true},"stable_avg_price":{"type":"number","nullable":true,"description":"Average over only the stable basket (products priced in EVERY period of the series) — immune to basket-composition shifts. Null when no product spans the whole series."},"insufficient_sample":{"type":"boolean","description":"True when product_count is below sample_threshold — treat the point as anecdote, not trend."},"sample_threshold":{"type":"integer"}},"additionalProperties":true}},"resolved":{"type":"object","properties":{"input":{"type":"string"},"category_path":{"type":"string","nullable":true},"department":{"type":"string","nullable":true},"match_source":{"type":"string","nullable":true},"match_confidence":{"type":"number","nullable":true},"alternates":{"type":"array","items":{"type":"object","additionalProperties":true}}},"additionalProperties":true},"meta":{"type":"object","properties":{"served_from":{"type":"string"},"freshness_seconds":{"type":"number"},"schema_version":{"type":"string"},"computed_at":{"type":"string","format":"date-time"},"price_observed_at_min":{"type":"string","format":"date-time","nullable":true},"price_observed_at_max":{"type":"string","format":"date-time","nullable":true}},"additionalProperties":true}}}}}},"400":{"description":"Invalid query parameters or unsupported enum values. Rejected by preflight BEFORE the payment challenge — no payment is requested or charged for malformed requests.","content":{"application/problem+json":{"schema":{"type":"object","required":["type","title","status"],"properties":{"type":{"type":"string","format":"uri-reference"},"title":{"type":"string","example":"Bad Request"},"status":{"type":"integer","const":400},"detail":{"type":"string"},"instance":{"type":"string"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":true}},"additionalProperties":true}},"additionalProperties":true}}}},"402":{"description":"Payment challenge required before executing paid work","content":{"application/problem+json":{"schema":{"type":"object","required":["type","title","status"],"properties":{"type":{"type":"string","format":"uri-reference"},"title":{"type":"string","example":"Payment Required"},"status":{"type":"integer","const":402},"detail":{"type":"string"},"instance":{"type":"string"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":true}},"additionalProperties":true}},"additionalProperties":true}}}},"404":{"description":"No matching result. error.code distinguishes the cases: NO_RESULTS (the query resolves to nothing in the catalog) or RETAILER_NOT_SERVING_ELIGIBLE (the requested retailer exists but is not serving-eligible — error.details carries its catalog quality_status and the serving_eligible_retailers list to retry against). Structurally-unservable requests are rejected by preflight before any payment challenge.","content":{"application/problem+json":{"schema":{"type":"object","required":["type","title","status"],"properties":{"type":{"type":"string","format":"uri-reference"},"title":{"type":"string","example":"Not Found"},"status":{"type":"integer","const":404},"detail":{"type":"string"},"instance":{"type":"string"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":true}},"additionalProperties":true}},"additionalProperties":true}}}},"429":{"description":"Rate limit exceeded","content":{"application/problem+json":{"schema":{"type":"object","required":["type","title","status"],"properties":{"type":{"type":"string","format":"uri-reference"},"title":{"type":"string","example":"Too Many Requests"},"status":{"type":"integer","const":429},"detail":{"type":"string"},"instance":{"type":"string"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":true}},"additionalProperties":true}},"additionalProperties":true}}}},"500":{"description":"Unexpected server error","content":{"application/problem+json":{"schema":{"type":"object","required":["type","title","status"],"properties":{"type":{"type":"string","format":"uri-reference"},"title":{"type":"string","example":"Internal Server Error"},"status":{"type":"integer","const":500},"detail":{"type":"string"},"instance":{"type":"string"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":true}},"additionalProperties":true}},"additionalProperties":true}}}}},"x-input-schema":{"type":"object","additionalProperties":false,"required":["retailer"],"properties":{"retailer":{"type":"string","description":"Retailer platform key (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. Accepts a human-readable name (e.g. 'electronics', 'beauty') or a taxonomy slug path (e.g. 'electronics/headphones'); matched against the catalog's category tree (exact node, subtree, or path substring). For analyst endpoints, supply either `category` or `department`; both may be supplied to narrow the scope.","example":"electronics"},"department":{"type":"string","minLength":1,"description":"Top-level department (root category), e.g. 'Electronics', 'Beauty', 'Home & Kitchen'. Case-insensitive; matched against the category tree's root segment. For analyst endpoints, supply either `category` or `department`; both may be supplied to narrow the scope.","example":"Electronics"},"time_window":{"type":"string","enum":["last_30_days","last_60_days","last_90_days","month_to_date","previous_month","month_over_month","quarter_to_date","custom"],"description":"Historical window preset. Explicit `from`/`to` takes precedence and is reported as `custom`; `time_window=custom` requires both `from` and `to`. Date-only ranges use UTC calendar boundaries with inclusive `from` and exclusive `to`.","example":"last_60_days"},"from":{"type":"string","format":"date","description":"Start date (ISO 8601, defaults to 30 days ago)","example":"2026-05-01"},"to":{"type":"string","format":"date","description":"End date (ISO 8601, defaults to now)","example":"2026-06-01"}},"anyOf":[{"required":["category"]},{"required":["department"]}]}}},"/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), promo rate, in-stock rate, and top brands. Headline stats are representativeness-filtered (no refurb/used, no accessory/parts subtrees, category-aware price floor) with exclusion counts disclosed in `excluded`; brand_count and top_brands merge brand variants on the canonical key and exclude placeholders.","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":604800,"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},"x-required-any-of":[["category"],["department"]],"parameters":[{"name":"category","in":"query","required":false,"schema":{"type":"string","minLength":1},"description":"Product category. Accepts a human-readable name (e.g. 'electronics', 'beauty') or a taxonomy slug path (e.g. 'electronics/headphones'); matched against the catalog's category tree (exact node, subtree, or path substring). For analyst endpoints, supply either `category` or `department`; both may be supplied to narrow the scope.","example":"electronics"},{"name":"department","in":"query","required":false,"schema":{"type":"string","minLength":1},"description":"Top-level department (root category), e.g. 'Electronics', 'Beauty', 'Home & Kitchen'. Case-insensitive; matched against the category tree's root segment. For analyst endpoints, supply either `category` or `department`; both may be supplied to narrow the scope.","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","target","bestbuy","homedepot","costco","ikea","samsclub","cvs","dillards"]},"description":"Filter to a specific retailer platform (long-tail specialty stores are also present; any platform key is accepted)","example":"amazon"}],"responses":{"200":{"description":"Category summary","content":{"application/json":{"schema":{"type":"object","properties":{"category":{"type":"string","nullable":true},"department":{"type":"string","nullable":true},"country":{"type":"string"},"currency":{"type":"string"},"product_count":{"type":"integer"},"brand_count":{"type":"integer"},"retailer_count":{"type":"integer"},"pricing":{"type":"object","properties":{"avg":{"type":"number","nullable":true},"min":{"type":"number","nullable":true},"max":{"type":"number","nullable":true},"median":{"type":"number","nullable":true}}},"avg_rating":{"type":"number","nullable":true},"promo_rate_pct":{"type":"number","nullable":true},"in_stock_rate_pct":{"type":"number","nullable":true},"representative_floor":{"type":"number"},"excluded":{"type":"object","description":"Transparency counts: rows in scope but excluded from the headline statistics by the representativeness policy.","properties":{"below_floor":{"type":"integer"},"refurbished_or_used":{"type":"integer"},"accessory_or_parts":{"type":"integer"},"price_outliers":{"type":"integer"}},"additionalProperties":true},"top_brands":{"type":"array","items":{"type":"object","properties":{"brand":{"type":"string","nullable":true},"product_count":{"type":"integer"},"share_pct":{"type":"number"}},"additionalProperties":true}},"resolved":{"type":"object","properties":{"input":{"type":"string"},"category_path":{"type":"string","nullable":true},"department":{"type":"string","nullable":true},"match_source":{"type":"string","nullable":true},"match_confidence":{"type":"number","nullable":true},"alternates":{"type":"array","items":{"type":"object","additionalProperties":true}}},"additionalProperties":true},"meta":{"type":"object","properties":{"served_from":{"type":"string"},"freshness_seconds":{"type":"number"},"schema_version":{"type":"string"},"computed_at":{"type":"string","format":"date-time"},"price_observed_at_min":{"type":"string","format":"date-time","nullable":true},"price_observed_at_max":{"type":"string","format":"date-time","nullable":true}},"additionalProperties":true}}}}}},"400":{"description":"Invalid query parameters or unsupported enum values. Rejected by preflight BEFORE the payment challenge — no payment is requested or charged for malformed requests.","content":{"application/problem+json":{"schema":{"type":"object","required":["type","title","status"],"properties":{"type":{"type":"string","format":"uri-reference"},"title":{"type":"string","example":"Bad Request"},"status":{"type":"integer","const":400},"detail":{"type":"string"},"instance":{"type":"string"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":true}},"additionalProperties":true}},"additionalProperties":true}}}},"402":{"description":"Payment challenge required before executing paid work","content":{"application/problem+json":{"schema":{"type":"object","required":["type","title","status"],"properties":{"type":{"type":"string","format":"uri-reference"},"title":{"type":"string","example":"Payment Required"},"status":{"type":"integer","const":402},"detail":{"type":"string"},"instance":{"type":"string"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":true}},"additionalProperties":true}},"additionalProperties":true}}}},"404":{"description":"No matching result. error.code distinguishes the cases: NO_RESULTS (the query resolves to nothing in the catalog) or RETAILER_NOT_SERVING_ELIGIBLE (the requested retailer exists but is not serving-eligible — error.details carries its catalog quality_status and the serving_eligible_retailers list to retry against). Structurally-unservable requests are rejected by preflight before any payment challenge.","content":{"application/problem+json":{"schema":{"type":"object","required":["type","title","status"],"properties":{"type":{"type":"string","format":"uri-reference"},"title":{"type":"string","example":"Not Found"},"status":{"type":"integer","const":404},"detail":{"type":"string"},"instance":{"type":"string"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":true}},"additionalProperties":true}},"additionalProperties":true}}}},"429":{"description":"Rate limit exceeded","content":{"application/problem+json":{"schema":{"type":"object","required":["type","title","status"],"properties":{"type":{"type":"string","format":"uri-reference"},"title":{"type":"string","example":"Too Many Requests"},"status":{"type":"integer","const":429},"detail":{"type":"string"},"instance":{"type":"string"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":true}},"additionalProperties":true}},"additionalProperties":true}}}},"500":{"description":"Unexpected server error","content":{"application/problem+json":{"schema":{"type":"object","required":["type","title","status"],"properties":{"type":{"type":"string","format":"uri-reference"},"title":{"type":"string","example":"Internal Server Error"},"status":{"type":"integer","const":500},"detail":{"type":"string"},"instance":{"type":"string"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":true}},"additionalProperties":true}},"additionalProperties":true}}}}},"x-input-schema":{"type":"object","additionalProperties":false,"properties":{"category":{"type":"string","minLength":1,"description":"Product category. Accepts a human-readable name (e.g. 'electronics', 'beauty') or a taxonomy slug path (e.g. 'electronics/headphones'); matched against the catalog's category tree (exact node, subtree, or path substring). For analyst endpoints, supply either `category` or `department`; both may be supplied to narrow the scope.","example":"electronics"},"department":{"type":"string","minLength":1,"description":"Top-level department (root category), e.g. 'Electronics', 'Beauty', 'Home & Kitchen'. Case-insensitive; matched against the category tree's root segment. For analyst endpoints, supply either `category` or `department`; both may be supplied to narrow the scope.","example":"Electronics"},"country":{"type":"string","enum":["us","ca"],"default":"us","description":"Country (us or ca)","example":"us"},"retailer":{"type":"string","enum":["amazon","walmart","target","bestbuy","homedepot","costco","ikea","samsclub","cvs","dillards"],"description":"Filter to a specific retailer platform (long-tail specialty stores are also present; any platform key is accepted)","example":"amazon"}},"anyOf":[{"required":["category"]},{"required":["department"]}]}}}},"components":{"schemas":{"ListPublicCategoriesInput":{"type":"object","additionalProperties":false,"properties":{"parent_path":{"type":"string","minLength":1,"description":"Optional category path whose descendants should be listed","example":"electronics"},"depth":{"type":"integer","default":1,"minimum":1,"maximum":3,"description":"Maximum depth below parent_path (default 1, max 3)","example":1},"limit":{"type":"integer","default":200,"minimum":1,"maximum":500,"description":"Max results to return (default 200, min 1, max 500)","example":200},"offset":{"type":"integer","default":0,"minimum":0,"description":"Pagination offset","example":0}}},"GetBestPriceInput":{"type":"object","additionalProperties":false,"properties":{"q":{"type":"string","minLength":1,"description":"Search query (product name, keyword, or brand + model). Required unless `product_uid` or `entity_uid` is supplied.","example":"airpods"},"product_uid":{"type":"string","minLength":1,"description":"Stable product identifier returned by a prior Syntalic shopper response. When supplied, the endpoint should pin to this listing instead of re-resolving free text.","example":"p_airpods_deal"},"entity_uid":{"type":"string","minLength":1,"description":"Stable cross-retailer entity identifier returned by a prior Syntalic shopper response. When supplied, the endpoint should resolve within the same physical-product entity.","example":"e_airpods_deal"},"country":{"type":"string","enum":["us","ca"],"default":"us","description":"Country (us or ca)","example":"us"},"retailer":{"type":"string","enum":["amazon","walmart","target","bestbuy","homedepot","costco","ikea","samsclub","cvs","dillards"],"description":"Filter to a specific retailer platform (long-tail specialty stores are also present; any platform key is accepted)","example":"amazon"},"limit":{"type":"integer","default":10,"minimum":1,"maximum":50,"description":"Max results to return (default 10, min 1, max 50)","example":10},"strict":{"type":"boolean","default":false,"description":"When true, restrict the comparison to entity-verified listings of the matched product (match_type 'entity' only). Default false also includes title-match rows — useful for broad queries, but may mix product variants.","example":false}},"anyOf":[{"required":["q"]},{"required":["product_uid"]},{"required":["entity_uid"]}]},"GetPriceHistoryInput":{"type":"object","additionalProperties":false,"properties":{"q":{"type":"string","minLength":1,"description":"Search query (product name, keyword, or brand + model). Required unless `product_uid` or `entity_uid` is supplied.","example":"airpods"},"product_uid":{"type":"string","minLength":1,"description":"Stable product identifier returned by a prior Syntalic shopper response. When supplied, the endpoint should pin to this listing instead of re-resolving free text.","example":"p_airpods_deal"},"entity_uid":{"type":"string","minLength":1,"description":"Stable cross-retailer entity identifier returned by a prior Syntalic shopper response. When supplied, the endpoint should resolve within the same physical-product entity.","example":"e_airpods_deal"},"country":{"type":"string","enum":["us","ca"],"default":"us","description":"Country (us or ca)","example":"us"},"retailer":{"type":"string","enum":["amazon","walmart","target","bestbuy","homedepot","costco","ikea","samsclub","cvs","dillards"],"description":"Filter to a specific retailer platform (long-tail specialty stores are also present; any platform key is accepted)","example":"amazon"},"time_window":{"type":"string","enum":["last_30_days","last_60_days","last_90_days","month_to_date","previous_month","month_over_month","quarter_to_date","custom"],"description":"Historical window preset. Explicit `from`/`to` takes precedence and is reported as `custom`; `time_window=custom` requires both `from` and `to`. Date-only ranges use UTC calendar boundaries with inclusive `from` and exclusive `to`.","example":"last_60_days"},"from":{"type":"string","format":"date","description":"Start date (ISO 8601, defaults to 30 days ago)","example":"2026-05-01"},"to":{"type":"string","format":"date","description":"End date (ISO 8601, defaults to now)","example":"2026-06-01"}},"anyOf":[{"required":["q"]},{"required":["product_uid"]},{"required":["entity_uid"]}]},"FindDealsInput":{"type":"object","additionalProperties":false,"required":["category"],"properties":{"category":{"type":"string","minLength":1,"description":"Product category. Accepts a human-readable name (e.g. 'electronics', 'beauty') or a taxonomy slug path (e.g. 'electronics/headphones'); matched against the catalog's category tree (exact node, subtree, or path substring).","example":"electronics"},"country":{"type":"string","enum":["us","ca"],"default":"us","description":"Country (us or ca)","example":"us"},"retailer":{"type":"string","enum":["amazon","walmart","target","bestbuy","homedepot","costco","ikea","samsclub","cvs","dillards"],"description":"Filter to a specific retailer platform (long-tail specialty stores are also present; any platform key is accepted)","example":"amazon"},"min_discount_pct":{"type":"integer","default":10,"description":"Minimum discount percentage (default 10)","example":10},"limit":{"type":"integer","default":20,"minimum":1,"maximum":50,"description":"Max results to return (default 20, min 1, max 50)","example":20}}},"GetPriceDropAlertInput":{"type":"object","additionalProperties":false,"properties":{"q":{"type":"string","minLength":1,"description":"Search query (product name, keyword, or brand + model). Required unless `product_uid` or `entity_uid` is supplied.","example":"airpods"},"product_uid":{"type":"string","minLength":1,"description":"Stable product identifier returned by a prior Syntalic shopper response. When supplied, the endpoint should pin to this listing instead of re-resolving free text.","example":"p_airpods_deal"},"entity_uid":{"type":"string","minLength":1,"description":"Stable cross-retailer entity identifier returned by a prior Syntalic shopper response. When supplied, the endpoint should resolve within the same physical-product entity.","example":"e_airpods_deal"},"country":{"type":"string","enum":["us","ca"],"default":"us","description":"Country (us or ca)","example":"us"},"retailer":{"type":"string","enum":["amazon","walmart","target","bestbuy","homedepot","costco","ikea","samsclub","cvs","dillards"],"description":"Filter to a specific retailer platform (long-tail specialty stores are also present; any platform key is accepted)","example":"amazon"},"time_window":{"type":"string","enum":["last_30_days","last_60_days","last_90_days","month_to_date","previous_month","month_over_month","quarter_to_date","custom"],"description":"Historical window preset. Explicit `from`/`to` takes precedence and is reported as `custom`; `time_window=custom` requires both `from` and `to`. Date-only ranges use UTC calendar boundaries with inclusive `from` and exclusive `to`.","example":"last_60_days"},"lookback_days":{"type":"integer","default":30,"minimum":1,"description":"Days to look back for price drops (default 30). Backwards-compatible alias for matching `last_N_days` windows.","example":30}},"anyOf":[{"required":["q"]},{"required":["product_uid"]},{"required":["entity_uid"]}]},"GetCompetitiveLandscapeInput":{"type":"object","additionalProperties":false,"required":["category"],"properties":{"category":{"type":"string","minLength":1,"description":"Product category. Accepts a human-readable name (e.g. 'electronics', 'beauty') or a taxonomy slug path (e.g. 'electronics/headphones'); matched against the catalog's category tree (exact node, subtree, or path substring).","example":"electronics"},"country":{"type":"string","enum":["us","ca"],"default":"us","description":"Country (us or ca)","example":"us"},"retailer":{"type":"string","enum":["amazon","walmart","target","bestbuy","homedepot","costco","ikea","samsclub","cvs","dillards"],"description":"Filter to a specific retailer platform (long-tail specialty stores are also present; any platform key is accepted)","example":"amazon"},"sort_by":{"type":"string","enum":["price_asc","price_desc","rating","reviews"],"default":"price_asc","description":"Sort order (rating/reviews accepted for compatibility; fall back to price_asc)","example":"price_asc"},"cursor":{"type":"integer","minimum":0,"description":"Pagination cursor — pass the previous response's next_cursor","example":0},"limit":{"type":"integer","default":20,"minimum":1,"maximum":50,"description":"Max results to return (default 20, min 1, 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"},"retailer":{"type":"string","enum":["amazon","walmart","target","bestbuy","homedepot","costco","ikea","samsclub","cvs","dillards"],"description":"Filter to a specific retailer platform (long-tail specialty stores are also present; any platform key is accepted)","example":"amazon"},"time_window":{"type":"string","enum":["last_30_days","last_60_days","last_90_days","month_to_date","previous_month","month_over_month","quarter_to_date","custom"],"description":"Historical window preset. Explicit `from`/`to` takes precedence and is reported as `custom`; `time_window=custom` requires both `from` and `to`. Date-only ranges use UTC calendar boundaries with inclusive `from` and exclusive `to`.","example":"last_60_days"},"from":{"type":"string","format":"date","description":"Start date (ISO 8601, defaults to 30 days ago)","example":"2026-05-01"},"to":{"type":"string","format":"date","description":"End date (ISO 8601, defaults to now)","example":"2026-06-01"}}},"GetPromoIntelligenceInput":{"type":"object","additionalProperties":false,"required":["category"],"properties":{"category":{"type":"string","minLength":1,"description":"Product category. Accepts a human-readable name (e.g. 'electronics', 'beauty') or a taxonomy slug path (e.g. 'electronics/headphones'); matched against the catalog's category tree (exact node, subtree, or path substring).","example":"electronics"},"country":{"type":"string","enum":["us","ca"],"default":"us","description":"Country (us or ca)","example":"us"},"retailer":{"type":"string","enum":["amazon","walmart","target","bestbuy","homedepot","costco","ikea","samsclub","cvs","dillards"],"description":"Filter to a specific retailer platform (long-tail specialty stores are also present; any platform key is accepted)","example":"amazon"},"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"},"time_window":{"type":"string","enum":["last_30_days","last_60_days","last_90_days","month_to_date","previous_month","month_over_month","quarter_to_date","custom"],"description":"Historical window preset. Explicit `from`/`to` takes precedence and is reported as `custom`; `time_window=custom` requires both `from` and `to`. Date-only ranges use UTC calendar boundaries with inclusive `from` and exclusive `to`.","example":"last_60_days"},"from":{"type":"string","format":"date","description":"Start date (ISO 8601, defaults to 30 days ago)","example":"2026-05-01"},"to":{"type":"string","format":"date","description":"End date (ISO 8601, defaults to now)","example":"2026-06-01"}}},"GetShareOfShelfInput":{"type":"object","additionalProperties":false,"required":["category"],"properties":{"category":{"type":"string","minLength":1,"description":"Product category. Accepts a human-readable name (e.g. 'electronics', 'beauty') or a taxonomy slug path (e.g. 'electronics/headphones'); matched against the catalog's category tree (exact node, subtree, or path substring).","example":"electronics"},"country":{"type":"string","enum":["us","ca"],"default":"us","description":"Country (us or ca)","example":"us"},"retailer":{"type":"string","enum":["amazon","walmart","target","bestbuy","homedepot","costco","ikea","samsclub","cvs","dillards"],"description":"Filter to a specific retailer platform (long-tail specialty stores are also present; any platform key is accepted)","example":"amazon"}}},"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. Accepts a human-readable name (e.g. 'electronics', 'beauty') or a taxonomy slug path (e.g. 'electronics/headphones'); matched against the catalog's category tree (exact node, subtree, or path substring).","example":"electronics"},"retailer":{"type":"string","enum":["amazon","walmart","target","bestbuy","homedepot","costco","ikea","samsclub","cvs","dillards"],"description":"Filter to a specific retailer platform (long-tail specialty stores are also present; any platform key is accepted)","example":"amazon"}}},"GetInflationInput":{"type":"object","additionalProperties":false,"properties":{"category":{"type":"string","minLength":1,"description":"Product category. Accepts a human-readable name (e.g. 'electronics', 'beauty') or a taxonomy slug path (e.g. 'electronics/headphones'); matched against the catalog's category tree (exact node, subtree, or path substring). For analyst endpoints, supply either `category` or `department`; both may be supplied to narrow the scope.","example":"electronics"},"department":{"type":"string","minLength":1,"description":"Top-level department (root category), e.g. 'Electronics', 'Beauty', 'Home & Kitchen'. Case-insensitive; matched against the category tree's root segment. For analyst endpoints, supply either `category` or `department`; both may be supplied to narrow the scope.","example":"Electronics"},"country":{"type":"string","enum":["us","ca"],"default":"us","description":"Country (us or ca)","example":"us"},"retailer":{"type":"string","enum":["amazon","walmart","target","bestbuy","homedepot","costco","ikea","samsclub","cvs","dillards"],"description":"Filter to a specific retailer platform (long-tail specialty stores are also present; any platform key is accepted)","example":"amazon"},"time_window":{"type":"string","enum":["last_30_days","last_60_days","last_90_days","month_to_date","previous_month","month_over_month","quarter_to_date","custom"],"description":"Historical window preset. Explicit `from`/`to` takes precedence and is reported as `custom`; `time_window=custom` requires both `from` and `to`. Date-only ranges use UTC calendar boundaries with inclusive `from` and exclusive `to`.","example":"last_60_days"},"from":{"type":"string","format":"date","description":"Start date (ISO 8601, defaults to 30 days ago)","example":"2026-05-01"},"to":{"type":"string","format":"date","description":"End date (ISO 8601, defaults to now)","example":"2026-06-01"},"granularity":{"type":"string","enum":["daily","weekly","monthly"],"default":"weekly","description":"Time granularity for the series","example":"weekly"}},"anyOf":[{"required":["category"]},{"required":["department"]}]},"GetPriceDispersionInput":{"type":"object","additionalProperties":false,"properties":{"category":{"type":"string","minLength":1,"description":"Product category. Accepts a human-readable name (e.g. 'electronics', 'beauty') or a taxonomy slug path (e.g. 'electronics/headphones'); matched against the catalog's category tree (exact node, subtree, or path substring). For analyst endpoints, supply either `category` or `department`; both may be supplied to narrow the scope.","example":"electronics"},"department":{"type":"string","minLength":1,"description":"Top-level department (root category), e.g. 'Electronics', 'Beauty', 'Home & Kitchen'. Case-insensitive; matched against the category tree's root segment. For analyst endpoints, supply either `category` or `department`; both may be supplied to narrow the scope.","example":"Electronics"},"country":{"type":"string","enum":["us","ca"],"default":"us","description":"Country (us or ca)","example":"us"},"retailer":{"type":"string","enum":["amazon","walmart","target","bestbuy","homedepot","costco","ikea","samsclub","cvs","dillards"],"description":"Filter to a specific retailer platform (long-tail specialty stores are also present; any platform key is accepted)","example":"amazon"}},"anyOf":[{"required":["category"]},{"required":["department"]}]},"GetRetailerIndexInput":{"type":"object","additionalProperties":false,"required":["retailer"],"properties":{"retailer":{"type":"string","description":"Retailer platform key (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. Accepts a human-readable name (e.g. 'electronics', 'beauty') or a taxonomy slug path (e.g. 'electronics/headphones'); matched against the catalog's category tree (exact node, subtree, or path substring). For analyst endpoints, supply either `category` or `department`; both may be supplied to narrow the scope.","example":"electronics"},"department":{"type":"string","minLength":1,"description":"Top-level department (root category), e.g. 'Electronics', 'Beauty', 'Home & Kitchen'. Case-insensitive; matched against the category tree's root segment. For analyst endpoints, supply either `category` or `department`; both may be supplied to narrow the scope.","example":"Electronics"},"time_window":{"type":"string","enum":["last_30_days","last_60_days","last_90_days","month_to_date","previous_month","month_over_month","quarter_to_date","custom"],"description":"Historical window preset. Explicit `from`/`to` takes precedence and is reported as `custom`; `time_window=custom` requires both `from` and `to`. Date-only ranges use UTC calendar boundaries with inclusive `from` and exclusive `to`.","example":"last_60_days"},"from":{"type":"string","format":"date","description":"Start date (ISO 8601, defaults to 30 days ago)","example":"2026-05-01"},"to":{"type":"string","format":"date","description":"End date (ISO 8601, defaults to now)","example":"2026-06-01"}},"anyOf":[{"required":["category"]},{"required":["department"]}]},"GetCategorySummaryInput":{"type":"object","additionalProperties":false,"properties":{"category":{"type":"string","minLength":1,"description":"Product category. Accepts a human-readable name (e.g. 'electronics', 'beauty') or a taxonomy slug path (e.g. 'electronics/headphones'); matched against the catalog's category tree (exact node, subtree, or path substring). For analyst endpoints, supply either `category` or `department`; both may be supplied to narrow the scope.","example":"electronics"},"department":{"type":"string","minLength":1,"description":"Top-level department (root category), e.g. 'Electronics', 'Beauty', 'Home & Kitchen'. Case-insensitive; matched against the category tree's root segment. For analyst endpoints, supply either `category` or `department`; both may be supplied to narrow the scope.","example":"Electronics"},"country":{"type":"string","enum":["us","ca"],"default":"us","description":"Country (us or ca)","example":"us"},"retailer":{"type":"string","enum":["amazon","walmart","target","bestbuy","homedepot","costco","ikea","samsclub","cvs","dillards"],"description":"Filter to a specific retailer platform (long-tail specialty stores are also present; any platform key is accepted)","example":"amazon"}},"anyOf":[{"required":["category"]},{"required":["department"]}]}}}}