{"openapi":"3.1.0","servers":[{"url":"https://api.syntalic.com"}],"info":{"title":"Syntalic — Data Analytics for Agentic Commerce ","version":"1.0.0","contact":{"name":"Syntalic","email":"support@syntalic.com","url":"https://syntalic.com"},"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":{"/openapi.json":{"get":{"operationId":"getOpenApiSpec","summary":"OpenAPI 3.1 discovery document","description":"Free machine-readable contract. Not a paid resource — agents and scanners should fetch this without a payment challenge.","tags":["Public"],"security":[],"responses":{"200":{"description":"OpenAPI 3.1 document","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}}},"x-input-schema":{"type":"object","additionalProperties":false,"properties":{}}}},"/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"],"security":[],"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"}}},"brands":{"type":"object","properties":{"total":{"type":"integer"}}},"observations":{"type":"object","properties":{"total":{"type":"integer","description":"Approximate count of price/stock observations in the serving hot window (planner estimate, refreshed by autovacuum/analyze)."}}},"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}}}}}}},"x-input-schema":{"type":"object","additionalProperties":false,"properties":{}}}},"/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"],"security":[],"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/public/retailers":{"get":{"operationId":"listPublicRetailers","summary":"List retailers (platforms) in the catalog","description":"Zero-cost aggregate discovery endpoint. One row per platform with served product count, countries seen, and freshest observation; row-level product data remains on paid endpoints.","tags":["Public"],"security":[],"parameters":[{"name":"limit","in":"query","required":false,"schema":{"type":"integer","default":100,"minimum":1,"maximum":500},"description":"Max results to return (default 100, min 1, max 500)","example":100},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","default":0,"minimum":0},"description":"Pagination offset","example":0}],"responses":{"200":{"description":"Public retailers","content":{"application/json":{"schema":{"type":"object","properties":{"items":{"type":"array","items":{"type":"object","properties":{"platform":{"type":"string"},"product_count":{"type":"integer"},"countries":{"type":"array","items":{"type":"string"}},"last_observed_at":{"type":"string","format":"date-time","nullable":true}}}},"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":{"limit":{"type":"integer","default":100,"minimum":1,"maximum":500,"description":"Max results to return (default 100, min 1, max 500)","example":100},"offset":{"type":"integer","default":0,"minimum":0,"description":"Pagination offset","example":0}}}}},"/v1/public/brands":{"get":{"operationId":"listPublicBrands","summary":"List brands in the catalog","description":"Zero-cost aggregate discovery endpoint. One row per normalized brand with a display label and served product count; optional q prefix-matches the normalized key (JBL == jbl).","tags":["Public"],"security":[],"parameters":[{"name":"q","in":"query","required":false,"schema":{"type":"string","minLength":1},"description":"Prefix match on the normalized brand key (case/punctuation-insensitive)","example":"sam"},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","default":100,"minimum":1,"maximum":500},"description":"Max results to return (default 100, min 1, max 500)","example":100},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","default":0,"minimum":0},"description":"Pagination offset","example":0}],"responses":{"200":{"description":"Public brands","content":{"application/json":{"schema":{"type":"object","properties":{"items":{"type":"array","items":{"type":"object","properties":{"brand":{"type":"string"},"brand_norm":{"type":"string"},"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":{"q":{"type":"string","minLength":1,"description":"Prefix match on the normalized brand key (case/punctuation-insensitive)","example":"sam"},"limit":{"type":"integer","default":100,"minimum":1,"maximum":500,"description":"Max results to return (default 100, min 1, max 500)","example":100},"offset":{"type":"integer","default":0,"minimum":0,"description":"Pagination offset","example":0}}}}},"/v1/public/coverage":{"get":{"operationId":"listPublicCoverage","summary":"Catalog coverage map (depth/quality per cell)","description":"Zero-cost aggregate discovery endpoint. Coverage + freshness per (platform, country, category_root): priced/recent/known-brand product counts and quality_status (serving/thin/stale — computed from shelf volume and 90-day freshness, never from how the data is acquired), so an agent can gauge whether a paid query will hit deep data. Row-level product data remains on paid endpoints.","tags":["Public"],"security":[],"parameters":[{"name":"country","in":"query","required":false,"schema":{"type":"string","enum":["us","ca"]},"description":"Filter to a country","example":"us"},{"name":"platform","in":"query","required":false,"schema":{"type":"string"},"description":"Filter to a platform (e.g. amazon, walmart)","example":"walmart"},{"name":"category_root","in":"query","required":false,"schema":{"type":"string"},"description":"Filter to a top-level category","example":"electronics"},{"name":"quality_status","in":"query","required":false,"schema":{"type":"string","enum":["serving","thin","stale"]},"description":"Filter to a coverage tier","example":"serving"},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","default":200,"minimum":1,"maximum":1000},"description":"Max results to return (default 200, min 1, max 1000)","example":200},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","default":0,"minimum":0},"description":"Pagination offset","example":0}],"responses":{"200":{"description":"Public coverage","content":{"application/json":{"schema":{"type":"object","properties":{"items":{"type":"array","items":{"type":"object","properties":{"platform":{"type":"string"},"country":{"type":"string"},"category_root":{"type":"string"},"priced_product_count":{"type":"integer"},"recent_priced_product_count":{"type":"integer"},"known_brand_product_count":{"type":"integer"},"quality_status":{"type":"string"},"is_serving_eligible":{"type":"boolean"},"last_observed_at":{"type":"string","format":"date-time","nullable":true}}}},"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":{"country":{"type":"string","enum":["us","ca"],"description":"Filter to a country","example":"us"},"platform":{"type":"string","description":"Filter to a platform (e.g. amazon, walmart)","example":"walmart"},"category_root":{"type":"string","description":"Filter to a top-level category","example":"electronics"},"quality_status":{"type":"string","enum":["serving","thin","stale"],"description":"Filter to a coverage tier","example":"serving"},"limit":{"type":"integer","default":200,"minimum":1,"maximum":1000,"description":"Max results to return (default 200, min 1, max 1000)","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":"Returns a nullable `gpc` block identifying the resolved product's GS1 GPC product type (code, title, full ancestry, and how exact the mapping is) — null when the product's category has no GPC mapping. 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"},"dropped_terms":{"type":"array","items":{"type":"string"},"nullable":true,"description":"Non-null when no product matched the query as written and retrieval had to drop these trailing terms to resolve one. Treat the result as an answer to the SHORTENED query: `NOBULL Laces black` returning these terms as ['black'] means the black variant was not found, only NOBULL Laces."},"country":{"type":"string"},"currency":{"type":"string"},"product_uid":{"type":"string"},"entity_uid":{"type":"string","nullable":true},"scope":{"type":"string","enum":["entity","listing"],"description":"'entity' = prices span the resolved product's cross-platform entity; 'listing' = the product belongs to no multi-member entity, so only its own listing is priced."},"member_count":{"type":"integer"},"match_suspect":{"type":"boolean","description":"True when the pipeline has already flagged this entity as welding together materially different products (intra_entity_incoherent). The comparison set — and therefore the headline price — may span variants that are not substitutes; prefer strict=true or a product_uid when this is set."},"retailers_compared":{"type":"integer","description":"Distinct retailers spanned by best_price + other_prices. **1 means no cross-retailer comparison was possible for this product** — it is the cheapest listing found, not the cheapest anywhere. Most direct-to-consumer products are sold by a single merchant and can never exceed 1; named-retailer products are roughly 48x likelier to support a real comparison. related_matches are excluded from this count because they are title matches on other entities, not prices for this product."},"resolved_product":{"type":"object","additionalProperties":true},"gpc":{"type":"object","additionalProperties":true,"nullable":true},"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","self_text","title"],"description":"'entity' = verified same physical product via cross-platform entity resolution; 'self_text' = the resolved product itself, matched on its own text; '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","self_text","title"]},"observed_at":{"type":"string","format":"date-time","description":"When this row's price was observed — rows in one comparison can differ in vintage."}}}},"related_matches":{"type":"array","description":"Title-matched rows OUTSIDE the resolved entity. Not price comparisons for the same product — a cheaper row here may be a different product, and a genuinely identical SKU can also land here when entity resolution split it across retailers.","items":{"type":"object","properties":{"product_uid":{"type":"string"},"entity_uid":{"type":"string","nullable":true},"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","self_text","title"]},"observed_at":{"type":"string","format":"date-time"}}}},"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), 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), or NOT_PUBLISHED (a social rollup the current publish run does not compute yet — a gap in what we publish, not a finding about the category). 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. Includes a nullable gpc block for the resolved product (fail-soft).","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), 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), or NOT_PUBLISHED (a social rollup the current publish run does not compute yet — a gap in what we publish, not a finding about the category). 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) and a nullable gpc block (fail-soft).","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":"brand","in":"query","required":false,"schema":{"type":"string","minLength":1},"description":"Brand name (e.g., Sony, Samsung, Nike)","example":"Apple"},{"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). Also accepts a GS1 GPC code (exactly 8 digits, e.g. '10001159') to filter by PRODUCT TYPE instead of by shelf placement — the same product type is shelved under different categories by different retailers, so a category filter answers from a fraction of the data while a GPC code spans them. Coarser codes (class/family/segment) match every brick beneath them. Resolve a phrase to a code with /v1/reference/classify?q=... ; when a code is used, resolved.match_source is 'gpc'.","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), 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), or NOT_PUBLISHED (a social rollup the current publish run does not compute yet — a gap in what we publish, not a finding about the category). 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":{"brand":{"type":"string","minLength":1,"description":"Brand name (e.g., Sony, Samsung, Nike)","example":"Apple"},"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). Also accepts a GS1 GPC code (exactly 8 digits, e.g. '10001159') to filter by PRODUCT TYPE instead of by shelf placement — the same product type is shelved under different categories by different retailers, so a category filter answers from a fraction of the data while a GPC code spans them. Coarser codes (class/family/segment) match every brick beneath them. Resolve a phrase to a code with /v1/reference/classify?q=... ; when a code is used, resolved.match_source is 'gpc'.","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. Includes a nullable gpc block for the resolved product (fail-soft).","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), 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), or NOT_PUBLISHED (a social rollup the current publish run does not compute yet — a gap in what we publish, not a finding about the category). 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, plus a nullable gpc block (fail-soft). 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). Also accepts a GS1 GPC code (exactly 8 digits, e.g. '10001159') to filter by PRODUCT TYPE instead of by shelf placement — the same product type is shelved under different categories by different retailers, so a category filter answers from a fraction of the data while a GPC code spans them. Coarser codes (class/family/segment) match every brick beneath them. Resolve a phrase to a code with /v1/reference/classify?q=... ; when a code is used, resolved.match_source is 'gpc'.","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), 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), or NOT_PUBLISHED (a social rollup the current publish run does not compute yet — a gap in what we publish, not a finding about the category). 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). Also accepts a GS1 GPC code (exactly 8 digits, e.g. '10001159') to filter by PRODUCT TYPE instead of by shelf placement — the same product type is shelved under different categories by different retailers, so a category filter answers from a fraction of the data while a GPC code spans them. Coarser codes (class/family/segment) match every brick beneath them. Resolve a phrase to a code with /v1/reference/classify?q=... ; when a code is used, resolved.match_source is 'gpc'.","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), 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), or NOT_PUBLISHED (a social rollup the current publish run does not compute yet — a gap in what we publish, not a finding about the category). 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). Also accepts a GS1 GPC code (exactly 8 digits, e.g. '10001159') to filter by PRODUCT TYPE instead of by shelf placement — the same product type is shelved under different categories by different retailers, so a category filter answers from a fraction of the data while a GPC code spans them. Coarser codes (class/family/segment) match every brick beneath them. Resolve a phrase to a code with /v1/reference/classify?q=... ; when a code is used, resolved.match_source is 'gpc'.","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), 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), or NOT_PUBLISHED (a social rollup the current publish run does not compute yet — a gap in what we publish, not a finding about the category). 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). Also accepts a GS1 GPC code (exactly 8 digits, e.g. '10001159') to filter by PRODUCT TYPE instead of by shelf placement — the same product type is shelved under different categories by different retailers, so a category filter answers from a fraction of the data while a GPC code spans them. Coarser codes (class/family/segment) match every brick beneath them. Resolve a phrase to a code with /v1/reference/classify?q=... ; when a code is used, resolved.match_source is 'gpc'.","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). Also accepts a GS1 GPC code (exactly 8 digits, e.g. '10001159') to filter by PRODUCT TYPE instead of by shelf placement — the same product type is shelved under different categories by different retailers, so a category filter answers from a fraction of the data while a GPC code spans them. Coarser codes (class/family/segment) match every brick beneath them. Resolve a phrase to a code with /v1/reference/classify?q=... ; when a code is used, resolved.match_source is 'gpc'.","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), 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), or NOT_PUBLISHED (a social rollup the current publish run does not compute yet — a gap in what we publish, not a finding about the category). 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). Also accepts a GS1 GPC code (exactly 8 digits, e.g. '10001159') to filter by PRODUCT TYPE instead of by shelf placement — the same product type is shelved under different categories by different retailers, so a category filter answers from a fraction of the data while a GPC code spans them. Coarser codes (class/family/segment) match every brick beneath them. Resolve a phrase to a code with /v1/reference/classify?q=... ; when a code is used, resolved.match_source is 'gpc'.","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). Also accepts a GS1 GPC code (exactly 8 digits, e.g. '10001159') to filter by PRODUCT TYPE instead of by shelf placement — the same product type is shelved under different categories by different retailers, so a category filter answers from a fraction of the data while a GPC code spans them. Coarser codes (class/family/segment) match every brick beneath them. Resolve a phrase to a code with /v1/reference/classify?q=... ; when a code is used, resolved.match_source is 'gpc'.","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), 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), or NOT_PUBLISHED (a social rollup the current publish run does not compute yet — a gap in what we publish, not a finding about the category). 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). Also accepts a GS1 GPC code (exactly 8 digits, e.g. '10001159') to filter by PRODUCT TYPE instead of by shelf placement — the same product type is shelved under different categories by different retailers, so a category filter answers from a fraction of the data while a GPC code spans them. Coarser codes (class/family/segment) match every brick beneath them. Resolve a phrase to a code with /v1/reference/classify?q=... ; when a code is used, resolved.match_source is 'gpc'.","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/social/creator-index":{"get":{"operationId":"getCreatorIndex","summary":"Rank creators by mention volume in a category","description":"Creators ranked by mention volume within a CPG category, with follower tier, reach, organic share, engagement rate and momentum. Answers 'who is talking about this category', 'which creators drive the conversation', and 'who is new this window'. Handles are public identifiers; no contact details, no post links, no captions or transcripts are ever returned. Covers TikTok and Instagram only - this is not a general social-listening feed, and nothing in the pipeline reads X, YouTube or Reddit. The corpus is a tracked set, not the market universe, so shares describe conversation we observed rather than all conversation that happened. The rollup publishes category-level rows only. `organic_only` works, and `organic_pct` reports each creator's organic share of their own mentions. `followers` and `tier` are derived at publish from the corpus's own pull payloads (TikTok author metadata; an Instagram profile sidecar), banded Nano <10K / Micro 10-50K / Small 50-100K / Mid 100-500K / Macro 500K-1M / Mega 1M+. A null on one row means that creator could not be sized; when EVERY row is null (runs published before the derivation existed) coverage.enrichment_note says so - do not size any audience while that note is present. Ranking is on mentions and is unaffected either way.","tags":["Social"],"x-faremeter-pricing":{"rates":{"solana-usdc":"30000","base-usdc":"30000","tempo-usdc":"30000"},"rules":[{"match":"$","capture":"1"}]},"x-payment-info":{"amount":"30000","currency":"0x20c000000000000000000000b9537d11c60e8b50","description":"Social signals query - $0.03 per request","intent":"charge","method":"tempo","methods":[{"method":"tempo","intent":"charge","currency":"0x20c000000000000000000000b9537d11c60e8b50","decimals":6,"amount":"30000","settlement":"Tempo Allegro USDC.e","role":"primary"}],"price":{"mode":"fixed","currency":"USD","amount":"0.030000"},"protocols":[{"x402":{}},{"mpp":{"method":"tempo","intent":"charge","currency":"USDC","amount":"30000","recipient":"0xe2e662cF219025AFC0C9Bf850b6a2B0a0b5517fe"}}]},"x-sla":{"p50_ms":150,"p99_ms":500,"freshness_seconds_max":1209600,"idempotency":"safe","cache_hint":"public"},"x-retry-policy":{"min_backoff_seconds":2,"max_backoff_seconds":30,"max_attempts":4,"jitter_required":true,"idempotency_safe":true},"parameters":[{"name":"category","in":"query","required":true,"schema":{"type":"string"},"example":"grocery-gourmet-food","description":"Category root slug (department, not aisle)."},{"name":"window","in":"query","required":false,"schema":{"type":"string","enum":["7d","30d","90d"],"default":"30d"},"description":"Rollup window. Only published windows are accepted."},{"name":"platform","in":"query","required":false,"schema":{"type":"string","enum":["all","tiktok","instagram"],"default":"all"},"description":"TikTok and Instagram are the only platforms in the corpus."},{"name":"organic_only","in":"query","required":false,"schema":{"type":"boolean","default":false},"description":"Exclude posts marked as ads."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","default":25,"minimum":1,"maximum":100},"description":"Max results to return (default 25, min 1, max 100)","example":25}],"responses":{"200":{"description":"Creator index","content":{"application/json":{"schema":{"type":"object","properties":{"category":{"type":"string"},"subcategory":{"type":"string","nullable":true,"description":"Always null. The rollup publishes category-level rows only."},"window_days":{"type":"integer"},"platform":{"type":"string"},"organic_only":{"type":"boolean"},"creators":{"type":"array","items":{"type":"object","additionalProperties":true}},"noise_pct":{"type":"number","nullable":true},"coverage":{"type":"object","description":"How much data backed this answer. `sufficient` is false when the slice is too thin to read as a market statement; the count is always reported so you can judge for yourself, and `note` explains an empty or thin result rather than leaving you to infer it.","properties":{"products":{"type":"integer","example":42},"sufficient":{"type":"boolean","example":true},"note":{"type":"string"},"unpublished_note":{"type":"string","description":"Names columns that came back null on EVERY row because the publish job writes them unpopulated, not because the subjects lack the attribute. Never infer a zero or an absence from a column named here."},"sku_note":{"type":"string","description":"Present when `skus` is null on every row returned. Read the column as unavailable for this run, not as a stocking fact."},"rank_note":{"type":"string","description":"Present when brands carry `tied_with`. Says how many, and that the tie list is pairwise proximity rather than an equivalence class."}},"additionalProperties":true},"freshness":{"type":"object","description":"How current the underlying observations are. `observedThrough` is the newest observation behind this answer; `staleHours` is its age. Both null when nothing was observed.","properties":{"observedThrough":{"type":"string","format":"date-time","nullable":true},"staleHours":{"type":"number","nullable":true,"example":6.5}},"additionalProperties":true},"snapshot":{"type":"object","additionalProperties":true,"nullable":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), 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), or NOT_PUBLISHED (a social rollup the current publish run does not compute yet — a gap in what we publish, not a finding about the category). 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","description":"Category root slug (department, not aisle).","example":"grocery-gourmet-food"},"window":{"type":"string","enum":["7d","30d","90d"],"default":"30d","description":"Rollup window. Only published windows are accepted."},"platform":{"type":"string","enum":["all","tiktok","instagram"],"default":"all","description":"TikTok and Instagram are the only platforms in the corpus."},"organic_only":{"type":"boolean","default":false,"description":"Exclude posts marked as ads."},"limit":{"type":"integer","default":25,"minimum":1,"maximum":100,"description":"Max results to return (default 25, min 1, max 100)","example":25}}}}},"/v1/social/brand-share":{"get":{"operationId":"getSocialBrandShare","summary":"Share of social conversation by brand","description":"Share of social conversation by brand inside a category, with movement. `mentions` is the event count and is the comparison currency; `views` is view-weighted reach and is reported SEPARATELY. share_pct is computed on mentions, never on views - Instagram stills report no plays, so view-weighting renders active subcategories as 0%. `category` is required: there is no default aisle, because inheriting one would sell a department-wide number under an aisle-shaped label. Each row carries `rank`, its position in the category by mentions - emitted ONLY on an unfiltered request, because with `brand` set the page is one row and any ordinal on it would be meaningless. A row may also carry `tied_with`, the 1-based positions of other rows within 5% of its mention count: that is PAIRWISE proximity, not an equivalence class, so A near B and B near C does not make A near C. `organic_only` filters to posts the provider did not mark as an ad (`isAd` on TikTok, `paidPartnership` on Instagram); each slice is its own denominator, so shares within it sum to 100 rather than to the organic share of the whole, and a post whose ad status is unknown is counted in neither slice. The rollup publishes category-level rows only.","tags":["Social"],"x-faremeter-pricing":{"rates":{"solana-usdc":"30000","base-usdc":"30000","tempo-usdc":"30000"},"rules":[{"match":"$","capture":"1"}]},"x-payment-info":{"amount":"30000","currency":"0x20c000000000000000000000b9537d11c60e8b50","description":"Social signals query - $0.03 per request","intent":"charge","method":"tempo","methods":[{"method":"tempo","intent":"charge","currency":"0x20c000000000000000000000b9537d11c60e8b50","decimals":6,"amount":"30000","settlement":"Tempo Allegro USDC.e","role":"primary"}],"price":{"mode":"fixed","currency":"USD","amount":"0.030000"},"protocols":[{"x402":{}},{"mpp":{"method":"tempo","intent":"charge","currency":"USDC","amount":"30000","recipient":"0xe2e662cF219025AFC0C9Bf850b6a2B0a0b5517fe"}}]},"x-sla":{"p50_ms":150,"p99_ms":500,"freshness_seconds_max":1209600,"idempotency":"safe","cache_hint":"public"},"x-retry-policy":{"min_backoff_seconds":2,"max_backoff_seconds":30,"max_attempts":4,"jitter_required":true,"idempotency_safe":true},"parameters":[{"name":"category","in":"query","required":true,"schema":{"type":"string"},"example":"grocery-gourmet-food","description":"Category root slug (department, not aisle)."},{"name":"window","in":"query","required":false,"schema":{"type":"string","enum":["7d","30d","90d"],"default":"30d"},"description":"Rollup window. Only published windows are accepted."},{"name":"platform","in":"query","required":false,"schema":{"type":"string","enum":["all","tiktok","instagram"],"default":"all"},"description":"TikTok and Instagram are the only platforms in the corpus."},{"name":"organic_only","in":"query","required":false,"schema":{"type":"boolean","default":false},"description":"Exclude posts marked as ads."},{"name":"brand","in":"query","required":false,"schema":{"type":"string","minLength":1},"description":"Brand name (e.g., Sony, Samsung, Nike)","example":"Apple"},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","default":25,"minimum":1,"maximum":100},"description":"Max results to return (default 25, min 1, max 100)","example":25}],"responses":{"200":{"description":"Brand share of conversation","content":{"application/json":{"schema":{"type":"object","properties":{"category":{"type":"string"},"subcategory":{"type":"string","nullable":true,"description":"Always null. The rollup publishes category-level rows only."},"axis":{"type":"string","enum":["category"],"description":"Always category. The subcategory axis is unpublished."},"brand":{"type":"string","nullable":true},"window_days":{"type":"integer"},"platform":{"type":"string"},"organic_only":{"type":"boolean"},"brands":{"type":"array","items":{"type":"object","additionalProperties":true}},"siblings":{"type":"array","items":{"type":"object","additionalProperties":true}},"noise_pct":{"type":"number","nullable":true},"coverage":{"type":"object","description":"How much data backed this answer. `sufficient` is false when the slice is too thin to read as a market statement; the count is always reported so you can judge for yourself, and `note` explains an empty or thin result rather than leaving you to infer it.","properties":{"products":{"type":"integer","example":42},"sufficient":{"type":"boolean","example":true},"note":{"type":"string"},"unpublished_note":{"type":"string","description":"Names columns that came back null on EVERY row because the publish job writes them unpopulated, not because the subjects lack the attribute. Never infer a zero or an absence from a column named here."},"sku_note":{"type":"string","description":"Present when `skus` is null on every row returned. Read the column as unavailable for this run, not as a stocking fact."},"rank_note":{"type":"string","description":"Present when brands carry `tied_with`. Says how many, and that the tie list is pairwise proximity rather than an equivalence class."}},"additionalProperties":true},"freshness":{"type":"object","description":"How current the underlying observations are. `observedThrough` is the newest observation behind this answer; `staleHours` is its age. Both null when nothing was observed.","properties":{"observedThrough":{"type":"string","format":"date-time","nullable":true},"staleHours":{"type":"number","nullable":true,"example":6.5}},"additionalProperties":true},"snapshot":{"type":"object","additionalProperties":true,"nullable":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), 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), or NOT_PUBLISHED (a social rollup the current publish run does not compute yet — a gap in what we publish, not a finding about the category). 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","description":"Category root slug (department, not aisle).","example":"grocery-gourmet-food"},"window":{"type":"string","enum":["7d","30d","90d"],"default":"30d","description":"Rollup window. Only published windows are accepted."},"platform":{"type":"string","enum":["all","tiktok","instagram"],"default":"all","description":"TikTok and Instagram are the only platforms in the corpus."},"organic_only":{"type":"boolean","default":false,"description":"Exclude posts marked as ads."},"brand":{"type":"string","minLength":1,"description":"Brand name (e.g., Sony, Samsung, Nike)","example":"Apple"},"limit":{"type":"integer","default":25,"minimum":1,"maximum":100,"description":"Max results to return (default 25, min 1, max 100)","example":25}}}}},"/v1/social/category-structure":{"get":{"operationId":"getSocialCategoryStructure","summary":"Show which subcategories own a category's conversation","description":"Which subcategories own a category's conversation, and how concentrated it is: mentions, share, growth, the leading brand, top-2 concentration, and the share of mentions carried by a single creator. A creator_top_pct at or above 60 means one voice carries the subcategory, which is a different fact from a brand leading it. `thin_base` marks rows whose prior-period base was too small for the growth figure to mean anything - a 900% rise from two mentions is arithmetic, not a trend, and the flag says so rather than letting the number stand alone.","tags":["Social"],"x-faremeter-pricing":{"rates":{"solana-usdc":"30000","base-usdc":"30000","tempo-usdc":"30000"},"rules":[{"match":"$","capture":"1"}]},"x-payment-info":{"amount":"30000","currency":"0x20c000000000000000000000b9537d11c60e8b50","description":"Social signals query - $0.03 per request","intent":"charge","method":"tempo","methods":[{"method":"tempo","intent":"charge","currency":"0x20c000000000000000000000b9537d11c60e8b50","decimals":6,"amount":"30000","settlement":"Tempo Allegro USDC.e","role":"primary"}],"price":{"mode":"fixed","currency":"USD","amount":"0.030000"},"protocols":[{"x402":{}},{"mpp":{"method":"tempo","intent":"charge","currency":"USDC","amount":"30000","recipient":"0xe2e662cF219025AFC0C9Bf850b6a2B0a0b5517fe"}}]},"x-sla":{"p50_ms":150,"p99_ms":500,"freshness_seconds_max":1209600,"idempotency":"safe","cache_hint":"public"},"x-retry-policy":{"min_backoff_seconds":2,"max_backoff_seconds":30,"max_attempts":4,"jitter_required":true,"idempotency_safe":true},"parameters":[{"name":"category","in":"query","required":true,"schema":{"type":"string"},"example":"grocery-gourmet-food","description":"Category root slug (department, not aisle)."},{"name":"window","in":"query","required":false,"schema":{"type":"string","enum":["7d","30d","90d"],"default":"30d"},"description":"Rollup window. Only published windows are accepted."},{"name":"platform","in":"query","required":false,"schema":{"type":"string","enum":["all","tiktok","instagram"],"default":"all"},"description":"TikTok and Instagram are the only platforms in the corpus."},{"name":"organic_only","in":"query","required":false,"schema":{"type":"boolean","default":false},"description":"Exclude posts marked as ads."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","default":25,"minimum":1,"maximum":100},"description":"Max results to return (default 25, min 1, max 100)","example":25}],"responses":{"200":{"description":"Category structure","content":{"application/json":{"schema":{"type":"object","properties":{"category":{"type":"string"},"window_days":{"type":"integer"},"platform":{"type":"string"},"organic_only":{"type":"boolean"},"subcategories":{"type":"array","items":{"type":"object","additionalProperties":true}},"noise_pct":{"type":"number","nullable":true},"coverage":{"type":"object","description":"How much data backed this answer. `sufficient` is false when the slice is too thin to read as a market statement; the count is always reported so you can judge for yourself, and `note` explains an empty or thin result rather than leaving you to infer it.","properties":{"products":{"type":"integer","example":42},"sufficient":{"type":"boolean","example":true},"note":{"type":"string"},"unpublished_note":{"type":"string","description":"Names columns that came back null on EVERY row because the publish job writes them unpopulated, not because the subjects lack the attribute. Never infer a zero or an absence from a column named here."},"sku_note":{"type":"string","description":"Present when `skus` is null on every row returned. Read the column as unavailable for this run, not as a stocking fact."},"rank_note":{"type":"string","description":"Present when brands carry `tied_with`. Says how many, and that the tie list is pairwise proximity rather than an equivalence class."}},"additionalProperties":true},"freshness":{"type":"object","description":"How current the underlying observations are. `observedThrough` is the newest observation behind this answer; `staleHours` is its age. Both null when nothing was observed.","properties":{"observedThrough":{"type":"string","format":"date-time","nullable":true},"staleHours":{"type":"number","nullable":true,"example":6.5}},"additionalProperties":true},"snapshot":{"type":"object","additionalProperties":true,"nullable":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), 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), or NOT_PUBLISHED (a social rollup the current publish run does not compute yet — a gap in what we publish, not a finding about the category). 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","description":"Category root slug (department, not aisle).","example":"grocery-gourmet-food"},"window":{"type":"string","enum":["7d","30d","90d"],"default":"30d","description":"Rollup window. Only published windows are accepted."},"platform":{"type":"string","enum":["all","tiktok","instagram"],"default":"all","description":"TikTok and Instagram are the only platforms in the corpus."},"organic_only":{"type":"boolean","default":false,"description":"Exclude posts marked as ads."},"limit":{"type":"integer","default":25,"minimum":1,"maximum":100,"description":"Max results to return (default 25, min 1, max 100)","example":25}}}}},"/v1/social/brand-momentum":{"get":{"operationId":"getBrandMomentum","summary":"Rank brands by conversation momentum in a category","description":"Brands ranked by MOVEMENT in a category's conversation — new entrants first, then the biggest risers and fallers by mention growth. This is the trend view over the same rows brand-share ranks by volume: one dataset, two questions, deliberately not two copies. Each row carries its prior-window base and a `thin_base` flag; `thin_base_rows` on the response counts them, because a 900% rise from two mentions is arithmetic, not a trend. Pass `status=new` for emerging-brand detection (brands appearing in the conversation with no prior-window presence), `rising` or `falling` to filter direction.","tags":["Social"],"x-faremeter-pricing":{"rates":{"solana-usdc":"30000","base-usdc":"30000","tempo-usdc":"30000"},"rules":[{"match":"$","capture":"1"}]},"x-payment-info":{"amount":"30000","currency":"0x20c000000000000000000000b9537d11c60e8b50","description":"Social signals query - $0.03 per request","intent":"charge","method":"tempo","methods":[{"method":"tempo","intent":"charge","currency":"0x20c000000000000000000000b9537d11c60e8b50","decimals":6,"amount":"30000","settlement":"Tempo Allegro USDC.e","role":"primary"}],"price":{"mode":"fixed","currency":"USD","amount":"0.030000"},"protocols":[{"x402":{}},{"mpp":{"method":"tempo","intent":"charge","currency":"USDC","amount":"30000","recipient":"0xe2e662cF219025AFC0C9Bf850b6a2B0a0b5517fe"}}]},"x-sla":{"p50_ms":150,"p99_ms":500,"freshness_seconds_max":1209600,"idempotency":"safe","cache_hint":"public"},"x-retry-policy":{"min_backoff_seconds":2,"max_backoff_seconds":30,"max_attempts":4,"jitter_required":true,"idempotency_safe":true},"parameters":[{"name":"category","in":"query","required":true,"schema":{"type":"string"},"example":"grocery-gourmet-food","description":"Category root slug (department, not aisle)."},{"name":"window","in":"query","required":false,"schema":{"type":"string","enum":["7d","30d","90d"],"default":"30d"},"description":"Rollup window. Only published windows are accepted."},{"name":"platform","in":"query","required":false,"schema":{"type":"string","enum":["all","tiktok","instagram"],"default":"all"},"description":"TikTok and Instagram are the only platforms in the corpus."},{"name":"organic_only","in":"query","required":false,"schema":{"type":"boolean","default":false},"description":"Exclude posts marked as ads."},{"name":"status","in":"query","required":false,"schema":{"type":"string","enum":["new","rising","falling","all"],"default":"all"},"description":"Restrict to one movement class. `new` = emerging-brand detection."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","default":25,"minimum":1,"maximum":100},"description":"Max results to return (default 25, min 1, max 100)","example":25}],"responses":{"200":{"description":"Brand momentum","content":{"application/json":{"schema":{"type":"object","properties":{"category":{"type":"string"},"subcategory":{"type":"string","nullable":true,"description":"Always null. The rollup publishes category-level rows only."},"window_days":{"type":"integer"},"platform":{"type":"string"},"organic_only":{"type":"boolean"},"status":{"type":"string"},"thin_base_rows":{"type":"integer"},"brands":{"type":"array","items":{"type":"object","additionalProperties":true}},"noise_pct":{"type":"number","nullable":true},"coverage":{"type":"object","description":"How much data backed this answer. `sufficient` is false when the slice is too thin to read as a market statement; the count is always reported so you can judge for yourself, and `note` explains an empty or thin result rather than leaving you to infer it.","properties":{"products":{"type":"integer","example":42},"sufficient":{"type":"boolean","example":true},"note":{"type":"string"},"unpublished_note":{"type":"string","description":"Names columns that came back null on EVERY row because the publish job writes them unpopulated, not because the subjects lack the attribute. Never infer a zero or an absence from a column named here."},"sku_note":{"type":"string","description":"Present when `skus` is null on every row returned. Read the column as unavailable for this run, not as a stocking fact."},"rank_note":{"type":"string","description":"Present when brands carry `tied_with`. Says how many, and that the tie list is pairwise proximity rather than an equivalence class."}},"additionalProperties":true},"freshness":{"type":"object","description":"How current the underlying observations are. `observedThrough` is the newest observation behind this answer; `staleHours` is its age. Both null when nothing was observed.","properties":{"observedThrough":{"type":"string","format":"date-time","nullable":true},"staleHours":{"type":"number","nullable":true,"example":6.5}},"additionalProperties":true},"snapshot":{"type":"object","additionalProperties":true,"nullable":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), 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), or NOT_PUBLISHED (a social rollup the current publish run does not compute yet — a gap in what we publish, not a finding about the category). 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","description":"Category root slug (department, not aisle).","example":"grocery-gourmet-food"},"window":{"type":"string","enum":["7d","30d","90d"],"default":"30d","description":"Rollup window. Only published windows are accepted."},"platform":{"type":"string","enum":["all","tiktok","instagram"],"default":"all","description":"TikTok and Instagram are the only platforms in the corpus."},"organic_only":{"type":"boolean","default":false,"description":"Exclude posts marked as ads."},"status":{"type":"string","enum":["new","rising","falling","all"],"default":"all","description":"Restrict to one movement class. `new` = emerging-brand detection."},"limit":{"type":"integer","default":25,"minimum":1,"maximum":100,"description":"Max results to return (default 25, min 1, max 100)","example":25}}}}},"/v1/social/topic-trends":{"get":{"operationId":"getTopicTrends","summary":"Emerging conversation topics in a category","description":"Emerging and shifting conversation topics inside a category: theme, the product types it spans, post volume, view-weighted reach, growth against the prior window, and a status of new, rising, falling or flat. Topics come from the corpus enrichment's theme extraction — market fact, not a tenant view. Ranked emergence-first: new themes, then the biggest movers, then volume. `thin_base` discloses rows whose prior base is too small for the growth figure to mean anything.","tags":["Social"],"x-faremeter-pricing":{"rates":{"solana-usdc":"30000","base-usdc":"30000","tempo-usdc":"30000"},"rules":[{"match":"$","capture":"1"}]},"x-payment-info":{"amount":"30000","currency":"0x20c000000000000000000000b9537d11c60e8b50","description":"Social signals query - $0.03 per request","intent":"charge","method":"tempo","methods":[{"method":"tempo","intent":"charge","currency":"0x20c000000000000000000000b9537d11c60e8b50","decimals":6,"amount":"30000","settlement":"Tempo Allegro USDC.e","role":"primary"}],"price":{"mode":"fixed","currency":"USD","amount":"0.030000"},"protocols":[{"x402":{}},{"mpp":{"method":"tempo","intent":"charge","currency":"USDC","amount":"30000","recipient":"0xe2e662cF219025AFC0C9Bf850b6a2B0a0b5517fe"}}]},"x-sla":{"p50_ms":150,"p99_ms":500,"freshness_seconds_max":1209600,"idempotency":"safe","cache_hint":"public"},"x-retry-policy":{"min_backoff_seconds":2,"max_backoff_seconds":30,"max_attempts":4,"jitter_required":true,"idempotency_safe":true},"parameters":[{"name":"category","in":"query","required":true,"schema":{"type":"string"},"example":"grocery-gourmet-food","description":"Category root slug (department, not aisle)."},{"name":"window","in":"query","required":false,"schema":{"type":"string","enum":["7d","30d","90d"],"default":"30d"},"description":"Rollup window. Only published windows are accepted."},{"name":"platform","in":"query","required":false,"schema":{"type":"string","enum":["all","tiktok","instagram"],"default":"all"},"description":"TikTok and Instagram are the only platforms in the corpus."},{"name":"organic_only","in":"query","required":false,"schema":{"type":"boolean","default":false},"description":"Exclude posts marked as ads."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","default":25,"minimum":1,"maximum":100},"description":"Max results to return (default 25, min 1, max 100)","example":25}],"responses":{"200":{"description":"Topic trends","content":{"application/json":{"schema":{"type":"object","properties":{"category":{"type":"string"},"window_days":{"type":"integer"},"platform":{"type":"string"},"organic_only":{"type":"boolean"},"thin_base_rows":{"type":"integer"},"topics":{"type":"array","items":{"type":"object","additionalProperties":true}},"noise_pct":{"type":"number","nullable":true},"coverage":{"type":"object","description":"How much data backed this answer. `sufficient` is false when the slice is too thin to read as a market statement; the count is always reported so you can judge for yourself, and `note` explains an empty or thin result rather than leaving you to infer it.","properties":{"products":{"type":"integer","example":42},"sufficient":{"type":"boolean","example":true},"note":{"type":"string"},"unpublished_note":{"type":"string","description":"Names columns that came back null on EVERY row because the publish job writes them unpopulated, not because the subjects lack the attribute. Never infer a zero or an absence from a column named here."},"sku_note":{"type":"string","description":"Present when `skus` is null on every row returned. Read the column as unavailable for this run, not as a stocking fact."},"rank_note":{"type":"string","description":"Present when brands carry `tied_with`. Says how many, and that the tie list is pairwise proximity rather than an equivalence class."}},"additionalProperties":true},"freshness":{"type":"object","description":"How current the underlying observations are. `observedThrough` is the newest observation behind this answer; `staleHours` is its age. Both null when nothing was observed.","properties":{"observedThrough":{"type":"string","format":"date-time","nullable":true},"staleHours":{"type":"number","nullable":true,"example":6.5}},"additionalProperties":true},"snapshot":{"type":"object","additionalProperties":true,"nullable":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), 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), or NOT_PUBLISHED (a social rollup the current publish run does not compute yet — a gap in what we publish, not a finding about the category). 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","description":"Category root slug (department, not aisle).","example":"grocery-gourmet-food"},"window":{"type":"string","enum":["7d","30d","90d"],"default":"30d","description":"Rollup window. Only published windows are accepted."},"platform":{"type":"string","enum":["all","tiktok","instagram"],"default":"all","description":"TikTok and Instagram are the only platforms in the corpus."},"organic_only":{"type":"boolean","default":false,"description":"Exclude posts marked as ads."},"limit":{"type":"integer","default":25,"minimum":1,"maximum":100,"description":"Max results to return (default 25, min 1, max 100)","example":25}}}}},"/v1/social/product-type-trends":{"get":{"operationId":"getProductTypeTrends","summary":"Attention by product type within a category","description":"Attention by product type within a category: which types own the conversation and how that mix is shifting. `share_pct` is the type's share of MENTION COUNTS in scope — the same mention-not-view rule every social endpoint holds, because Instagram stills report no plays. Movement fields (growth, is_new, thin_base) follow the same conventions as brand-momentum.","tags":["Social"],"x-faremeter-pricing":{"rates":{"solana-usdc":"30000","base-usdc":"30000","tempo-usdc":"30000"},"rules":[{"match":"$","capture":"1"}]},"x-payment-info":{"amount":"30000","currency":"0x20c000000000000000000000b9537d11c60e8b50","description":"Social signals query - $0.03 per request","intent":"charge","method":"tempo","methods":[{"method":"tempo","intent":"charge","currency":"0x20c000000000000000000000b9537d11c60e8b50","decimals":6,"amount":"30000","settlement":"Tempo Allegro USDC.e","role":"primary"}],"price":{"mode":"fixed","currency":"USD","amount":"0.030000"},"protocols":[{"x402":{}},{"mpp":{"method":"tempo","intent":"charge","currency":"USDC","amount":"30000","recipient":"0xe2e662cF219025AFC0C9Bf850b6a2B0a0b5517fe"}}]},"x-sla":{"p50_ms":150,"p99_ms":500,"freshness_seconds_max":1209600,"idempotency":"safe","cache_hint":"public"},"x-retry-policy":{"min_backoff_seconds":2,"max_backoff_seconds":30,"max_attempts":4,"jitter_required":true,"idempotency_safe":true},"parameters":[{"name":"category","in":"query","required":true,"schema":{"type":"string"},"example":"beauty-personal-care","description":"Category root slug (department, not aisle)."},{"name":"window","in":"query","required":false,"schema":{"type":"string","enum":["7d","30d","90d"],"default":"30d"},"description":"Rollup window. Only published windows are accepted."},{"name":"platform","in":"query","required":false,"schema":{"type":"string","enum":["all","tiktok","instagram"],"default":"all"},"description":"TikTok and Instagram are the only platforms in the corpus."},{"name":"organic_only","in":"query","required":false,"schema":{"type":"boolean","default":false},"description":"Exclude posts marked as ads."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","default":25,"minimum":1,"maximum":100},"description":"Max results to return (default 25, min 1, max 100)","example":25}],"responses":{"200":{"description":"Product type trends","content":{"application/json":{"schema":{"type":"object","properties":{"category":{"type":"string"},"subcategory":{"type":"string","nullable":true,"description":"Always null. The rollup publishes category-level rows only."},"window_days":{"type":"integer"},"platform":{"type":"string"},"organic_only":{"type":"boolean"},"thin_base_rows":{"type":"integer"},"product_types":{"type":"array","items":{"type":"object","additionalProperties":true}},"noise_pct":{"type":"number","nullable":true},"coverage":{"type":"object","description":"How much data backed this answer. `sufficient` is false when the slice is too thin to read as a market statement; the count is always reported so you can judge for yourself, and `note` explains an empty or thin result rather than leaving you to infer it.","properties":{"products":{"type":"integer","example":42},"sufficient":{"type":"boolean","example":true},"note":{"type":"string"},"unpublished_note":{"type":"string","description":"Names columns that came back null on EVERY row because the publish job writes them unpopulated, not because the subjects lack the attribute. Never infer a zero or an absence from a column named here."},"sku_note":{"type":"string","description":"Present when `skus` is null on every row returned. Read the column as unavailable for this run, not as a stocking fact."},"rank_note":{"type":"string","description":"Present when brands carry `tied_with`. Says how many, and that the tie list is pairwise proximity rather than an equivalence class."}},"additionalProperties":true},"freshness":{"type":"object","description":"How current the underlying observations are. `observedThrough` is the newest observation behind this answer; `staleHours` is its age. Both null when nothing was observed.","properties":{"observedThrough":{"type":"string","format":"date-time","nullable":true},"staleHours":{"type":"number","nullable":true,"example":6.5}},"additionalProperties":true},"snapshot":{"type":"object","additionalProperties":true,"nullable":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), 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), or NOT_PUBLISHED (a social rollup the current publish run does not compute yet — a gap in what we publish, not a finding about the category). 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","description":"Category root slug (department, not aisle).","example":"beauty-personal-care"},"window":{"type":"string","enum":["7d","30d","90d"],"default":"30d","description":"Rollup window. Only published windows are accepted."},"platform":{"type":"string","enum":["all","tiktok","instagram"],"default":"all","description":"TikTok and Instagram are the only platforms in the corpus."},"organic_only":{"type":"boolean","default":false,"description":"Exclude posts marked as ads."},"limit":{"type":"integer","default":25,"minimum":1,"maximum":100,"description":"Max results to return (default 25, min 1, max 100)","example":25}}}}},"/v1/social/series":{"get":{"operationId":"getSocialSeries","summary":"Weekly mentions/views time series for one subject","description":"Weekly mentions and views time series for one subject — a brand or a category — for charting and modelling. Weeks, not days: the corpus refresh is weekly, and a daily grain would imply precision the pipeline does not have. Coverage counts the WEEKS the series actually has and says so; a 4-week series answering a 26-week request is disclosed, never padded.","tags":["Social"],"x-faremeter-pricing":{"rates":{"solana-usdc":"30000","base-usdc":"30000","tempo-usdc":"30000"},"rules":[{"match":"$","capture":"1"}]},"x-payment-info":{"amount":"30000","currency":"0x20c000000000000000000000b9537d11c60e8b50","description":"Social signals query - $0.03 per request","intent":"charge","method":"tempo","methods":[{"method":"tempo","intent":"charge","currency":"0x20c000000000000000000000b9537d11c60e8b50","decimals":6,"amount":"30000","settlement":"Tempo Allegro USDC.e","role":"primary"}],"price":{"mode":"fixed","currency":"USD","amount":"0.030000"},"protocols":[{"x402":{}},{"mpp":{"method":"tempo","intent":"charge","currency":"USDC","amount":"30000","recipient":"0xe2e662cF219025AFC0C9Bf850b6a2B0a0b5517fe"}}]},"x-sla":{"p50_ms":150,"p99_ms":500,"freshness_seconds_max":1209600,"idempotency":"safe","cache_hint":"public"},"x-retry-policy":{"min_backoff_seconds":2,"max_backoff_seconds":30,"max_attempts":4,"jitter_required":true,"idempotency_safe":true},"parameters":[{"name":"subject_kind","in":"query","required":false,"schema":{"type":"string","enum":["brand","category"],"default":"brand"},"description":"What kind of subject to chart. Brand or category only."},{"name":"subject","in":"query","required":false,"schema":{"type":"string"},"example":"olipop","description":"The subject key (brand_key). Required unless subject_kind=category, where it defaults to `category`."},{"name":"category","in":"query","required":true,"schema":{"type":"string"},"example":"grocery-gourmet-food","description":"Category root slug the subject is scoped to (department, not aisle)."},{"name":"platform","in":"query","required":false,"schema":{"type":"string","enum":["all","tiktok","instagram"],"default":"all"},"description":"TikTok and Instagram are the only platforms in the corpus."},{"name":"organic_only","in":"query","required":false,"schema":{"type":"boolean","default":false},"description":"Exclude posts marked as ads."},{"name":"weeks","in":"query","required":false,"schema":{"type":"integer","default":26,"minimum":1,"maximum":104},"description":"How many trailing ISO weeks to return."}],"responses":{"200":{"description":"Social series","content":{"application/json":{"schema":{"type":"object","properties":{"subject_kind":{"type":"string"},"subject":{"type":"string"},"category":{"type":"string"},"platform":{"type":"string"},"organic_only":{"type":"boolean"},"weeks":{"type":"integer"},"series":{"type":"array","items":{"type":"object","additionalProperties":true}},"coverage":{"type":"object","description":"How much data backed this answer. `sufficient` is false when the slice is too thin to read as a market statement; the count is always reported so you can judge for yourself, and `note` explains an empty or thin result rather than leaving you to infer it.","properties":{"products":{"type":"integer","example":42},"sufficient":{"type":"boolean","example":true},"note":{"type":"string"},"unpublished_note":{"type":"string","description":"Names columns that came back null on EVERY row because the publish job writes them unpopulated, not because the subjects lack the attribute. Never infer a zero or an absence from a column named here."},"sku_note":{"type":"string","description":"Present when `skus` is null on every row returned. Read the column as unavailable for this run, not as a stocking fact."},"rank_note":{"type":"string","description":"Present when brands carry `tied_with`. Says how many, and that the tie list is pairwise proximity rather than an equivalence class."}},"additionalProperties":true},"freshness":{"type":"object","description":"How current the underlying observations are. `observedThrough` is the newest observation behind this answer; `staleHours` is its age. Both null when nothing was observed.","properties":{"observedThrough":{"type":"string","format":"date-time","nullable":true},"staleHours":{"type":"number","nullable":true,"example":6.5}},"additionalProperties":true},"snapshot":{"type":"object","additionalProperties":true,"nullable":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), 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), or NOT_PUBLISHED (a social rollup the current publish run does not compute yet — a gap in what we publish, not a finding about the category). 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":{"subject_kind":{"type":"string","enum":["brand","category"],"default":"brand","description":"What kind of subject to chart. Brand or category only."},"subject":{"type":"string","description":"The subject key (brand_key). Required unless subject_kind=category, where it defaults to `category`.","example":"olipop"},"category":{"type":"string","description":"Category root slug the subject is scoped to (department, not aisle).","example":"grocery-gourmet-food"},"platform":{"type":"string","enum":["all","tiktok","instagram"],"default":"all","description":"TikTok and Instagram are the only platforms in the corpus."},"organic_only":{"type":"boolean","default":false,"description":"Exclude posts marked as ads."},"weeks":{"type":"integer","default":26,"minimum":1,"maximum":104,"description":"How many trailing ISO weeks to return."}}}}},"/v1/social/attention-vs-shelf":{"get":{"operationId":"getAttentionVsShelf","summary":"Rank brands by share-of-conversation vs share-of-shelf gap","description":"Brands ranked by the GAP between share of social conversation and share of shelf inside one category. Over-indexed attention with under-distribution is the ranging signal a retail buyer wants and the deck slide a challenger brand wants - one endpoint, two customer types. Requires BOTH corpora bound to the same category axis and the same brand key, which is why nobody holding one of them can reproduce it. The join is on brand KEY, never on name: a row whose key is absent from the other side is dropped and COUNTED in `unmatched`, because matching by name mislabels a real brand as under-distributed. Carries TWO coverage blocks and TWO freshness values - social counts mention subjects on a weekly refresh, shelf counts products on a daily one, and merging either pair would be a lie with a familiar shape. `shelf_brands_not_in_conversation` is the mirror finding: stocked and unspoken of.","tags":["Social"],"x-faremeter-pricing":{"rates":{"solana-usdc":"50000","base-usdc":"50000","tempo-usdc":"50000"},"rules":[{"match":"$","capture":"1"}]},"x-payment-info":{"amount":"50000","currency":"0x20c000000000000000000000b9537d11c60e8b50","description":"Cross-domain scout query (social x shelf) - $0.05 per request","intent":"charge","method":"tempo","methods":[{"method":"tempo","intent":"charge","currency":"0x20c000000000000000000000b9537d11c60e8b50","decimals":6,"amount":"50000","settlement":"Tempo Allegro USDC.e","role":"primary"}],"price":{"mode":"fixed","currency":"USD","amount":"0.050000"},"protocols":[{"x402":{}},{"mpp":{"method":"tempo","intent":"charge","currency":"USDC","amount":"50000","recipient":"0xe2e662cF219025AFC0C9Bf850b6a2B0a0b5517fe"}}]},"x-sla":{"p50_ms":400,"p99_ms":2000,"freshness_seconds_max":1209600,"idempotency":"safe","cache_hint":"public"},"x-retry-policy":{"min_backoff_seconds":5,"max_backoff_seconds":120,"max_attempts":3,"jitter_required":true,"idempotency_safe":true},"parameters":[{"name":"category","in":"query","required":true,"schema":{"type":"string"},"example":"grocery-gourmet-food","description":"Category root slug (department, not aisle). No wildcard: these answers are ranked comparisons."},{"name":"country","in":"query","required":false,"schema":{"type":"string","enum":["us","ca"],"default":"us"},"description":"Country for the SHELF side of the join."},{"name":"window","in":"query","required":false,"schema":{"type":"string","enum":["7d","30d","90d"],"default":"30d"},"description":"Rollup window. Only published windows are accepted."},{"name":"platform","in":"query","required":false,"schema":{"type":"string","enum":["all","tiktok","instagram"],"default":"all"},"description":"TikTok and Instagram are the only platforms in the corpus."},{"name":"organic_only","in":"query","required":false,"schema":{"type":"boolean","default":false},"description":"Exclude posts marked as ads."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","default":25,"minimum":1,"maximum":100},"description":"Maximum ranked brands to return."}],"responses":{"200":{"description":"Attention vs shelf ranking","content":{"application/json":{"schema":{"type":"object","properties":{"category":{"type":"string"},"country":{"type":"string"},"currency":{"type":"string"},"window_days":{"type":"integer"},"platform":{"type":"string"},"organic_only":{"type":"boolean"},"brands":{"type":"array","items":{"type":"object","additionalProperties":true}},"corpus_mentions":{"type":"integer","description":"The conversation the shares divide up. A share of 40 mentions is not the same kind of fact as a share of 40,000."},"thin_corpus":{"type":"string","description":"Present when the whole category's corpus is below the depth floor: the ranking is arithmetic, not a market signal."},"unmatched":{"type":"object","additionalProperties":true,"description":"Rows dropped per side because their brand key has no counterpart. Counted, never fuzzy-matched."},"coverage":{"type":"object","additionalProperties":true,"description":"TWO blocks — social counts mention subjects, shelf counts products. Never merged."},"freshness":{"type":"object","additionalProperties":true,"description":"TWO values — weekly social, daily serving. Never the max."},"snapshot":{"type":"object","additionalProperties":true,"nullable":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), 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), or NOT_PUBLISHED (a social rollup the current publish run does not compute yet — a gap in what we publish, not a finding about the category). 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","description":"Category root slug (department, not aisle). No wildcard: these answers are ranked comparisons.","example":"grocery-gourmet-food"},"country":{"type":"string","enum":["us","ca"],"default":"us","description":"Country for the SHELF side of the join."},"window":{"type":"string","enum":["7d","30d","90d"],"default":"30d","description":"Rollup window. Only published windows are accepted."},"platform":{"type":"string","enum":["all","tiktok","instagram"],"default":"all","description":"TikTok and Instagram are the only platforms in the corpus."},"organic_only":{"type":"boolean","default":false,"description":"Exclude posts marked as ads."},"limit":{"type":"integer","default":25,"minimum":1,"maximum":100,"description":"Maximum ranked brands to return."}}}}},"/v1/social/launch-buzz":{"get":{"operationId":"getLaunchBuzz","summary":"New shelf arrivals vs the conversation around their brand","description":"New shelf arrivals in the window set against the conversation around their brand: which launches landed with traction and which landed in silence. SILENT LAUNCHES ARE RETURNED, FLAGGED - most launches are silent, so filtering them out answers a different and much less useful question. Mentions are BRAND-level in the window, not per SKU: the corpus resolves conversation to brands, and the field is named so the number cannot be read as proof anyone discussed that specific product. First-seen is the earliest observation of the product in the requested country - so rows flagged `new_store` are first observations of a STORE that entered observation inside the window (stores onboard in waves, and a new store's whole catalog gets a first observation at once). Those are catalog backfill wearing the shape of a launch: flagged rather than filtered, counted in `new_store_launches`, and not to be reported as product launches.","tags":["Social"],"x-faremeter-pricing":{"rates":{"solana-usdc":"50000","base-usdc":"50000","tempo-usdc":"50000"},"rules":[{"match":"$","capture":"1"}]},"x-payment-info":{"amount":"50000","currency":"0x20c000000000000000000000b9537d11c60e8b50","description":"Cross-domain scout query (social x shelf) - $0.05 per request","intent":"charge","method":"tempo","methods":[{"method":"tempo","intent":"charge","currency":"0x20c000000000000000000000b9537d11c60e8b50","decimals":6,"amount":"50000","settlement":"Tempo Allegro USDC.e","role":"primary"}],"price":{"mode":"fixed","currency":"USD","amount":"0.050000"},"protocols":[{"x402":{}},{"mpp":{"method":"tempo","intent":"charge","currency":"USDC","amount":"50000","recipient":"0xe2e662cF219025AFC0C9Bf850b6a2B0a0b5517fe"}}]},"x-sla":{"p50_ms":400,"p99_ms":2000,"freshness_seconds_max":1209600,"idempotency":"safe","cache_hint":"public"},"x-retry-policy":{"min_backoff_seconds":5,"max_backoff_seconds":120,"max_attempts":3,"jitter_required":true,"idempotency_safe":true},"parameters":[{"name":"category","in":"query","required":true,"schema":{"type":"string"},"example":"grocery-gourmet-food","description":"Category root slug (department, not aisle). No wildcard: these answers are ranked comparisons."},{"name":"country","in":"query","required":false,"schema":{"type":"string","enum":["us","ca"],"default":"us"},"description":"Country whose observations define first-seen."},{"name":"window","in":"query","required":false,"schema":{"type":"string","enum":["7d","30d","90d"],"default":"30d"},"description":"Arrival window. Only published windows are accepted."},{"name":"platform","in":"query","required":false,"schema":{"type":"string","enum":["all","tiktok","instagram"],"default":"all"},"description":"TikTok and Instagram are the only platforms in the corpus."},{"name":"organic_only","in":"query","required":false,"schema":{"type":"boolean","default":false},"description":"Exclude posts marked as ads."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","default":25,"minimum":1,"maximum":100},"description":"Maximum arrivals to return."}],"responses":{"200":{"description":"Launch buzz","content":{"application/json":{"schema":{"type":"object","properties":{"category":{"type":"string"},"country":{"type":"string"},"window_days":{"type":"integer"},"platform":{"type":"string"},"organic_only":{"type":"boolean"},"launches":{"type":"array","items":{"type":"object","additionalProperties":true}},"silent_launches":{"type":"integer","description":"Arrivals with zero brand conversation. A finding, not a gap: most launches are silent."},"new_store_launches":{"type":"integer","description":"Arrivals whose whole store entered observation inside the window — catalog backfill wearing the shape of a launch. Flagged per row as new_store, never filtered."},"note":{"type":"string"},"coverage":{"type":"object","additionalProperties":true,"description":"TWO blocks — social counts brands, shelf counts launches. Never merged."},"freshness":{"type":"object","additionalProperties":true,"description":"TWO values — weekly social, daily serving. Never the max."},"snapshot":{"type":"object","additionalProperties":true,"nullable":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), 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), or NOT_PUBLISHED (a social rollup the current publish run does not compute yet — a gap in what we publish, not a finding about the category). 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","description":"Category root slug (department, not aisle). No wildcard: these answers are ranked comparisons.","example":"grocery-gourmet-food"},"country":{"type":"string","enum":["us","ca"],"default":"us","description":"Country whose observations define first-seen."},"window":{"type":"string","enum":["7d","30d","90d"],"default":"30d","description":"Arrival window. Only published windows are accepted."},"platform":{"type":"string","enum":["all","tiktok","instagram"],"default":"all","description":"TikTok and Instagram are the only platforms in the corpus."},"organic_only":{"type":"boolean","default":false,"description":"Exclude posts marked as ads."},"limit":{"type":"integer","default":25,"minimum":1,"maximum":100,"description":"Maximum arrivals to return."}}}}},"/v1/analyst/price-change-leaders":{"get":{"operationId":"getPriceChangeLeaders","summary":"Rank the biggest price movers in a category or brand","description":"Per-product price-change leaderboard: the biggest droppers and gainers in a category or for a brand. Each product's change is LIKE-FOR-LIKE between two matched bands - the best price now versus the best price a window ago - over win = 7, 30 (default) or 90 days, which is the same comparison the Syntalic dashboards show. Only the two bands are scanned, never the dead middle of the window, so a product observed twice in one day cannot masquerade as a 90-day move. Changes beyond 50% in either direction are dropped as data errors rather than reported as news: a product does not fall 97% in a month, a mis-keyed price does, and it would otherwise top a list sorted by absolute change. The rising/stable/falling counts describe the WHOLE matched set the movers were drawn from, so a leaderboard can never imply more churn than the shelf actually had. DISTINCT from /v1/analyst/inflation, which is the category-level read over a quarter or longer; this is which individual SKUs moved. At least one of category or brand is required.","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},"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). Also accepts a GS1 GPC code (exactly 8 digits, e.g. '10001159') to filter by PRODUCT TYPE instead of by shelf placement — the same product type is shelved under different categories by different retailers, so a category filter answers from a fraction of the data while a GPC code spans them. Coarser codes (class/family/segment) match every brick beneath them. Resolve a phrase to a code with /v1/reference/classify?q=... ; when a code is used, resolved.match_source is 'gpc'.","example":"electronics"},{"name":"brand","in":"query","required":false,"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":"win","in":"query","required":false,"schema":{"type":"integer","enum":[7,30,90],"default":30},"description":"Comparison window in days. Only the canon bands are accepted."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","default":15,"minimum":1,"maximum":100},"description":"Max results to return (default 15, min 1, max 100)","example":15}],"responses":{"200":{"description":"Price change leaders","content":{"application/json":{"schema":{"type":"object","properties":{"category":{"type":"string","nullable":true},"brand":{"type":"string","nullable":true},"country":{"type":"string"},"currency":{"type":"string"},"win":{"type":"integer","enum":[7,30,90]},"rising":{"type":"integer"},"stable":{"type":"integer"},"falling":{"type":"integer"},"movers":{"type":"array","items":{"type":"object","properties":{"product_uid":{"type":"string"},"title":{"type":"string"},"brand":{"type":"string","nullable":true},"change_pct":{"type":"number","example":-12.5},"price_then":{"type":"number"},"price_now":{"type":"number"}}}},"coverage":{"type":"object","description":"How much data backed this answer. `sufficient` is false when the slice is too thin to read as a market statement; the count is always reported so you can judge for yourself, and `note` explains an empty or thin result rather than leaving you to infer it.","properties":{"products":{"type":"integer","example":42},"sufficient":{"type":"boolean","example":true},"note":{"type":"string"},"unpublished_note":{"type":"string","description":"Names columns that came back null on EVERY row because the publish job writes them unpopulated, not because the subjects lack the attribute. Never infer a zero or an absence from a column named here."},"sku_note":{"type":"string","description":"Present when `skus` is null on every row returned. Read the column as unavailable for this run, not as a stocking fact."},"rank_note":{"type":"string","description":"Present when brands carry `tied_with`. Says how many, and that the tie list is pairwise proximity rather than an equivalence class."}},"additionalProperties":true},"freshness":{"type":"object","description":"How current the underlying observations are. `observedThrough` is the newest observation behind this answer; `staleHours` is its age. Both null when nothing was observed.","properties":{"observedThrough":{"type":"string","format":"date-time","nullable":true},"staleHours":{"type":"number","nullable":true,"example":6.5}},"additionalProperties":true},"quality":{"type":"object","additionalProperties":true,"nullable":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), 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), or NOT_PUBLISHED (a social rollup the current publish run does not compute yet — a gap in what we publish, not a finding about the category). 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). Also accepts a GS1 GPC code (exactly 8 digits, e.g. '10001159') to filter by PRODUCT TYPE instead of by shelf placement — the same product type is shelved under different categories by different retailers, so a category filter answers from a fraction of the data while a GPC code spans them. Coarser codes (class/family/segment) match every brick beneath them. Resolve a phrase to a code with /v1/reference/classify?q=... ; when a code is used, resolved.match_source is 'gpc'.","example":"electronics"},"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"},"win":{"type":"integer","enum":[7,30,90],"default":30,"description":"Comparison window in days. Only the canon bands are accepted."},"limit":{"type":"integer","default":15,"minimum":1,"maximum":100,"description":"Max results to return (default 15, min 1, max 100)","example":15}}}}},"/v1/analyst/category-concentration":{"get":{"operationId":"getCategoryConcentration","summary":"Measure how concentrated a category is","description":"How concentrated or fragmented a category is: HHI on the standard 0-10,000 scale, CR4 (the combined share of the four largest brands), the effective number of brands, and a plain-language label. Answers 'is this category competitive or dominated', 'how many real players are there', and 'what is the market structure'. Computed over the same brand vector share-of-shelf returns, so the two answers can never disagree about who is on the shelf. The HHI bands follow the US DOJ/FTC Horizontal Merger Guidelines (under 1,500 competitive; 1,500-2,500 moderately concentrated; above 2,500 highly concentrated). Effective brands is 1/HHI expressed as a count and is fractional by nature - fifty brands where one holds 90% is not a fifty-brand market, and this reports roughly 1.2. Every metric is withheld together (all null) below five brands, because a concentration figure over three brands describes who happens to be in the catalog rather than who competes.","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},"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). Also accepts a GS1 GPC code (exactly 8 digits, e.g. '10001159') to filter by PRODUCT TYPE instead of by shelf placement — the same product type is shelved under different categories by different retailers, so a category filter answers from a fraction of the data while a GPC code spans them. Coarser codes (class/family/segment) match every brick beneath them. Resolve a phrase to a code with /v1/reference/classify?q=... ; when a code is used, resolved.match_source is 'gpc'.","example":"electronics"},{"name":"country","in":"query","required":false,"schema":{"type":"string","enum":["us","ca"],"default":"us"},"description":"Country (us or ca)","example":"us"}],"responses":{"200":{"description":"Category concentration","content":{"application/json":{"schema":{"type":"object","properties":{"category":{"type":"string"},"country":{"type":"string"},"hhi":{"type":"integer","nullable":true},"cr4":{"type":"number","nullable":true},"effective_brands":{"type":"number","nullable":true},"fragmentation":{"type":"string","nullable":true},"brand_count":{"type":"integer"},"top_shares":{"type":"array","items":{"type":"object","properties":{"brand":{"type":"string"},"share_pct":{"type":"number"}}}},"coverage":{"type":"object","description":"How much data backed this answer. `sufficient` is false when the slice is too thin to read as a market statement; the count is always reported so you can judge for yourself, and `note` explains an empty or thin result rather than leaving you to infer it.","properties":{"products":{"type":"integer","example":42},"sufficient":{"type":"boolean","example":true},"note":{"type":"string"},"unpublished_note":{"type":"string","description":"Names columns that came back null on EVERY row because the publish job writes them unpopulated, not because the subjects lack the attribute. Never infer a zero or an absence from a column named here."},"sku_note":{"type":"string","description":"Present when `skus` is null on every row returned. Read the column as unavailable for this run, not as a stocking fact."},"rank_note":{"type":"string","description":"Present when brands carry `tied_with`. Says how many, and that the tie list is pairwise proximity rather than an equivalence class."}},"additionalProperties":true},"freshness":{"type":"object","description":"How current the underlying observations are. `observedThrough` is the newest observation behind this answer; `staleHours` is its age. Both null when nothing was observed.","properties":{"observedThrough":{"type":"string","format":"date-time","nullable":true},"staleHours":{"type":"number","nullable":true,"example":6.5}},"additionalProperties":true},"quality":{"type":"object","additionalProperties":true,"nullable":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), 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), or NOT_PUBLISHED (a social rollup the current publish run does not compute yet — a gap in what we publish, not a finding about the category). 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). Also accepts a GS1 GPC code (exactly 8 digits, e.g. '10001159') to filter by PRODUCT TYPE instead of by shelf placement — the same product type is shelved under different categories by different retailers, so a category filter answers from a fraction of the data while a GPC code spans them. Coarser codes (class/family/segment) match every brick beneath them. Resolve a phrase to a code with /v1/reference/classify?q=... ; when a code is used, resolved.match_source is 'gpc'.","example":"electronics"},"country":{"type":"string","enum":["us","ca"],"default":"us","description":"Country (us or ca)","example":"us"}}}}},"/v1/marketing/availability-index":{"get":{"operationId":"getAvailabilityIndex","summary":"Measure out-of-stock rates by retailer or category","description":"Out-of-stock rate by retail chain or by category root - an on-shelf availability read rather than a pricing one. Answers 'which retailers are running out of stock', 'what is the stockout rate in this category', and 'is my brand actually on shelf'. Pivot with aggregate_by: 'seller' (default) ranks chains, 'category_root' ranks categories. The denominator is rows where availability was actually OBSERVED, never all rows: roughly 40% of listings carry no availability signal, and counting those as in-stock would report a healthy shelf whenever coverage is poor. availability_coverage reports what share of the scoped shelf carried a signal, so you can tell a genuine 5% stockout rate from one computed over a tenth of the listings. Groups with fewer than five observed rows are dropped rather than shown with a caveat - a rate from two rows is noise wearing a percentage sign. Unlike the pricing endpoints this one does NOT exclude price-flagged rows: the flag marks an untrustworthy price, not an untrustworthy listing, and dropping those rows would understate a chain's stock coverage for an unrelated reason. At least one of category or brand is required.","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":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). Also accepts a GS1 GPC code (exactly 8 digits, e.g. '10001159') to filter by PRODUCT TYPE instead of by shelf placement — the same product type is shelved under different categories by different retailers, so a category filter answers from a fraction of the data while a GPC code spans them. Coarser codes (class/family/segment) match every brick beneath them. Resolve a phrase to a code with /v1/reference/classify?q=... ; when a code is used, resolved.match_source is 'gpc'.","example":"electronics"},{"name":"brand","in":"query","required":false,"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":"aggregate_by","in":"query","required":false,"schema":{"type":"string","enum":["seller","category_root"],"default":"seller"},"description":"Dimension to group by: retail chain (default) or category root."}],"responses":{"200":{"description":"Availability index","content":{"application/json":{"schema":{"type":"object","properties":{"category":{"type":"string","nullable":true},"brand":{"type":"string","nullable":true},"country":{"type":"string"},"aggregate_by":{"type":"string","enum":["seller","category_root"]},"groups":{"type":"array","items":{"type":"object","properties":{"key":{"type":"string"},"oos_rate":{"type":"number","example":12.5},"out_of_stock_count":{"type":"integer"},"observed":{"type":"integer"}}}},"availability_coverage":{"type":"number","example":0.6},"coverage":{"type":"object","description":"How much data backed this answer. `sufficient` is false when the slice is too thin to read as a market statement; the count is always reported so you can judge for yourself, and `note` explains an empty or thin result rather than leaving you to infer it.","properties":{"products":{"type":"integer","example":42},"sufficient":{"type":"boolean","example":true},"note":{"type":"string"},"unpublished_note":{"type":"string","description":"Names columns that came back null on EVERY row because the publish job writes them unpopulated, not because the subjects lack the attribute. Never infer a zero or an absence from a column named here."},"sku_note":{"type":"string","description":"Present when `skus` is null on every row returned. Read the column as unavailable for this run, not as a stocking fact."},"rank_note":{"type":"string","description":"Present when brands carry `tied_with`. Says how many, and that the tie list is pairwise proximity rather than an equivalence class."}},"additionalProperties":true},"freshness":{"type":"object","description":"How current the underlying observations are. `observedThrough` is the newest observation behind this answer; `staleHours` is its age. Both null when nothing was observed.","properties":{"observedThrough":{"type":"string","format":"date-time","nullable":true},"staleHours":{"type":"number","nullable":true,"example":6.5}},"additionalProperties":true},"quality":{"type":"object","additionalProperties":true,"nullable":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), 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), or NOT_PUBLISHED (a social rollup the current publish run does not compute yet — a gap in what we publish, not a finding about the category). 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). Also accepts a GS1 GPC code (exactly 8 digits, e.g. '10001159') to filter by PRODUCT TYPE instead of by shelf placement — the same product type is shelved under different categories by different retailers, so a category filter answers from a fraction of the data while a GPC code spans them. Coarser codes (class/family/segment) match every brick beneath them. Resolve a phrase to a code with /v1/reference/classify?q=... ; when a code is used, resolved.match_source is 'gpc'.","example":"electronics"},"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"},"aggregate_by":{"type":"string","enum":["seller","category_root"],"default":"seller","description":"Dimension to group by: retail chain (default) or category root."}}}}},"/v1/marketing/retailer-assortment":{"get":{"operationId":"getRetailerAssortment","summary":"Find which retail chains carry a brand or category","description":"Which retail CHAINS carry a brand or a category, ranked by how many distinct priced products each lists, with that chain's average and median price. Answers 'who stocks this brand', 'where can I find it', and 'which retailers carry the most of this category'. Grouped on the retailer chain, never on the scrape lane - a lane like 'shopify' spans hundreds of storefronts, so grouping by it would answer 'which retailer' with 'shopify'. At least one of brand or category is required. Price statistics exclude rows the pipeline flagged as incoherent while the COUNTS keep them: a chain that genuinely carries the brand should not disappear because one of its prices is wrong. DISTINCT from share-of-shelf, which answers which BRANDS hold a category's shelf.","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":false,"schema":{"type":"string","minLength":1},"description":"Brand name (e.g., Sony, Samsung, Nike)","example":"Apple"},{"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). Also accepts a GS1 GPC code (exactly 8 digits, e.g. '10001159') to filter by PRODUCT TYPE instead of by shelf placement — the same product type is shelved under different categories by different retailers, so a category filter answers from a fraction of the data while a GPC code spans them. Coarser codes (class/family/segment) match every brick beneath them. Resolve a phrase to a code with /v1/reference/classify?q=... ; when a code is used, resolved.match_source is 'gpc'.","example":"electronics"},{"name":"country","in":"query","required":false,"schema":{"type":"string","enum":["us","ca"],"default":"us"},"description":"Country (us or ca)","example":"us"}],"responses":{"200":{"description":"Retailer assortment","content":{"application/json":{"schema":{"type":"object","properties":{"brand":{"type":"string","nullable":true},"category":{"type":"string","nullable":true},"country":{"type":"string"},"currency":{"type":"string"},"retailers":{"type":"array","items":{"type":"object","properties":{"seller":{"type":"string"},"product_count":{"type":"integer"},"avg_price_usd":{"type":"number","nullable":true},"median_price_usd":{"type":"number","nullable":true}}}},"coverage":{"type":"object","description":"How much data backed this answer. `sufficient` is false when the slice is too thin to read as a market statement; the count is always reported so you can judge for yourself, and `note` explains an empty or thin result rather than leaving you to infer it.","properties":{"products":{"type":"integer","example":42},"sufficient":{"type":"boolean","example":true},"note":{"type":"string"},"unpublished_note":{"type":"string","description":"Names columns that came back null on EVERY row because the publish job writes them unpopulated, not because the subjects lack the attribute. Never infer a zero or an absence from a column named here."},"sku_note":{"type":"string","description":"Present when `skus` is null on every row returned. Read the column as unavailable for this run, not as a stocking fact."},"rank_note":{"type":"string","description":"Present when brands carry `tied_with`. Says how many, and that the tie list is pairwise proximity rather than an equivalence class."}},"additionalProperties":true},"freshness":{"type":"object","description":"How current the underlying observations are. `observedThrough` is the newest observation behind this answer; `staleHours` is its age. Both null when nothing was observed.","properties":{"observedThrough":{"type":"string","format":"date-time","nullable":true},"staleHours":{"type":"number","nullable":true,"example":6.5}},"additionalProperties":true},"quality":{"type":"object","additionalProperties":true,"nullable":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), 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), or NOT_PUBLISHED (a social rollup the current publish run does not compute yet — a gap in what we publish, not a finding about the category). 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":{"brand":{"type":"string","minLength":1,"description":"Brand name (e.g., Sony, Samsung, Nike)","example":"Apple"},"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). Also accepts a GS1 GPC code (exactly 8 digits, e.g. '10001159') to filter by PRODUCT TYPE instead of by shelf placement — the same product type is shelved under different categories by different retailers, so a category filter answers from a fraction of the data while a GPC code spans them. Coarser codes (class/family/segment) match every brick beneath them. Resolve a phrase to a code with /v1/reference/classify?q=... ; when a code is used, resolved.match_source is 'gpc'.","example":"electronics"},"country":{"type":"string","enum":["us","ca"],"default":"us","description":"Country (us or ca)","example":"us"}}}}},"/v1/marketing/brand-breakdown":{"get":{"operationId":"getBrandBreakdown","summary":"Break a brand's assortment down by category","description":"What a brand actually sells: a count of its distinct priced products under each category root, ranked. Answers 'what is this brand's product mix' and 'which categories does it really compete in' - useful before a positioning or shelf question, so the comparison targets the category the brand is densest in rather than whichever one was guessed. Brand input matches case-insensitively and across normalization variants (jbl == JBL, tplink == TP-Link); placeholder brands are excluded. Counts only products carrying a current price in the requested country, so a brand present in the catalog but unpriced reads as empty coverage rather than as absent. Carries the coverage and freshness envelope: coverage.products is the total counted, and coverage.note explains an empty result rather than leaving an empty list to imply the brand sells nothing.","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"}],"responses":{"200":{"description":"Brand assortment composition","content":{"application/json":{"schema":{"type":"object","properties":{"brand":{"type":"string"},"country":{"type":"string"},"breakdown":{"type":"array","items":{"type":"object","properties":{"category_root":{"type":"string"},"product_count":{"type":"integer"}}}},"coverage":{"type":"object","description":"How much data backed this answer. `sufficient` is false when the slice is too thin to read as a market statement; the count is always reported so you can judge for yourself, and `note` explains an empty or thin result rather than leaving you to infer it.","properties":{"products":{"type":"integer","example":42},"sufficient":{"type":"boolean","example":true},"note":{"type":"string"},"unpublished_note":{"type":"string","description":"Names columns that came back null on EVERY row because the publish job writes them unpopulated, not because the subjects lack the attribute. Never infer a zero or an absence from a column named here."},"sku_note":{"type":"string","description":"Present when `skus` is null on every row returned. Read the column as unavailable for this run, not as a stocking fact."},"rank_note":{"type":"string","description":"Present when brands carry `tied_with`. Says how many, and that the tie list is pairwise proximity rather than an equivalence class."}},"additionalProperties":true},"freshness":{"type":"object","description":"How current the underlying observations are. `observedThrough` is the newest observation behind this answer; `staleHours` is its age. Both null when nothing was observed.","properties":{"observedThrough":{"type":"string","format":"date-time","nullable":true},"staleHours":{"type":"number","nullable":true,"example":6.5}},"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), 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), or NOT_PUBLISHED (a social rollup the current publish run does not compute yet — a gap in what we publish, not a finding about the category). 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"}}}}},"/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. PREFER lfl_change_pct: the like-for-like change over the whole window, computed per product between the first and last period and summarised as a trimmed mean, with lfl_matched / lfl_rising / lfl_stable / lfl_falling beside it. It is the SAME definition the Syntalic dashboards report, so an API answer and a dashboard answer agree, and it is withheld (null, with lfl_note) rather than estimated when fewer than 10 products match. The legacy chained fields remain for compatibility and are DEPRECATED: overall_change_pct chains per-period Jevons matched-pairs changes, and naive_overall_change_pct is an average-vs-average fallback that moves when the basket composition changes even if no price moved — do not treat it as inflation. 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). Also accepts a GS1 GPC code (exactly 8 digits, e.g. '10001159') to filter by PRODUCT TYPE instead of by shelf placement — the same product type is shelved under different categories by different retailers, so a category filter answers from a fraction of the data while a GPC code spans them. Coarser codes (class/family/segment) match every brick beneath them. Resolve a phrase to a code with /v1/reference/classify?q=... ; when a code is used, resolved.match_source is 'gpc'. 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), 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), or NOT_PUBLISHED (a social rollup the current publish run does not compute yet — a gap in what we publish, not a finding about the category). 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). Also accepts a GS1 GPC code (exactly 8 digits, e.g. '10001159') to filter by PRODUCT TYPE instead of by shelf placement — the same product type is shelved under different categories by different retailers, so a category filter answers from a fraction of the data while a GPC code spans them. Coarser codes (class/family/segment) match every brick beneath them. Resolve a phrase to a code with /v1/reference/classify?q=... ; when a code is used, resolved.match_source is 'gpc'. 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). Also accepts a GS1 GPC code (exactly 8 digits, e.g. '10001159') to filter by PRODUCT TYPE instead of by shelf placement — the same product type is shelved under different categories by different retailers, so a category filter answers from a fraction of the data while a GPC code spans them. Coarser codes (class/family/segment) match every brick beneath them. Resolve a phrase to a code with /v1/reference/classify?q=... ; when a code is used, resolved.match_source is 'gpc'. 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"},"price_histogram":{"type":"array","description":"Equal-width buckets over the SAME products the percentiles describe, so the counts sum to product_count. Eight buckets spanning min_price..max_price; the top bucket's upper edge is inclusive. A category where every product shares one price returns a single bucket. Per-product prices are not served — the distribution answers the question without shipping the priced catalogue.","items":{"type":"object","properties":{"bin":{"type":"string","description":"Bucket range label, e.g. \"12.5–24.0\""},"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), 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), or NOT_PUBLISHED (a social rollup the current publish run does not compute yet — a gap in what we publish, not a finding about the category). 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). Also accepts a GS1 GPC code (exactly 8 digits, e.g. '10001159') to filter by PRODUCT TYPE instead of by shelf placement — the same product type is shelved under different categories by different retailers, so a category filter answers from a fraction of the data while a GPC code spans them. Coarser codes (class/family/segment) match every brick beneath them. Resolve a phrase to a code with /v1/reference/classify?q=... ; when a code is used, resolved.match_source is 'gpc'. 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). Also accepts a GS1 GPC code (exactly 8 digits, e.g. '10001159') to filter by PRODUCT TYPE instead of by shelf placement — the same product type is shelved under different categories by different retailers, so a category filter answers from a fraction of the data while a GPC code spans them. Coarser codes (class/family/segment) match every brick beneath them. Resolve a phrase to a code with /v1/reference/classify?q=... ; when a code is used, resolved.match_source is 'gpc'. 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), 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), or NOT_PUBLISHED (a social rollup the current publish run does not compute yet — a gap in what we publish, not a finding about the category). 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). Also accepts a GS1 GPC code (exactly 8 digits, e.g. '10001159') to filter by PRODUCT TYPE instead of by shelf placement — the same product type is shelved under different categories by different retailers, so a category filter answers from a fraction of the data while a GPC code spans them. Coarser codes (class/family/segment) match every brick beneath them. Resolve a phrase to a code with /v1/reference/classify?q=... ; when a code is used, resolved.match_source is 'gpc'. 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/price-bands":{"get":{"operationId":"getPriceBands","summary":"Price band and tiers for a category node","description":"The price architecture of one shelf: the comparability window that defines 'similarly priced' there, and the shelf's price tiers. Scoped by ladder NODE (a category path like 'electronics/headphones'), because a band is a property of one shelf. The window is derived in log space from the shelf's own robust spread over a 90-day window, so it is relative rather than a fixed dollar range - tight where a shelf clusters (video-game accessories run ±10%), wide where it spreads (car-care tools run ±60%). Tiers are equal-population, so 'premium' means the same thing on a $5-$40 shelf and a $400-$4,000 one. A shelf with too few products to define a distribution inherits its parent's window (disclosed in band.inherited_from) with the tier ladder re-centred on its own median; a shelf where a fifth of products share one price reports fewer than five tiers rather than an empty one.","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},"parameters":[{"name":"node","in":"query","required":true,"schema":{"type":"string"},"description":"Ladder node as a category path — 'electronics', 'electronics/headphones', or a deeper rung.","example":"electronics/headphones"},{"name":"brand","in":"query","required":false,"schema":{"type":"string","minLength":1},"description":"Optional. Locate one brand within the tiers: each tier gains brand_products, the count of that brand's products in it. Omit for the market view.","example":"Apple"}],"responses":{"200":{"description":"Price band","content":{"application/json":{"schema":{"type":"object","properties":{"node":{"type":"string"},"level":{"type":"string","enum":["root","l2","l3","l4"]},"products":{"type":"integer"},"price_range":{"type":"object","properties":{"p05":{"type":"number","nullable":true},"median":{"type":"number","nullable":true},"p95":{"type":"number","nullable":true}}},"band":{"type":"object","properties":{"half_width_pct":{"type":"number"},"example":{"type":"object","nullable":true,"properties":{"price":{"type":"number"},"lower":{"type":"number"},"upper":{"type":"number"}}},"inherited_from":{"type":"string","nullable":true}}},"tiers":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string","enum":["entry","value","mid","premium","luxury"]},"upper_bound":{"type":"number","nullable":true},"from":{"type":"number","nullable":true},"to":{"type":"number","nullable":true},"products":{"type":"integer"},"brand_products":{"type":"integer"}}}}}}}}},"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), 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), or NOT_PUBLISHED (a social rollup the current publish run does not compute yet — a gap in what we publish, not a finding about the category). 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":["node"],"properties":{"node":{"type":"string","description":"Ladder node as a category path — 'electronics', 'electronics/headphones', or a deeper rung.","example":"electronics/headphones"},"brand":{"type":"string","minLength":1,"description":"Optional. Locate one brand within the tiers: each tier gains brand_products, the count of that brand's products in it. Omit for the market view.","example":"Apple"}}}}},"/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). Also accepts a GS1 GPC code (exactly 8 digits, e.g. '10001159') to filter by PRODUCT TYPE instead of by shelf placement — the same product type is shelved under different categories by different retailers, so a category filter answers from a fraction of the data while a GPC code spans them. Coarser codes (class/family/segment) match every brick beneath them. Resolve a phrase to a code with /v1/reference/classify?q=... ; when a code is used, resolved.match_source is 'gpc'. 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), 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), or NOT_PUBLISHED (a social rollup the current publish run does not compute yet — a gap in what we publish, not a finding about the category). 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). Also accepts a GS1 GPC code (exactly 8 digits, e.g. '10001159') to filter by PRODUCT TYPE instead of by shelf placement — the same product type is shelved under different categories by different retailers, so a category filter answers from a fraction of the data while a GPC code spans them. Coarser codes (class/family/segment) match every brick beneath them. Resolve a phrase to a code with /v1/reference/classify?q=... ; when a code is used, resolved.match_source is 'gpc'. 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/reference/classify":{"get":{"operationId":"classifyBrowseNodes","summary":"Map Amazon browse node ids to GS1 GPC codes","description":"Map Amazon browse node ids or product-type phrases to GS1 GPC codes. Accepts up to 100 comma-separated browse_id values or q phrases per request (not both). Each browse result carries GPC ancestry, match_precision (SKOS-style), match_source (self | inherited), assurance_state, and browse_node { name, path, in_serving_catalog }. Unmapped ids come back with gpc: null so the response lines up 1:1 with the request. Phrase results are certain-or-blank: a hit is always curated. A class-level hit (e.g. coffee → 50202600) includes forms[] — the child bricks; ask the user which form if they need a leaf, or pass the class code as category= (it matches every brick beneath). An empty gpc list always includes miss { reason, detail, hint, try, candidates }. reason is unmatched_phrase, or ambiguous when several GPC types share the head (fish → prepared vs raw). hint is built from this query; try is nearby lexicon phrases; candidates are competing type identities (code + title), not keyword hits like fish oil. Do not treat empty gpc as 'give up' — read miss and either retry or ask which type. Version-pinned: X-GPC-Release and X-Map-Version, not X-Data-Freshness-Hours.","tags":["Reference"],"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":"Taxonomy reference lookup - $0.01 per request, up to 100 ids","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":40,"p99_ms":150,"freshness_seconds_max":0,"idempotency":"safe","cache_hint":"public"},"x-retry-policy":{"min_backoff_seconds":1,"max_backoff_seconds":15,"max_attempts":5,"jitter_required":true,"idempotency_safe":true},"parameters":[{"name":"browse_id","in":"query","required":false,"schema":{"type":"string","pattern":"^\\d{1,20}(,\\d{1,20})*$"},"description":"Comma-separated Amazon browse node ids (max 100 per request). Provide either browse_id or q, not both.","example":"300334,12899121"},{"name":"q","in":"query","required":false,"schema":{"type":"string"},"description":"Comma-separated product-type phrases to resolve to GPC bricks or classes via the curated lexicon, e.g. 'protein bars' or 'coffee'. Max 100 per request. Certain-or-blank: a phrase the lexicon does not carry returns an empty gpc list plus miss { reason, detail, hint, try, candidates }, never a nearest guess. A class hit includes forms[]. Provide either browse_id or q, not both.","example":"protein bars,laptops"}],"responses":{"200":{"description":"Browse node to GPC mappings","content":{"application/json":{"schema":{"type":"object","properties":{"results":{"type":"array","items":{"type":"object","properties":{"browse_id":{"type":"string"},"browse_node":{"type":"object","description":"Amazon browse node label. name/path are null when taxonomy_nodes is unpublished or the id is unknown.","properties":{"browse_id":{"type":"string"},"name":{"type":"string","nullable":true},"path":{"type":"string","nullable":true},"in_serving_catalog":{"type":"boolean"}}},"gpc":{"type":"object","nullable":true,"description":"The matched GS1 GPC node and its ancestry. null when the id has no mapping.","properties":{"code":{"type":"string"},"title":{"type":"string"},"level":{"type":"string","enum":["brick","class","family","segment"]},"segment":{"type":"string","nullable":true},"family":{"type":"string","nullable":true},"class":{"type":"string","nullable":true},"brick":{"type":"string","nullable":true}}},"match_precision":{"type":"string","nullable":true},"match_source":{"type":"string","nullable":true},"inherited_from":{"type":"string","nullable":true},"assurance_state":{"type":"string","nullable":true},"attribute_count":{"type":"integer"},"miss":{"type":"object","nullable":true,"description":"Present iff phrase classify returned an empty gpc list. reason is a closed enum. Read hint/try/candidates instead of giving up.","properties":{"reason":{"type":"string","enum":["need_type","unmatched_phrase","ambiguous","out_of_scope"]},"detail":{"type":"string"},"hint":{"type":"string"},"try":{"type":"array","items":{"type":"string"},"description":"Lexicon phrases to retry. Not a type guess; gpc is still empty."},"candidates":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string"},"title":{"type":"string"},"level":{"type":"string"}}},"description":"Competing GPC type identities when the head is a homograph. Ask which type; do not pick one."}}},"forms":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string"},"title":{"type":"string"},"level":{"type":"string"}}},"description":"Child bricks when the hit is a class. Offer as 'which form?' or pass the class code as category=."}}}},"gpc_release":{"type":"string","example":"v20260520"},"schema_version":{"type":"string","example":"v3"}}}}}},"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), 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), or NOT_PUBLISHED (a social rollup the current publish run does not compute yet — a gap in what we publish, not a finding about the category). 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":{"browse_id":{"type":"string","pattern":"^\\d{1,20}(,\\d{1,20})*$","description":"Comma-separated Amazon browse node ids (max 100 per request). Provide either browse_id or q, not both.","example":"300334,12899121"},"q":{"type":"string","description":"Comma-separated product-type phrases to resolve to GPC bricks or classes via the curated lexicon, e.g. 'protein bars' or 'coffee'. Max 100 per request. Certain-or-blank: a phrase the lexicon does not carry returns an empty gpc list plus miss { reason, detail, hint, try, candidates }, never a nearest guess. A class hit includes forms[]. Provide either browse_id or q, not both.","example":"protein bars,laptops"}}}}},"/v1/reference/reverse":{"get":{"operationId":"reverseGpcLookup","summary":"Map GS1 GPC codes back to Amazon browse nodes","description":"Reverse the crosswalk: given GS1 GPC codes, return the Amazon browse nodes mapped onto them. Accepts up to 100 comma-separated gpc_code values. browse_node_count is the true total per code; browse_ids is capped per code (see ids_per_code_cap in the response) because a coarse segment can carry thousands of nodes and an uncapped batch would be enormous. browse_nodes is the same list with name, path, and in_serving_catalog when taxonomy_nodes is published (null name/path until the next serving swap). Codes with no mapped nodes return an empty list rather than being omitted.","tags":["Reference"],"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":"Taxonomy reference lookup - $0.01 per request, up to 100 ids","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":40,"p99_ms":150,"freshness_seconds_max":0,"idempotency":"safe","cache_hint":"public"},"x-retry-policy":{"min_backoff_seconds":1,"max_backoff_seconds":15,"max_attempts":5,"jitter_required":true,"idempotency_safe":true},"parameters":[{"name":"gpc_code","in":"query","required":true,"schema":{"type":"string","pattern":"^\\d{8}(,\\d{8})*$"},"description":"Comma-separated 8-digit GS1 GPC codes (max 100 per request)","example":"10001159,10000025"}],"responses":{"200":{"description":"GPC to browse node mappings","content":{"application/json":{"schema":{"type":"object","properties":{"results":{"type":"array","items":{"type":"object","properties":{"gpc_code":{"type":"string"},"gpc":{"type":"object","nullable":true,"description":"The matched GS1 GPC node and its ancestry. null when the id has no mapping.","properties":{"code":{"type":"string"},"title":{"type":"string"},"level":{"type":"string","enum":["brick","class","family","segment"]},"segment":{"type":"string","nullable":true},"family":{"type":"string","nullable":true},"class":{"type":"string","nullable":true},"brick":{"type":"string","nullable":true}}},"browse_node_count":{"type":"integer"},"browse_ids":{"type":"array","items":{"type":"string"}},"browse_nodes":{"type":"array","items":{"type":"object","description":"Amazon browse node label. name/path are null when taxonomy_nodes is unpublished or the id is unknown.","properties":{"browse_id":{"type":"string"},"name":{"type":"string","nullable":true},"path":{"type":"string","nullable":true},"in_serving_catalog":{"type":"boolean"}}}}}}},"ids_per_code_cap":{"type":"integer"},"gpc_release":{"type":"string","example":"v20260520"},"schema_version":{"type":"string","example":"v3"}}}}}},"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), 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), or NOT_PUBLISHED (a social rollup the current publish run does not compute yet — a gap in what we publish, not a finding about the category). 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":["gpc_code"],"properties":{"gpc_code":{"type":"string","pattern":"^\\d{8}(,\\d{8})*$","description":"Comma-separated 8-digit GS1 GPC codes (max 100 per request)","example":"10001159,10000025"}}}}},"/v1/reference/brick-attributes":{"get":{"operationId":"getGpcBrickAttributes","summary":"GS1 GPC attribute schema for one or more bricks","description":"Return the GPC attribute schema for one or more bricks - attribute names and their allowed value sets. Accepts up to 100 comma-separated gpc_code values. Use this to discover which attributes GS1 defines for a product category (for example Formation, If Organic) and the controlled vocabulary each one permits. Bricks that define no attributes return an empty attributes array.","tags":["Reference"],"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":"Taxonomy reference lookup - $0.01 per request, up to 100 ids","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":40,"p99_ms":150,"freshness_seconds_max":0,"idempotency":"safe","cache_hint":"public"},"x-retry-policy":{"min_backoff_seconds":1,"max_backoff_seconds":15,"max_attempts":5,"jitter_required":true,"idempotency_safe":true},"parameters":[{"name":"gpc_code","in":"query","required":true,"schema":{"type":"string","pattern":"^\\d{8}(,\\d{8})*$"},"description":"Comma-separated 8-digit GS1 GPC brick codes (max 100 per request)","example":"10000002"}],"responses":{"200":{"description":"GPC brick attribute schemas","content":{"application/json":{"schema":{"type":"object","properties":{"results":{"type":"array","items":{"type":"object","properties":{"gpc_code":{"type":"string"},"gpc":{"type":"object","nullable":true,"description":"The matched GS1 GPC node and its ancestry. null when the id has no mapping.","properties":{"code":{"type":"string"},"title":{"type":"string"},"level":{"type":"string","enum":["brick","class","family","segment"]},"segment":{"type":"string","nullable":true},"family":{"type":"string","nullable":true},"class":{"type":"string","nullable":true},"brick":{"type":"string","nullable":true}}},"attributes":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"allowed_values":{"type":"array","items":{"type":"string"}},"value_count":{"type":"integer"}}}}}}},"gpc_release":{"type":"string","example":"v20260520"},"schema_version":{"type":"string","example":"v3"}}}}}},"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), 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), or NOT_PUBLISHED (a social rollup the current publish run does not compute yet — a gap in what we publish, not a finding about the category). 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":["gpc_code"],"properties":{"gpc_code":{"type":"string","pattern":"^\\d{8}(,\\d{8})*$","description":"Comma-separated 8-digit GS1 GPC brick codes (max 100 per request)","example":"10000002"}}}}}},"components":{"schemas":{"GetOpenApiSpecInput":{"type":"object","additionalProperties":false,"properties":{}},"GetPublicStatsInput":{"type":"object","additionalProperties":false,"properties":{}},"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}}},"ListPublicRetailersInput":{"type":"object","additionalProperties":false,"properties":{"limit":{"type":"integer","default":100,"minimum":1,"maximum":500,"description":"Max results to return (default 100, min 1, max 500)","example":100},"offset":{"type":"integer","default":0,"minimum":0,"description":"Pagination offset","example":0}}},"ListPublicBrandsInput":{"type":"object","additionalProperties":false,"properties":{"q":{"type":"string","minLength":1,"description":"Prefix match on the normalized brand key (case/punctuation-insensitive)","example":"sam"},"limit":{"type":"integer","default":100,"minimum":1,"maximum":500,"description":"Max results to return (default 100, min 1, max 500)","example":100},"offset":{"type":"integer","default":0,"minimum":0,"description":"Pagination offset","example":0}}},"ListPublicCoverageInput":{"type":"object","additionalProperties":false,"properties":{"country":{"type":"string","enum":["us","ca"],"description":"Filter to a country","example":"us"},"platform":{"type":"string","description":"Filter to a platform (e.g. amazon, walmart)","example":"walmart"},"category_root":{"type":"string","description":"Filter to a top-level category","example":"electronics"},"quality_status":{"type":"string","enum":["serving","thin","stale"],"description":"Filter to a coverage tier","example":"serving"},"limit":{"type":"integer","default":200,"minimum":1,"maximum":1000,"description":"Max results to return (default 200, min 1, max 1000)","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":{"brand":{"type":"string","minLength":1,"description":"Brand name (e.g., Sony, Samsung, Nike)","example":"Apple"},"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). Also accepts a GS1 GPC code (exactly 8 digits, e.g. '10001159') to filter by PRODUCT TYPE instead of by shelf placement — the same product type is shelved under different categories by different retailers, so a category filter answers from a fraction of the data while a GPC code spans them. Coarser codes (class/family/segment) match every brick beneath them. Resolve a phrase to a code with /v1/reference/classify?q=... ; when a code is used, resolved.match_source is 'gpc'.","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). Also accepts a GS1 GPC code (exactly 8 digits, e.g. '10001159') to filter by PRODUCT TYPE instead of by shelf placement — the same product type is shelved under different categories by different retailers, so a category filter answers from a fraction of the data while a GPC code spans them. Coarser codes (class/family/segment) match every brick beneath them. Resolve a phrase to a code with /v1/reference/classify?q=... ; when a code is used, resolved.match_source is 'gpc'.","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). Also accepts a GS1 GPC code (exactly 8 digits, e.g. '10001159') to filter by PRODUCT TYPE instead of by shelf placement — the same product type is shelved under different categories by different retailers, so a category filter answers from a fraction of the data while a GPC code spans them. Coarser codes (class/family/segment) match every brick beneath them. Resolve a phrase to a code with /v1/reference/classify?q=... ; when a code is used, resolved.match_source is 'gpc'.","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). Also accepts a GS1 GPC code (exactly 8 digits, e.g. '10001159') to filter by PRODUCT TYPE instead of by shelf placement — the same product type is shelved under different categories by different retailers, so a category filter answers from a fraction of the data while a GPC code spans them. Coarser codes (class/family/segment) match every brick beneath them. Resolve a phrase to a code with /v1/reference/classify?q=... ; when a code is used, resolved.match_source is 'gpc'.","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). Also accepts a GS1 GPC code (exactly 8 digits, e.g. '10001159') to filter by PRODUCT TYPE instead of by shelf placement — the same product type is shelved under different categories by different retailers, so a category filter answers from a fraction of the data while a GPC code spans them. Coarser codes (class/family/segment) match every brick beneath them. Resolve a phrase to a code with /v1/reference/classify?q=... ; when a code is used, resolved.match_source is 'gpc'.","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"}}},"GetCreatorIndexInput":{"type":"object","additionalProperties":false,"required":["category"],"properties":{"category":{"type":"string","description":"Category root slug (department, not aisle).","example":"grocery-gourmet-food"},"window":{"type":"string","enum":["7d","30d","90d"],"default":"30d","description":"Rollup window. Only published windows are accepted."},"platform":{"type":"string","enum":["all","tiktok","instagram"],"default":"all","description":"TikTok and Instagram are the only platforms in the corpus."},"organic_only":{"type":"boolean","default":false,"description":"Exclude posts marked as ads."},"limit":{"type":"integer","default":25,"minimum":1,"maximum":100,"description":"Max results to return (default 25, min 1, max 100)","example":25}}},"GetSocialBrandShareInput":{"type":"object","additionalProperties":false,"required":["category"],"properties":{"category":{"type":"string","description":"Category root slug (department, not aisle).","example":"grocery-gourmet-food"},"window":{"type":"string","enum":["7d","30d","90d"],"default":"30d","description":"Rollup window. Only published windows are accepted."},"platform":{"type":"string","enum":["all","tiktok","instagram"],"default":"all","description":"TikTok and Instagram are the only platforms in the corpus."},"organic_only":{"type":"boolean","default":false,"description":"Exclude posts marked as ads."},"brand":{"type":"string","minLength":1,"description":"Brand name (e.g., Sony, Samsung, Nike)","example":"Apple"},"limit":{"type":"integer","default":25,"minimum":1,"maximum":100,"description":"Max results to return (default 25, min 1, max 100)","example":25}}},"GetSocialCategoryStructureInput":{"type":"object","additionalProperties":false,"required":["category"],"properties":{"category":{"type":"string","description":"Category root slug (department, not aisle).","example":"grocery-gourmet-food"},"window":{"type":"string","enum":["7d","30d","90d"],"default":"30d","description":"Rollup window. Only published windows are accepted."},"platform":{"type":"string","enum":["all","tiktok","instagram"],"default":"all","description":"TikTok and Instagram are the only platforms in the corpus."},"organic_only":{"type":"boolean","default":false,"description":"Exclude posts marked as ads."},"limit":{"type":"integer","default":25,"minimum":1,"maximum":100,"description":"Max results to return (default 25, min 1, max 100)","example":25}}},"GetBrandMomentumInput":{"type":"object","additionalProperties":false,"required":["category"],"properties":{"category":{"type":"string","description":"Category root slug (department, not aisle).","example":"grocery-gourmet-food"},"window":{"type":"string","enum":["7d","30d","90d"],"default":"30d","description":"Rollup window. Only published windows are accepted."},"platform":{"type":"string","enum":["all","tiktok","instagram"],"default":"all","description":"TikTok and Instagram are the only platforms in the corpus."},"organic_only":{"type":"boolean","default":false,"description":"Exclude posts marked as ads."},"status":{"type":"string","enum":["new","rising","falling","all"],"default":"all","description":"Restrict to one movement class. `new` = emerging-brand detection."},"limit":{"type":"integer","default":25,"minimum":1,"maximum":100,"description":"Max results to return (default 25, min 1, max 100)","example":25}}},"GetTopicTrendsInput":{"type":"object","additionalProperties":false,"required":["category"],"properties":{"category":{"type":"string","description":"Category root slug (department, not aisle).","example":"grocery-gourmet-food"},"window":{"type":"string","enum":["7d","30d","90d"],"default":"30d","description":"Rollup window. Only published windows are accepted."},"platform":{"type":"string","enum":["all","tiktok","instagram"],"default":"all","description":"TikTok and Instagram are the only platforms in the corpus."},"organic_only":{"type":"boolean","default":false,"description":"Exclude posts marked as ads."},"limit":{"type":"integer","default":25,"minimum":1,"maximum":100,"description":"Max results to return (default 25, min 1, max 100)","example":25}}},"GetProductTypeTrendsInput":{"type":"object","additionalProperties":false,"required":["category"],"properties":{"category":{"type":"string","description":"Category root slug (department, not aisle).","example":"beauty-personal-care"},"window":{"type":"string","enum":["7d","30d","90d"],"default":"30d","description":"Rollup window. Only published windows are accepted."},"platform":{"type":"string","enum":["all","tiktok","instagram"],"default":"all","description":"TikTok and Instagram are the only platforms in the corpus."},"organic_only":{"type":"boolean","default":false,"description":"Exclude posts marked as ads."},"limit":{"type":"integer","default":25,"minimum":1,"maximum":100,"description":"Max results to return (default 25, min 1, max 100)","example":25}}},"GetSocialSeriesInput":{"type":"object","additionalProperties":false,"required":["category"],"properties":{"subject_kind":{"type":"string","enum":["brand","category"],"default":"brand","description":"What kind of subject to chart. Brand or category only."},"subject":{"type":"string","description":"The subject key (brand_key). Required unless subject_kind=category, where it defaults to `category`.","example":"olipop"},"category":{"type":"string","description":"Category root slug the subject is scoped to (department, not aisle).","example":"grocery-gourmet-food"},"platform":{"type":"string","enum":["all","tiktok","instagram"],"default":"all","description":"TikTok and Instagram are the only platforms in the corpus."},"organic_only":{"type":"boolean","default":false,"description":"Exclude posts marked as ads."},"weeks":{"type":"integer","default":26,"minimum":1,"maximum":104,"description":"How many trailing ISO weeks to return."}}},"GetAttentionVsShelfInput":{"type":"object","additionalProperties":false,"required":["category"],"properties":{"category":{"type":"string","description":"Category root slug (department, not aisle). No wildcard: these answers are ranked comparisons.","example":"grocery-gourmet-food"},"country":{"type":"string","enum":["us","ca"],"default":"us","description":"Country for the SHELF side of the join."},"window":{"type":"string","enum":["7d","30d","90d"],"default":"30d","description":"Rollup window. Only published windows are accepted."},"platform":{"type":"string","enum":["all","tiktok","instagram"],"default":"all","description":"TikTok and Instagram are the only platforms in the corpus."},"organic_only":{"type":"boolean","default":false,"description":"Exclude posts marked as ads."},"limit":{"type":"integer","default":25,"minimum":1,"maximum":100,"description":"Maximum ranked brands to return."}}},"GetLaunchBuzzInput":{"type":"object","additionalProperties":false,"required":["category"],"properties":{"category":{"type":"string","description":"Category root slug (department, not aisle). No wildcard: these answers are ranked comparisons.","example":"grocery-gourmet-food"},"country":{"type":"string","enum":["us","ca"],"default":"us","description":"Country whose observations define first-seen."},"window":{"type":"string","enum":["7d","30d","90d"],"default":"30d","description":"Arrival window. Only published windows are accepted."},"platform":{"type":"string","enum":["all","tiktok","instagram"],"default":"all","description":"TikTok and Instagram are the only platforms in the corpus."},"organic_only":{"type":"boolean","default":false,"description":"Exclude posts marked as ads."},"limit":{"type":"integer","default":25,"minimum":1,"maximum":100,"description":"Maximum arrivals to return."}}},"GetPriceChangeLeadersInput":{"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). Also accepts a GS1 GPC code (exactly 8 digits, e.g. '10001159') to filter by PRODUCT TYPE instead of by shelf placement — the same product type is shelved under different categories by different retailers, so a category filter answers from a fraction of the data while a GPC code spans them. Coarser codes (class/family/segment) match every brick beneath them. Resolve a phrase to a code with /v1/reference/classify?q=... ; when a code is used, resolved.match_source is 'gpc'.","example":"electronics"},"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"},"win":{"type":"integer","enum":[7,30,90],"default":30,"description":"Comparison window in days. Only the canon bands are accepted."},"limit":{"type":"integer","default":15,"minimum":1,"maximum":100,"description":"Max results to return (default 15, min 1, max 100)","example":15}}},"GetCategoryConcentrationInput":{"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). Also accepts a GS1 GPC code (exactly 8 digits, e.g. '10001159') to filter by PRODUCT TYPE instead of by shelf placement — the same product type is shelved under different categories by different retailers, so a category filter answers from a fraction of the data while a GPC code spans them. Coarser codes (class/family/segment) match every brick beneath them. Resolve a phrase to a code with /v1/reference/classify?q=... ; when a code is used, resolved.match_source is 'gpc'.","example":"electronics"},"country":{"type":"string","enum":["us","ca"],"default":"us","description":"Country (us or ca)","example":"us"}}},"GetAvailabilityIndexInput":{"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). Also accepts a GS1 GPC code (exactly 8 digits, e.g. '10001159') to filter by PRODUCT TYPE instead of by shelf placement — the same product type is shelved under different categories by different retailers, so a category filter answers from a fraction of the data while a GPC code spans them. Coarser codes (class/family/segment) match every brick beneath them. Resolve a phrase to a code with /v1/reference/classify?q=... ; when a code is used, resolved.match_source is 'gpc'.","example":"electronics"},"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"},"aggregate_by":{"type":"string","enum":["seller","category_root"],"default":"seller","description":"Dimension to group by: retail chain (default) or category root."}}},"GetRetailerAssortmentInput":{"type":"object","additionalProperties":false,"properties":{"brand":{"type":"string","minLength":1,"description":"Brand name (e.g., Sony, Samsung, Nike)","example":"Apple"},"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). Also accepts a GS1 GPC code (exactly 8 digits, e.g. '10001159') to filter by PRODUCT TYPE instead of by shelf placement — the same product type is shelved under different categories by different retailers, so a category filter answers from a fraction of the data while a GPC code spans them. Coarser codes (class/family/segment) match every brick beneath them. Resolve a phrase to a code with /v1/reference/classify?q=... ; when a code is used, resolved.match_source is 'gpc'.","example":"electronics"},"country":{"type":"string","enum":["us","ca"],"default":"us","description":"Country (us or ca)","example":"us"}}},"GetBrandBreakdownInput":{"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"}}},"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). Also accepts a GS1 GPC code (exactly 8 digits, e.g. '10001159') to filter by PRODUCT TYPE instead of by shelf placement — the same product type is shelved under different categories by different retailers, so a category filter answers from a fraction of the data while a GPC code spans them. Coarser codes (class/family/segment) match every brick beneath them. Resolve a phrase to a code with /v1/reference/classify?q=... ; when a code is used, resolved.match_source is 'gpc'. 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). Also accepts a GS1 GPC code (exactly 8 digits, e.g. '10001159') to filter by PRODUCT TYPE instead of by shelf placement — the same product type is shelved under different categories by different retailers, so a category filter answers from a fraction of the data while a GPC code spans them. Coarser codes (class/family/segment) match every brick beneath them. Resolve a phrase to a code with /v1/reference/classify?q=... ; when a code is used, resolved.match_source is 'gpc'. 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). Also accepts a GS1 GPC code (exactly 8 digits, e.g. '10001159') to filter by PRODUCT TYPE instead of by shelf placement — the same product type is shelved under different categories by different retailers, so a category filter answers from a fraction of the data while a GPC code spans them. Coarser codes (class/family/segment) match every brick beneath them. Resolve a phrase to a code with /v1/reference/classify?q=... ; when a code is used, resolved.match_source is 'gpc'. 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"]}]},"GetPriceBandsInput":{"type":"object","additionalProperties":false,"required":["node"],"properties":{"node":{"type":"string","description":"Ladder node as a category path — 'electronics', 'electronics/headphones', or a deeper rung.","example":"electronics/headphones"},"brand":{"type":"string","minLength":1,"description":"Optional. Locate one brand within the tiers: each tier gains brand_products, the count of that brand's products in it. Omit for the market view.","example":"Apple"}}},"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). Also accepts a GS1 GPC code (exactly 8 digits, e.g. '10001159') to filter by PRODUCT TYPE instead of by shelf placement — the same product type is shelved under different categories by different retailers, so a category filter answers from a fraction of the data while a GPC code spans them. Coarser codes (class/family/segment) match every brick beneath them. Resolve a phrase to a code with /v1/reference/classify?q=... ; when a code is used, resolved.match_source is 'gpc'. 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"]}]},"ClassifyBrowseNodesInput":{"type":"object","additionalProperties":false,"properties":{"browse_id":{"type":"string","pattern":"^\\d{1,20}(,\\d{1,20})*$","description":"Comma-separated Amazon browse node ids (max 100 per request). Provide either browse_id or q, not both.","example":"300334,12899121"},"q":{"type":"string","description":"Comma-separated product-type phrases to resolve to GPC bricks or classes via the curated lexicon, e.g. 'protein bars' or 'coffee'. Max 100 per request. Certain-or-blank: a phrase the lexicon does not carry returns an empty gpc list plus miss { reason, detail, hint, try, candidates }, never a nearest guess. A class hit includes forms[]. Provide either browse_id or q, not both.","example":"protein bars,laptops"}}},"ReverseGpcLookupInput":{"type":"object","additionalProperties":false,"required":["gpc_code"],"properties":{"gpc_code":{"type":"string","pattern":"^\\d{8}(,\\d{8})*$","description":"Comma-separated 8-digit GS1 GPC codes (max 100 per request)","example":"10001159,10000025"}}},"GetGpcBrickAttributesInput":{"type":"object","additionalProperties":false,"required":["gpc_code"],"properties":{"gpc_code":{"type":"string","pattern":"^\\d{8}(,\\d{8})*$","description":"Comma-separated 8-digit GS1 GPC brick codes (max 100 per request)","example":"10000002"}}}}}}