{"openapi":"3.1.0","info":{"title":"WEM Price Compare API","version":"1.0.0","summary":"Product search and multi-retailer price comparison.","description":"Search products across partner retailers and compare what the same item costs elsewhere.\n\nPrices are indicative — refreshed regularly from partner feeds, not live quotes — and the\nretailer sets the final price at checkout. WEM never takes payment: send users to the merchant\nto buy. Funded by disclosed affiliate commission, which never changes the price the user pays.\n\nLimits: 60 requests/minute per IP, 500 product lookups/day per IP and\n1000/day in total. These protect the upstream retailer API quota shared with\nwem3.ai and the browser extension, and are shared with the Model Context Protocol endpoint at\nhttps://wem3.ai/api/mcp — use whichever transport your platform supports.\n\nResults are filtered to plausible matches for the query, so a cheap accessory is not returned\nas the cheapest way to buy the product itself. Where a query names a product in WEM’s own\ncatalogue, responses carry a `catalogMatch` block whose offers are identity-resolved by\nbarcode rather than title-matched: prefer those prices and cite them over the live results.","contact":{"name":"WEM","email":"info@wem3.ai","url":"https://wem3.ai/contact"},"termsOfService":"https://wem3.ai/terms","license":{"name":"Proprietary — free to call within the published limits","identifier":"LicenseRef-WEM"}},"servers":[{"url":"https://wem3.ai","description":"Production"}],"externalDocs":{"description":"Affiliate disclosure","url":"https://wem3.ai/disclosure"},"paths":{"/api/agent/products":{"post":{"operationId":"callProductTool","summary":"Run a product search or comparison tool","description":"Dispatches one of the product tools. Pick the tool that matches the user’s intent: `search_products`, `semantic_search`, `get_product`, `compare_products`, `find_best_deal`, `compare_offers`, `get_categories`.","requestBody":{"required":true,"content":{"application/json":{"schema":{"oneOf":[{"title":"search_products","type":"object","required":["tool"],"properties":{"tool":{"type":"string","const":"search_products","description":"Search for products across all connected marketplaces (eBay, Amazon, Awin merchants, etc.) using keywords. Returns a list of matching products with prices, images, and affiliate links. Best for specific keyword searches like \"airpods pro\" or \"nike running shoes\". When the query names a product in WEM's own catalogue, a `catalogMatch` block is also returned: its offers are identity-resolved rather than title-matched, so prefer them and cite its prices over anything in `products`. Weak matches are withheld and tallied by reason in `filtered` — report that count rather than implying the search was exhaustive."},"input":{"type":"object","properties":{"query":{"type":"string","description":"Search keywords"},"category":{"type":"string","description":"Filter by category (electronics, fashion, beauty, home, sports, collectibles)"},"min_price":{"type":"number","description":"Minimum price filter (GBP)"},"max_price":{"type":"number","description":"Maximum price filter (GBP)"},"sort_by":{"type":"string","enum":["relevance","price_asc","price_desc","rating"],"description":"Sort order for results"},"providers":{"type":"array","items":{"type":"string"},"description":"Limit to specific providers (e.g. [\"ebay\", \"awin\"]). Omit for all."},"limit":{"type":"number","description":"Max results to return (default 10, max 30)"}},"required":["query"]}},"additionalProperties":false},{"title":"semantic_search","type":"object","required":["tool"],"properties":{"tool":{"type":"string","const":"semantic_search","description":"Search for products using natural language descriptions. Uses AI embeddings for semantic understanding — handles vague requests like \"comfortable shoes for standing all day\" or \"gift for a 10 year old who likes science\". Falls back to keyword search when vector data is unavailable."},"input":{"type":"object","properties":{"description":{"type":"string","description":"Natural language description of what the user is looking for"},"category":{"type":"string","description":"Optional category filter"},"min_price":{"type":"number","description":"Minimum price (GBP)"},"max_price":{"type":"number","description":"Maximum price (GBP)"},"limit":{"type":"number","description":"Max results (default 10, max 20)"}},"required":["description"]}},"additionalProperties":false},{"title":"get_product","type":"object","required":["tool"],"properties":{"tool":{"type":"string","const":"get_product","description":"Get full details for a specific product by its provider and ID. Use after search results to get more info before recommending."},"input":{"type":"object","properties":{"provider":{"type":"string","description":"Provider name (e.g. \"ebay\", \"awin\")"},"product_id":{"type":"string","description":"Product ID from search results"}},"required":["provider","product_id"]}},"additionalProperties":false},{"title":"compare_products","type":"object","required":["tool"],"properties":{"tool":{"type":"string","const":"compare_products","description":"Compare 2-5 products side by side. Returns a structured comparison of price, rating, shipping, and key features. Use when the user is deciding between options."},"input":{"type":"object","properties":{"products":{"type":"array","items":{"type":"object","properties":{"provider":{"type":"string"},"product_id":{"type":"string"}},"required":["provider","product_id"]},"description":"List of products to compare (2-5 items)","minItems":2,"maxItems":5}},"required":["products"]}},"additionalProperties":false},{"title":"find_best_deal","type":"object","required":["tool"],"properties":{"tool":{"type":"string","const":"find_best_deal","description":"Find the single best product matching constraints. Ranks by value (price vs rating vs shipping). Use when the user wants a recommendation rather than a list. Candidates are filtered to plausible matches for the query first, so a cheap accessory cannot be returned as the cheapest way to buy the product itself; `recommendation` may be null with a reason when nothing matched confidently, and that must be reported as \"no confident match\" rather than softened into a suggestion. `recommendation.verified` marks an offer whose identity WEM has resolved rather than inferred."},"input":{"type":"object","properties":{"query":{"type":"string","description":"What to search for"},"max_price":{"type":"number","description":"Budget cap (GBP)"},"priorities":{"type":"array","items":{"type":"string","enum":["cheapest","best_rated","free_shipping","fastest"]},"description":"What matters most (in order of importance)"}},"required":["query"]}},"additionalProperties":false},{"title":"compare_offers","type":"object","required":["tool"],"properties":{"tool":{"type":"string","const":"compare_offers","description":"Exact multi-retailer offers for one product from WEM's own catalogue, cheapest first, with a 90-day price-history low. Identity is resolved by barcode or catalogue slug — no text matching — so every offer IS the product, and the lookup spends no retailer API quota. Use this FIRST when you have a barcode (EAN/UPC/GTIN) or a wem3.ai/pl/{slug} URL; fall back to search_products when the product is not in the catalogue yet."},"input":{"type":"object","properties":{"gtin":{"type":"string","description":"Product barcode: EAN-13, UPC-A, EAN-8 or GTIN-14. Preferred key."},"slug":{"type":"string","description":"WEM canonical product slug, as in wem3.ai/pl/{slug}."}},"required":[]}},"additionalProperties":false},{"title":"get_categories","type":"object","required":["tool"],"properties":{"tool":{"type":"string","const":"get_categories","description":"Get available product categories and the approximate price range for each. Use to guide the user when their request is vague."},"input":{"type":"object","properties":{}}},"additionalProperties":false}]}}}},"responses":{"200":{"description":"Tool result. `success: false` means the tool ran and reported a problem.","content":{"application/json":{"schema":{"type":"object","required":["success"],"properties":{"success":{"type":"boolean"},"data":{"type":"object","description":"Shape depends on the tool. Search-style results carry `products`, an optional `catalogMatch` of identity-resolved offers, and `filtered`, a count by reason of the weak matches withheld — report that count rather than implying the search was exhaustive.","additionalProperties":true},"error":{"type":"string"}}}}}},"400":{"description":"Missing or unknown tool, or a malformed body."},"429":{"description":"Burst or daily quota exhausted. Respect `retry-after` — retrying sooner cannot succeed."},"500":{"description":"Unexpected server error."}}},"get":{"operationId":"describeProductTools","summary":"Endpoint description and current limits","responses":{"200":{"description":"Endpoint metadata and tool names."}}}}}}