{"openapi":"3.1.0","info":{"title":"Shopograph API","version":"1.1.0","description":"The product verdict layer for AI shopping agents: honest ratings aggregated from reviews across the whole internet (saved and versioned) and the lowest verified in-stock price in the shopper's country. Send an API key as X-API-Key for higher limits."},"servers":[{"url":"https://shopograph.com"}],"components":{"securitySchemes":{"apiKey":{"type":"apiKey","in":"header","name":"X-API-Key"}}},"security":[{},{"apiKey":[]}],"paths":{"/api/v1/verdict":{"get":{"operationId":"getProductVerdict","summary":"Rating, verdict and lowest verified price for one product","description":"Call this before recommending or buying a specific product. Returns an honest 1-5 star rating aggregated from reviews across the whole internet (retailers in every country, Reddit, YouTube, forums, expert tests; corrected for fake and early reviews), BUY / MAYBE / AVOID, pros and cons, and the lowest in-stock price at stores whose product pages were just opened and verified (right model, new, real price, working link) in the shopper's country and currency. Also: price history, a similar pick if the exact item can't be bought, a better-reviewed pick if it rates poorly. Identify the product by name, by a product page url (also tells you if that listing is the cheapest), or by barcode. If prices take longer than max_wait_seconds, returns status 'pending' with a check_id for get_check.","parameters":[{"name":"q","in":"query","required":false,"schema":{"type":"string"},"description":"Product name, brand + model"},{"name":"url","in":"query","required":false,"schema":{"type":"string"},"description":"Product page link"},{"name":"gtin","in":"query","required":false,"schema":{"type":"string"},"description":"UPC/EAN/GTIN barcode"},{"name":"country","in":"query","required":false,"schema":{"type":"string"},"description":"Two-letter country code where the shopper buys (US, CA, MX, BR, GB, IE, ES, PT, FR, BE, LU, NL, DE, AT, CH, IT, GR, FI, SE, NO, DK, PL, CZ, TR, AE, SA, EG, ZA, IN, SG, JP, KR, HK, AU, NZ, AR, CL, CO, IL). Prices, stores and currency follow it. Default US."},{"name":"wait","in":"query","required":false,"schema":{"type":"number"},"description":"Seconds to wait for verified prices before returning a check_id to poll (0-110, default 50)."}],"responses":{"200":{"description":"Complete verdict"},"202":{"description":"Pending: poll /api/v1/checks/{check_id}"}}}},"/api/v1/find":{"get":{"operationId":"findProducts","summary":"Best-reviewed products for a need, with verified prices","description":"When the shopper describes a need rather than a product ('quiet robot vacuum for pet hair under $300'), returns the best-reviewed specific products for it, each with a full verdict (rating, pros/cons) and its lowest verified in-stock price in the shopper's country, ranked by rating then price.","parameters":[{"name":"need","in":"query","required":true,"schema":{"type":"string"},"description":"What the shopper needs"},{"name":"budget_max","in":"query","required":false,"schema":{"type":"number"},"description":"Max price, local currency"},{"name":"count","in":"query","required":false,"schema":{"type":"number"},"description":"1-3 (5 with key)"},{"name":"country","in":"query","required":false,"schema":{"type":"string"},"description":"Two-letter country code where the shopper buys (US, CA, MX, BR, GB, IE, ES, PT, FR, BE, LU, NL, DE, AT, CH, IT, GR, FI, SE, NO, DK, PL, CZ, TR, AE, SA, EG, ZA, IN, SG, JP, KR, HK, AU, NZ, AR, CL, CO, IL). Prices, stores and currency follow it. Default US."},{"name":"wait","in":"query","required":false,"schema":{"type":"number"},"description":"Seconds to wait for verified prices before returning a check_id to poll (0-110, default 50)."}],"responses":{"200":{"description":"Ranked results"},"202":{"description":"Pending"}}}},"/api/v1/compare":{"get":{"operationId":"compareProducts","summary":"Compare 2-4 products","description":"Compares 2-4 specific products (up to 6 with an API key): a full verdict and lowest verified price for each, plus best_rated and best_value picks with the rule used.","parameters":[{"name":"products","in":"query","required":true,"schema":{"type":"string"},"description":"Product names separated by |"},{"name":"country","in":"query","required":false,"schema":{"type":"string"},"description":"Two-letter country code where the shopper buys (US, CA, MX, BR, GB, IE, ES, PT, FR, BE, LU, NL, DE, AT, CH, IT, GR, FI, SE, NO, DK, PL, CZ, TR, AE, SA, EG, ZA, IN, SG, JP, KR, HK, AU, NZ, AR, CL, CO, IL). Prices, stores and currency follow it. Default US."},{"name":"wait","in":"query","required":false,"schema":{"type":"number"},"description":"Seconds to wait for verified prices before returning a check_id to poll (0-110, default 50)."}],"responses":{"200":{"description":"Comparison"},"202":{"description":"Pending"}}}},"/api/v1/checks/{check_id}":{"get":{"operationId":"getCheck","summary":"Result of a pending check","parameters":[{"name":"check_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Result"},"202":{"description":"Still running"}}}},"/api/v1/history":{"get":{"operationId":"getPriceHistory","summary":"Price and rating history","parameters":[{"name":"product_id","in":"query","required":true,"schema":{"type":"string"},"description":"From a verdict, e.g. us:wyze-cam-pan-v2"}],"responses":{"200":{"description":"History"}}}}}}