{"openapi":"3.1.0","info":{"title":"Buy Where (BYOK) API","version":"0.1.0","description":"Buy Where (BYOK) lets an AI assistant read your own Buy Where data through the Buy Where API with a key you supply (BuyWhere API key). Read-only: 10 tools (search_products, get_product, list_deals, compare_products, get_price_history, get_product_prices, find_similar_products, list_categories, get_category_products, list_featured_products). The BYOK key travels with each request, is used for that...\n\nEvery operation is read-only or compute-only. The same tools are available over MCP (streamable HTTP) at https://byok-buywhere.connectorbay.com/mcp.","contact":{"name":"Unify Dynamics LLC","email":"agent@connectorbay.com","url":"https://connectorbay.com/byok-buywhere/docs"},"termsOfService":"https://connectorbay.com/byok-buywhere/terms"},"servers":[{"url":"https://byok-buywhere.connectorbay.com"}],"externalDocs":{"url":"https://connectorbay.com/byok-buywhere/docs"},"security":[{"upstreamKey":[]}],"components":{"securitySchemes":{"bearer":{"type":"http","scheme":"bearer","description":"Optional. A Pro API key raises rate limits; no credentials are required."},"upstreamKey":{"type":"apiKey","in":"header","name":"X-Upstream-Key","description":"Your own key for the service this connector wraps (bring your own key). Used for that one call only; never stored, logged or cached."}},"schemas":{"Error":{"type":"object","properties":{"ok":{"const":false},"error":{"type":"object"}}}}},"paths":{"/v1/tools/search_products":{"post":{"operationId":"search_products","summary":"Search products across merchants by keyword with filters for price, country, currency and deliverability. Each product h","description":"Search products across merchants by keyword with filters for price, country, currency and deliverability. Each product has title, price, merchant, URL and category path. Use for \"Find wireless noise-cancelling headphones deliverable to Singapore under 300 SGD\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"q":{"description":"Search words, for example 'wireless headphones'.","maxLength":200,"title":"Q","type":"string"},"deliver_to":{"anyOf":[{"enum":["SG","US","VN","TH","MY","ID","PH"],"type":"string"},{"type":"null"}],"default":null,"description":"Country the buyer is in; results are ranked deliverable-first.","title":"Deliver To"},"country_code":{"anyOf":[{"enum":["SG","US","VN","TH","MY"],"type":"string"},{"type":"null"}],"default":null,"description":"Only products sold in this country.","title":"Country Code"},"include_unshippable":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":true,"description":"False to hide products that cannot be shipped to deliver_to.","title":"Include Unshippable"},"min_price":{"anyOf":[{"minimum":0,"type":"number"},{"type":"null"}],"default":null,"description":"Minimum price in the chosen currency.","title":"Min Price"},"max_price":{"anyOf":[{"minimum":0,"type":"number"},{"type":"null"}],"default":null,"description":"Maximum price in the chosen currency.","title":"Max Price"},"currency":{"anyOf":[{"maxLength":3,"type":"string"},{"type":"null"}],"default":"SGD","description":"Currency code for prices, for example SGD or USD.","title":"Currency"},"mode":{"anyOf":[{"enum":["keyword","semantic","hybrid"],"type":"string"},{"type":"null"}],"default":"keyword","description":"Search mode: keyword, semantic or hybrid.","title":"Mode"},"limit":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":20,"description":"How many results (1 to 100).","title":"Limit"},"offset":{"anyOf":[{"maximum":100000,"minimum":0,"type":"integer"},{"type":"null"}],"default":0,"description":"How many results to skip, for paging.","title":"Offset"}},"required":["q"],"title":"search_productsArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/get_product":{"post":{"operationId":"get_product","summary":"Get the full details of one product by its BuyWhere id. Use for \"Show the details of product 12345\".","description":"Get the full details of one product by its BuyWhere id. Use for \"Show the details of product 12345\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"id":{"description":"BuyWhere product id from search_products.","maxLength":200,"title":"Id","type":"string"}},"required":["id"],"title":"get_productArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/list_deals":{"post":{"operationId":"list_deals","summary":"List discounted products sorted by discount percentage, optionally for one country. Use for \"What are the biggest discou","description":"List discounted products sorted by discount percentage, optionally for one country. Use for \"What are the biggest discounts on offer in Singapore\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"min_discount":{"anyOf":[{"maximum":100,"minimum":0,"type":"number"},{"type":"null"}],"default":10,"description":"Minimum discount in percent.","title":"Min Discount"},"country_code":{"anyOf":[{"maxLength":2,"type":"string"},{"type":"null"}],"default":null,"description":"Only products sold in this country, for example 'SG'.","title":"Country Code"},"currency":{"anyOf":[{"maxLength":3,"type":"string"},{"type":"null"}],"default":"SGD","description":"Currency code for prices, for example SGD or USD.","title":"Currency"},"deliver_to":{"anyOf":[{"enum":["SG","US","VN","TH","MY","ID","PH"],"type":"string"},{"type":"null"}],"default":null,"description":"Country the buyer is in; results are ranked deliverable-first.","title":"Deliver To"},"limit":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":20,"description":"How many results (1 to 100).","title":"Limit"},"offset":{"anyOf":[{"maximum":100000,"minimum":0,"type":"integer"},{"type":"null"}],"default":0,"description":"How many results to skip, for paging.","title":"Offset"}},"title":"list_dealsArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/compare_products":{"post":{"operationId":"compare_products","summary":"Compare two or more products side by side by id. Use for \"Compare products 12345 and 67890\".","description":"Compare two or more products side by side by id. Use for \"Compare products 12345 and 67890\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"ids":{"description":"Comma-separated product ids (2 to 10).","maxLength":300,"title":"Ids","type":"string"}},"required":["ids"],"title":"compare_productsArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/get_price_history":{"post":{"operationId":"get_price_history","summary":"Get the historical price points of a product for charting. Use for \"How has the price of product 12345 changed\".","description":"Get the historical price points of a product for charting. Use for \"How has the price of product 12345 changed\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"id":{"description":"BuyWhere product id from search_products.","maxLength":200,"title":"Id","type":"string"}},"required":["id"],"title":"get_price_historyArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/get_product_prices":{"post":{"operationId":"get_product_prices","summary":"Get price snapshots of a product from merchant feeds over the last days (up to 90). Use for \"What did product 12345 cost","description":"Get price snapshots of a product from merchant feeds over the last days (up to 90). Use for \"What did product 12345 cost over the last 30 days\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"id":{"description":"BuyWhere product id from search_products.","maxLength":200,"title":"Id","type":"string"},"days":{"anyOf":[{"maximum":90,"minimum":1,"type":"integer"},{"type":"null"}],"default":30,"description":"How many past days (1 to 90).","title":"Days"}},"required":["id"],"title":"get_product_pricesArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/find_similar_products":{"post":{"operationId":"find_similar_products","summary":"Find products similar to a given one by embedding similarity. Use for \"What products are similar to 12345\".","description":"Find products similar to a given one by embedding similarity. Use for \"What products are similar to 12345\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"id":{"description":"BuyWhere product id from search_products.","maxLength":200,"title":"Id","type":"string"},"limit":{"anyOf":[{"maximum":20,"minimum":1,"type":"integer"},{"type":"null"}],"default":10,"description":"How many results (1 to 20).","title":"Limit"}},"required":["id"],"title":"find_similar_productsArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/list_categories":{"post":{"operationId":"list_categories","summary":"List the top-level product categories. Use for \"What product categories does BuyWhere have\".","description":"List the top-level product categories. Use for \"What product categories does BuyWhere have\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"currency":{"anyOf":[{"maxLength":3,"type":"string"},{"type":"null"}],"default":"SGD","description":"Currency code for prices, for example SGD or USD.","title":"Currency"}},"title":"list_categoriesArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/get_category_products":{"post":{"operationId":"get_category_products","summary":"List products within a category by slug. Use for \"Show products in the electronics category\".","description":"List products within a category by slug. Use for \"Show products in the electronics category\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"slug":{"description":"Category slug from list_categories, for example 'electronics'.","maxLength":200,"title":"Slug","type":"string"},"currency":{"anyOf":[{"maxLength":3,"type":"string"},{"type":"null"}],"default":"SGD","description":"Currency code for prices, for example SGD or USD.","title":"Currency"},"limit":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":20,"description":"How many results (1 to 100).","title":"Limit"},"offset":{"anyOf":[{"maximum":100000,"minimum":0,"type":"integer"},{"type":"null"}],"default":0,"description":"How many results to skip, for paging.","title":"Offset"}},"required":["slug"],"title":"get_category_productsArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/list_featured_products":{"post":{"operationId":"list_featured_products","summary":"List featured products (newest active ones) for a country. Use for \"Show newly featured products in Singapore\".","description":"List featured products (newest active ones) for a country. Use for \"Show newly featured products in Singapore\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"country":{"anyOf":[{"enum":["SG","US","VN","TH","MY"],"type":"string"},{"type":"null"}],"default":null,"description":"Country code.","title":"Country"},"currency":{"anyOf":[{"maxLength":3,"type":"string"},{"type":"null"}],"default":"SGD","description":"Currency code for prices, for example SGD or USD.","title":"Currency"},"limit":{"anyOf":[{"maximum":50,"minimum":1,"type":"integer"},{"type":"null"}],"default":12,"description":"How many results (1 to 50).","title":"Limit"},"offset":{"anyOf":[{"maximum":100000,"minimum":0,"type":"integer"},{"type":"null"}],"default":0,"description":"How many results to skip, for paging.","title":"Offset"}},"title":"list_featured_productsArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}}}}