openapi: 3.0.3
info:
title: BuyWhere Product Catalog Authentication Products API
version: '1'
description: 'Agent-native product catalog API for Southeast Asia and US commerce. Search 1.5M+
products across Shopee, Lazada, Amazon, Walmart, FairPrice, Carousell, Best Denki,
and 20+ e-commerce platforms. Compare prices, discover deals, and find best prices
through REST or MCP (Model Context Protocol).
Responses are structured for LLM and agent consumption (Schema.org-compatible
`Product` / `Offer` / `ItemList` shapes). Each product carries normalized
`structured_specs` (brand, model, size, color) and `comparison_attributes`
so agents can reason and rank without scraping.
BuyWhere is MCP-native — the same operations are exposed at
`POST https://api.buywhere.ai/mcp` for MCP-compatible clients, with a hosted
HTTP transport and a published `@buywhere/mcp-server` STDIO package.
'
contact:
name: BuyWhere API
email: api@buywhere.ai
url: https://api.buywhere.ai/
termsOfService: https://buywhere.ai/terms
license:
name: Commercial
url: https://buywhere.ai/terms
servers:
- url: https://api.buywhere.ai/v1
description: Production REST API
tags:
- name: Products
description: Product search, lookup, comparison, deals, and price history.
paths:
/products/search:
get:
summary: Search Products By Keyword
description: Full-text search across the BuyWhere catalog with filters for merchant platform, region, country, price range, and currency. Set `compact=true` for an LLM-optimized payload.
operationId: searchProducts
tags:
- Products
security:
- BearerAuth: []
parameters:
- name: q
in: query
schema:
type: string
description: Keyword search query (full-text).
example: wireless headphones
- name: domain
in: query
schema:
type: string
description: Filter by merchant platform (e.g. `lazada`, `shopee`, `amazon`, `walmart`, `carousell`).
example: shopee
- name: region
in: query
schema:
type: string
enum:
- sea
- us
- eu
- au
description: Filter by region.
- name: country_code
in: query
schema:
type: string
enum:
- SG
- US
- VN
- TH
- MY
description: 'Filter by ISO country code. When provided without an explicit `currency` param,
the default currency is inferred (SG→SGD, US→USD, VN→VND, TH→THB, MY→MYR).
`min_price` / `max_price` apply in the inferred currency. Default: `SG`.
'
- name: min_price
in: query
schema:
type: number
description: Minimum price in the active currency.
- name: max_price
in: query
schema:
type: number
description: Maximum price in the active currency.
- name: currency
in: query
schema:
type: string
default: SGD
description: Explicit currency override. If omitted and `country_code` is set, currency is inferred from `country_code`.
- name: compact
in: query
schema:
type: boolean
default: false
description: Return a minimal payload for AI agents (id, title, price, currency, url, structured_specs, comparison_attributes).
- name: limit
in: query
schema:
type: integer
default: 20
maximum: 100
- name: offset
in: query
schema:
type: integer
default: 0
responses:
'200':
description: Product list with meta (total, response_time_ms, cached).
content:
application/json:
schema:
$ref: '#/components/schemas/ProductList'
'401':
$ref: '#/components/responses/Unauthorized'
'429':
$ref: '#/components/responses/RateLimited'
/products/deals:
get:
summary: List Discounted Products By Discount Percentage
description: Returns products sorted by discount percentage, filtered by minimum discount, currency, and country.
operationId: getDeals
tags:
- Products
security:
- BearerAuth: []
parameters:
- name: currency
in: query
schema:
type: string
default: SGD
- name: country_code
in: query
schema:
type: string
enum:
- SG
- US
- VN
- TH
- MY
description: When set, only deals from that country are returned.
- name: min_discount
in: query
schema:
type: number
default: 10
description: Minimum discount percentage (0–90).
- name: limit
in: query
schema:
type: integer
default: 20
maximum: 100
- name: offset
in: query
schema:
type: integer
default: 0
responses:
'200':
description: Discounted products with `price`, `original_price`, and `discount_pct`.
content:
application/json:
schema:
$ref: '#/components/schemas/DealList'
'401':
$ref: '#/components/responses/Unauthorized'
'429':
$ref: '#/components/responses/RateLimited'
/products/compare:
get:
summary: Compare Multiple Products Side-By-Side
description: Compare 2–10 products side-by-side with normalized price, brand, rating, and category path.
operationId: compareProducts
tags:
- Products
security:
- BearerAuth: []
parameters:
- name: ids
in: query
required: true
schema:
type: string
description: Comma-separated product IDs (2–10).
example: 8a2c3a8e-1234-5678-9abc-def012345678,9b3d4b9f-2345-6789-abcd-ef0123456789
responses:
'200':
description: Array of products with comparison-ready attributes.
content:
application/json:
schema:
$ref: '#/components/schemas/CompareResponse'
'400':
description: Fewer than 2 IDs provided.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'401':
$ref: '#/components/responses/Unauthorized'
/products/{id}:
get:
summary: Get Product By ID
description: Returns the full product detail including title, description, price, merchant, structured specs, and Schema.org-compatible metadata.
operationId: getProduct
tags:
- Products
security:
- BearerAuth: []
parameters:
- name: id
in: path
required: true
schema:
type: string
format: uuid
responses:
'200':
description: Product detail.
content:
application/json:
schema:
$ref: '#/components/schemas/Product'
'404':
$ref: '#/components/responses/NotFound'
'401':
$ref: '#/components/responses/Unauthorized'
/products/{id}/prices:
get:
summary: Get Product Price History
description: Returns price history (with min/max/avg stats) over a configurable look-back window.
operationId: getProductPrices
tags:
- Products
security:
- BearerAuth: []
parameters:
- name: id
in: path
required: true
schema:
type: string
format: uuid
- name: days
in: query
schema:
type: integer
default: 30
maximum: 90
description: Look-back window in days.
responses:
'200':
description: Price history with min/max/avg stats.
content:
application/json:
schema:
$ref: '#/components/schemas/PriceHistory'
'404':
$ref: '#/components/responses/NotFound'
'401':
$ref: '#/components/responses/Unauthorized'
components:
schemas:
PricePoint:
type: object
properties:
date:
type: string
format: date
price:
type: number
currency:
type: string
ProductList:
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/Product'
meta:
type: object
properties:
total:
type: integer
response_time_ms:
type: integer
cached:
type: boolean
limit:
type: integer
offset:
type: integer
CompareResponse:
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/Product'
meta:
type: object
properties:
count:
type: integer
Deal:
allOf:
- $ref: '#/components/schemas/Product'
- type: object
properties:
discount_pct:
type: number
description: Discount percentage (0–90).
DealList:
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/Deal'
meta:
type: object
properties:
total:
type: integer
response_time_ms:
type: integer
Error:
type: object
properties:
error:
type: object
properties:
code:
type: string
enum:
- invalid_params
- not_found
- rate_limited
- unauthorized
- internal_error
message:
type: string
request_id:
type: string
PriceHistory:
type: object
properties:
id:
type: string
format: uuid
currency:
type: string
days:
type: integer
points:
type: array
items:
$ref: '#/components/schemas/PricePoint'
stats:
type: object
properties:
min:
type: number
max:
type: number
avg:
type: number
current:
type: number
Product:
type: object
description: Schema.org-compatible product representation.
properties:
id:
type: string
format: uuid
title:
type: string
description:
type: string
brand:
type: string
domain:
type: string
description: Source merchant platform (lazada, shopee, amazon, walmart, etc.).
url:
type: string
format: uri
description: Canonical merchant product URL.
image_url:
type: string
format: uri
price:
type: number
original_price:
type: number
discount_pct:
type: number
currency:
type: string
example: SGD
country_code:
type: string
example: SG
rating:
type: number
review_count:
type: integer
category_path:
type: array
items:
type: string
structured_specs:
type: object
description: Normalized structured attributes (brand, model, size, color, etc.).
additionalProperties: true
comparison_attributes:
type: object
description: Attributes pre-normalized for agent comparison reasoning.
additionalProperties: true
normalized_price_usd:
type: number
availability:
type: string
enum:
- in_stock
- out_of_stock
- preorder
- limited
updated_at:
type: string
format: date-time
responses:
Unauthorized:
description: Missing or invalid API key.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
RateLimited:
description: Rate limit exceeded. Implement exponential backoff and respect `Retry-After`.
headers:
Retry-After:
schema:
type: integer
description: Seconds to wait before retrying.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
NotFound:
description: Resource not found.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
securitySchemes:
BearerAuth:
type: http
scheme: bearer
description: 'Pass your API key as a Bearer token. Get a free key at `POST /v1/auth/register`.
Tiers: `bw_free_*` (60 rpm), `bw_live_*` (600 rpm), `bw_partner_*` (unlimited).
'
externalDocs:
description: BuyWhere developer documentation and MCP guide
url: https://api.buywhere.ai/docs/guides/mcp