API Reference

Complete reference for all BuyWhere API endpoints.

Base URL

https://api.buywhere.ai

Authentication

All endpoints require a Bearer token:

Authorization: Bearer bw_live_xxxxx

See the Authentication Guide for details.

Table of Contents

• Search Products
• Get Product by ID
• Best Price
• Compare Products
• Compare Matrix
• Compare Diff
• Trending Products
• Categories
• Export Products
• Deals
• API Root
• Health Check

---

Search Products

Full-text search across all products.

GET /v1/search

Query Parameters

Example

curl "https://api.buywhere.ai/v1/search?q=dyson%20vacuum&limit=10" \
  -H "Authorization: Bearer bw_live_xxxxx"

Response

{
  "total": 142,
  "limit": 10,
  "offset": 0,
  "has_more": true,
  "items": [
    {
      "id": 12345,
      "sku": "DY-VC7-XXXX",
      "source": "lazada_sg",
      "merchant_id": "LAZADA_SG_001",
      "name": "Dyson V15 Detect Vacuum Cleaner",
      "description": "Laser detects microscopic dust...",
      "price": "749.00",
      "currency": "SGD",
      "buy_url": "https://www.lazada.sg/products/...",
      "affiliate_url": "https://buywhere.ai/track/...",
      "image_url": "https://...jpg",
      "brand": "Dyson",
      "category": "Vacuum Cleaners",
      "category_path": ["Home & Garden", "Cleaning", "Vacuum Cleaners"],
      "rating": "4.8",
      "is_available": true,
      "last_checked": "2026-04-03T12:00:00Z",
      "metadata": null,
      "updated_at": "2026-04-03T14:30:00Z"
    }
  ]
}

---

Get Product by ID

Retrieve a single product by its BuyWhere ID.

GET /v1/products/{product_id}

Path Parameters

Example

curl "https://api.buywhere.ai/v1/products/12345" \
  -H "Authorization: Bearer bw_live_xxxxx"

Response

Returns a single Product object. See Product Schema.

---

Best Price

Find the cheapest listing for a product across all platforms.

GET /v1/products/best-price

Query Parameters

Example

curl "https://api.buywhere.ai/v1/products/best-price?q=nintendo%20switch%20oled" \
  -H "Authorization: Bearer bw_live_xxxxx"

Response

Returns a single Product object — the cheapest match.

Error Responses

---

Compare Products

Find all listings of the same product across platforms.

GET /v1/products/compare

Query Parameters

Example

curl "https://api.buywhere.ai/v1/products/compare?product_id=12345" \
  -H "Authorization: Bearer bw_live_xxxxx"

Response

{
  "source_product_id": 12345,
  "source_product_name": "Dyson V15 Detect Vacuum Cleaner",
  "matches": [
    {
      "id": 12346,
      "sku": "DY-VC7-YYY",
      "source": "shopee_sg",
      "merchant_id": "SHOPEE_SG_002",
      "name": "Dyson V15 Detect Vacuum Cleaner",
      "price": "729.00",
      "currency": "SGD",
      "buy_url": "https://shopee.sg/...",
      "affiliate_url": "https://buywhere.ai/track/...",
      "match_score": 0.95,
      ...
    }
  ],
  "total_matches": 5
}

---

Compare Matrix

Compare multiple products across platforms in a single request.

POST /v1/products/compare

Request Body

{
  "product_ids": [12345, 67890, 11111],
  "min_price": 0,
  "max_price": 10000
}

Response

{
  "comparisons": [
    {
      "source_product_id": 12345,
      "source_product_name": "Product A",
      "matches": [...],
      "total_matches": 5
    }
  ],
  "total_products": 3
}

---

Compare Diff

Compare 2-5 products directly — returns structured field differences.

POST /v1/products/compare/diff

Request Body

{
  "product_ids": [12345, 67890, 11111],
  "include_image_similarity": false
}

Response

{
  "products": [
    {
      "id": 12345,
      "name": "Product A",
      "price": "749.00",
      "price_rank": 2,
      ...
    }
  ],
  "field_diffs": [
    {
      "field": "price",
      "values": ["749.00", "729.00", "799.00"],
      "all_identical": false
    }
  ],
  "identical_fields": ["brand", "category"],
  "cheapest_product_id": 67890,
  "most_expensive_product_id": 11111,
  "price_spread": "70.00",
  "price_spread_pct": 9.61
}

---

Trending Products

Get recently updated products by category.

GET /v1/products/trending

Query Parameters

Example

curl "https://api.buywhere.ai/v1/products/trending?category=Electronics&limit=20" \
  -H "Authorization: Bearer bw_live_xxxxx"

---

Categories

List all available product categories with item counts.

GET /v1/categories

Example

curl "https://api.buywhere.ai/v1/categories" \
  -H "Authorization: Bearer bw_live_xxxxx"

Response

{
  "categories": [
    {"name": "Electronics", "count": 125000},
    {"name": "Fashion", "count": 98000},
    {"name": "Home & Garden", "count": 67000}
  ],
  "total": 45
}

---

Export Products

Export products as CSV or JSON.

GET /v1/products/export

Query Parameters

Example

curl "https://api.buywhere.ai/v1/products/export?format=csv&limit=100" \
  -H "Authorization: Bearer bw_live_xxxxx"

---

Deals

Get products currently priced below their historical price.

GET /v1/deals

Query Parameters

---

API Root

Get API metadata and available endpoints.

GET /v1

Response

{
  "api": "BuyWhere Catalog API",
  "version": "v1",
  "endpoints": {
    "search": "GET /v1/search",
    "products": "GET /v1/products",
    "best_price": "GET /v1/products/best-price",
    "compare_single": "GET /v1/products/compare",
    "compare_matrix": "POST /v1/products/compare",
    "compare_diff": "POST /v1/products/compare/diff",
    "trending": "GET /v1/products/trending",
    "export": "GET /v1/products/export?format=csv|json",
    "product": "GET /v1/products/{id}",
    "categories": "GET /v1/categories",
    "deals": "GET /v1/deals"
  },
  "auth": "Bearer token required (API key)",
  "docs": "/docs"
}

---

Health Check

Check API health status.

GET /health

Response

{
  "status": "ok",
  "version": "1.0.0",
  "environment": "production"
}

---

Product Schema

All product-related endpoints return objects conforming to this schema:

---

Error Codes