release-notes-v1.0

BuyWhere API v1.0 — Release Notes

Released: April 23, 2026

What is BuyWhere API v1.0?

BuyWhere API v1.0 is the first stable release of BuyWhere's agent-native product catalog platform. It provides AI agents and developers with structured, real-time access to e-commerce product data across Singapore, Southeast Asia, and the United States — all through a single REST API and a native MCP server. v1.0 is production-ready: rate-limited, authenticated, and optimized for both direct HTTP use and tool-call invocation by LLM agents.

Endpoints

All endpoints are served at https://api.buywhere.ai. Authentication uses Bearer tokens obtained via /v1/auth/register.

Authentication

Method	Endpoint	Description
`POST`	`/v1/auth/register`	Self-register for a free API key — no approval required. Returns a `bw_` prefixed key immediately.

Products

Method	Endpoint	Description
`GET`	`/v1/products/search`	Full-text product search across the catalog. Supports keyword query, merchant domain, region, country code, price range, and currency filters. Returns ranked results via PostgreSQL GIN index. Accepts `compact=true` for a smaller, agent-optimized response envelope with `structured_specs`, `comparison_attributes`, and `normalized_price_usd`.
`GET`	`/v1/products/deals`	Discounted products sorted by discount depth. Filter by region (`sea`, `us`, `eu`, `au`) and country code. Use `min_discount` to set a floor percentage (default 10%).
`GET`	`/v1/products/compare`	Side-by-side comparison of 2–10 products. Pass `ids=id1,id2,...` as a query parameter. Returns price, brand, rating, category, and availability for each product.
`GET`	`/v1/products/:id`	Full product detail by UUID, including current price, images, description, and merchant link.
`GET`	`/v1/products/:id/price-history`	Daily aggregated price history for a product (suitable for charting price trends).
`GET`	`/v1/products/:id/prices`	Raw price snapshots from the price tracking pipeline (granular, timestamped).
`GET`	`/v1/products/:id/similar`	Up to 8 similar products, useful for recommendation widgets.

v2 alias: /v2/products/search and /v2/products/deals are available as aliases to the same router, extending the v1 contract with country_code-based currency inference. v1 and v2 responses are compatible.

Method	Endpoint	Description
`GET`	`/v1/categories`	List all top-level product categories in the catalog.
`GET`	`/v1/categories/:slug`	Get products within a specific category by slug.

Comparison Pages

Method	Endpoint	Description
`GET`	`/v1/compare/:slug`	Retrieve a pre-built product comparison page payload by slug. Used by the BuyWhere web frontend and embeddable compare widgets.
`POST`	`/v1/compare/:slug/click`	Record a retailer click on a comparison page for analytics attribution.

MCP

Method	Endpoint	Description
`GET`	`/mcp`	MCP server info — credential-free introspection for directory scanners (Smithery, Glama).
`POST`	`/mcp`	MCP JSON-RPC 2.0 endpoint. Supports `initialize`, `tools/list` without auth; `tools/call` requires a Bearer API key.

Affiliate Redirect

Method	Endpoint	Description
`GET`	`/r/:affiliateSlug/:productId`	Affiliate-tracked redirect to a product's merchant URL. Validates the destination, sets security headers, and logs the click before issuing a 302.

Coverage

Dimension	Detail
Catalog size	Growing rapidly toward 1M products at launch; 5M+ is the near-term milestone
Regions	Singapore (primary), Southeast Asia (MY, TH, VN, PH, ID), United States
Retailers	50+ merchants including Amazon SG/US, Shopee, Lazada, Zalora, Harvey Norman, Courts, FairPrice, NTUC, IKEA SG, Best Buy (US), Chewy (US), Carousell, Challenger, Decathlon, Uniqlo, and others
Categories	Electronics, fashion, home & living, health & beauty, groceries, pet supplies, sports, books
Currencies	SGD, USD, MYR, THB, VND — with `normalized_price_usd` available in compact mode for cross-currency comparison

MCP Server

BuyWhere ships a native MCP server at https://api.buywhere.ai/mcp, implementing the Model Context Protocol version 2024-11-05 over stateless HTTP POST.

Tools

Tool	Description
`search_products`	Keyword search with filters for domain, region, country code, and price range. Supports `compact=true` for agent-optimized output (40% smaller response with structured specs).
`get_product`	Retrieve full product details by BuyWhere product UUID.
`compare_products`	Compare 2–10 products side-by-side: price, brand, rating, category.
`get_deals`	Discounted products ranked by discount depth, filterable by region and country.
`list_categories`	List top-level product categories available in the catalog.

Compatible Frameworks

The BuyWhere MCP server works with any MCP-compatible client or agent framework, including:

Claude (via MCP tool configuration)
LangChain (via langchain-mcp-adapters)
OpenAI Agents SDK (via MCP server config)
Cursor and other IDE agents
Smithery and Glama directories (listed and introspectable)

To connect, provide your API key as a Bearer token in the Authorization header of each POST /mcp call, or configure it in your MCP client's environment settings (BUYWHERE_API_KEY).

Rate Limits

Rate limits are enforced per API key using a sliding window. Limits reset on a rolling per-minute and per-day basis.

Tier	Requests/Minute	Requests/Day	Notes
Free	60	1,000	Self-service via `/v1/auth/register`
Pro	300	10,000	Contact `api@buywhere.ai`
Enterprise	1,000	100,000	Custom contracts available

When a limit is exceeded, the API returns HTTP 429 Too Many Requests with X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset headers.

Known Limitations

Data freshness varies by retailer. High-volume merchants (Amazon SG, Shopee) are refreshed frequently; smaller merchants may have data that is 24–48 hours old. Price-sensitive workflows should treat prices as indicative, not real-time.
eBay not available at launch. eBay marketplace integration is code-complete but pending API credentials from the eBay Developer Program. Target: v1.1.
Some SEA retailers have partial coverage. Platforms requiring login-based scraping (certain Shopee MY, Tokopedia) have limited depth at launch.
Catalog is growing. The full 1M-product milestone is in active progress. Certain niche categories (automotive parts, industrial supplies) are not yet indexed.
No real-time price guarantee. BuyWhere aggregates merchant data; we are not a live checkout integration. Always link users to the merchant page for final price confirmation.
Free tier is intentionally restrictive. 60 RPM / 1,000 daily is designed for development and testing. Production agent workloads should upgrade to Pro or contact us for Enterprise.

What's Coming in v1.1

eBay marketplace — Full eBay US and eBay SG integration, adding auction and fixed-price listings to the catalog.
Price alerts API — Subscribe to price threshold notifications for specific products or search queries; webhook delivery.
Enhanced proxy coverage — BrightData and Oxylabs proxy integration to improve scraping reliability for platforms that currently have partial coverage, increasing both catalog depth and freshness.

For API reference, quickstart guides, and SDK examples, see https://docs.buywhere.ai. To report issues or request features, contact the engineering team at api@buywhere.ai.