API_EXAMPLES

BuyWhere API Usage Examples

Complete copy-paste examples for every BuyWhere API endpoint. All endpoints require authentication unless noted as No Auth.

Base URL: https://api.buywhere.ai

Authentication: Pass your API key in the Authorization header:

-H "Authorization: Bearer <your-api-key>"

Authentication & Developer Setup
API Keys
Product Search
Full-Text Search
Product Details
Product Comparison
Deals Discovery
Categories
Analytics
Click Tracking
Batch Ingestion
Ingestion Run Tracking
Catalog Quality
Admin
System Status

1. Authentication & Developer Setup

Developer Signup (No Auth)

Create a developer account and API key in a single request. Rate limited to 5 accounts per IP per hour.

curl -X POST https://api.buywhere.ai/v1/developers/signup \
  -H "Content-Type: application/json" \
  -d '{
    "email": "developer@example.com",
    "name": "My App"
  }'

Python:

import requests

resp = requests.post(
    "https://api.buywhere.ai/v1/developers/signup",
    json={"email": "developer@example.com", "name": "My App"}
)
print(resp.json())

Response:

{
  "developer_id": "550e8400-e29b-41d4-a716-446655440000",
  "email": "developer@example.com",
  "plan": "free",
  "key_id": "123e4567-e89b-12d3-a456-426614174000",
  "raw_key": "bw_live_xR2kP9vL7mNqT4w...",
  "name": "My App",
  "tier": "basic",
  "message": "Store this key securely — it will not be shown again."
}

Get Developer Profile

Returns developer profile and all API keys associated with the account.

curl https://api.buywhere.ai/v1/developers/me \
  -H "Authorization: Bearer <your-api-key>"

Python:

resp = requests.get(
    "https://api.buywhere.ai/v1/developers/me",
    headers={"Authorization": "Bearer <your-api-key>"}
)
print(resp.json())

2. API Keys

Bootstrap First Key (No Auth)

Create the first API key when no keys exist in the system. Only works for initial setup.

curl -X POST https://api.buywhere.ai/v1/keys/bootstrap \
  -H "Content-Type: application/json" \
  -d '{"name": "My First Key"}'

Python:

resp = requests.post(
    "https://api.buywhere.ai/v1/keys/bootstrap",
    json={"name": "My First Key"}
)
print(resp.json())

Create API Key

Create an additional API key for your account.

curl -X POST https://api.buywhere.ai/v1/keys \
  -H "Authorization: Bearer <your-api-key>" \
  -H "Content-Type: application/json" \
  -d '{"name": "Production Key"}'

Python:

resp = requests.post(
    "https://api.buywhere.ai/v1/keys",
    headers={"Authorization": "Bearer <your-api-key>"},
    json={"name": "Production Key"}
)
print(resp.json())

List API Keys

List all active API keys for your account.

curl https://api.buywhere.ai/v1/keys \
  -H "Authorization: Bearer <your-api-key>"

Python:

resp = requests.get(
    "https://api.buywhere.ai/v1/keys",
    headers={"Authorization": "Bearer <your-api-key>"}
)
print(resp.json())

Revoke API Key

Revoke (deactivate) an API key.

curl -X DELETE https://api.buywhere.ai/v1/keys/{key_id} \
  -H "Authorization: Bearer <your-api-key>"

Python:

resp = requests.delete(
    f"https://api.buywhere.ai/v1/keys/{key_id}",
    headers={"Authorization": "Bearer <your-api-key>"}
)
print(resp.status_code)  # 204 No Content

3. Product Search

Search Products

Full-text search with optional filters. Returns paginated results with relevance ranking.

curl "https://api.buywhere.ai/v1/products?q=laptop&limit=10&offset=0" \
  -H "Authorization: Bearer <your-api-key>"

Python:

resp = requests.get(
    "https://api.buywhere.ai/v1/products",
    params={"q": "laptop", "limit": 10, "offset": 0},
    headers={"Authorization": "Bearer <your-api-key>"}
)
print(resp.json())

With filters:

curl "https://api.buywhere.ai/v1/products?q=laptop&min_price=100&max_price=2000&source=shopee_sg&category=electronics" \
  -H "Authorization: Bearer <your-api-key>"

Response:

{
  "total": 142,
  "limit": 10,
  "offset": 0,
  "items": [
    {
      "id": 12345,
      "sku": "SHOPEE-ABC123",
      "source": "shopee_sg",
      "merchant_id": "shop_123",
      "name": "ASUS VivoBook 15 Laptop",
      "description": "Intel Core i5, 8GB RAM, 512GB SSD...",
      "price": 1299.00,
      "currency": "SGD",
      "buy_url": "https://shopee.sg/product/...",
      "affiliate_url": "https://buywhere.ai/track/...",
      "image_url": "https://cf.shopee.sg/file/...",
      "brand": "ASUS",
      "category": "Computers & Laptops",
      "category_path": "Electronics > Computers > Laptops",
      "rating": 4.5,
      "is_available": true,
      "updated_at": "2026-04-04T10:30:00Z"
    }
  ],
  "has_more": true
}

Find Best Price

Find the cheapest listing for a product across all platforms.

curl "https://api.buywhere.ai/v1/products/best-price?q=iphone+15+case" \
  -H "Authorization: Bearer <your-api-key>"

Python:

resp = requests.get(
    "https://api.buywhere.ai/v1/products/best-price",
    params={"q": "iphone 15 case"},
    headers={"Authorization": "Bearer <your-api-key>"}
)
print(resp.json())

Response:

{
  "id": 67890,
  "sku": "LAZADA-XYZ789",
  "source": "lazada_sg",
  "merchant_id": "lazada_store_456",
  "name": "iPhone 15 Silicone Case",
  "price": 12.99,
  "currency": "SGD",
  "buy_url": "https://www.lazada.sg/products/...",
  "affiliate_url": "https://buywhere.ai/track/...",
  "brand": "Apple",
  "category": "Phone Cases",
  "is_available": true
}

Get Trending Products

Get recently updated/trending products, optionally filtered by category.

curl "https://api.buywhere.ai/v1/products/trending?category=electronics&limit=20" \
  -H "Authorization: Bearer <your-api-key>"

Python:

resp = requests.get(
    "https://api.buywhere.ai/v1/products/trending",
    params={"category": "electronics", "limit": 20},
    headers={"Authorization": "Bearer <your-api-key>"}
)
print(resp.json())

Export Products

Bulk export products in CSV or JSON format.

curl "https://api.buywhere.ai/v1/products/export?format=json&category=electronics&limit=100" \
  -H "Authorization: Bearer <your-api-key>" \
  -o products_export.json

For CSV format:

curl "https://api.buywhere.ai/v1/products/export?format=csv&limit=1000" \
  -H "Authorization: Bearer <your-api-key>" \
  -o products_export.csv

Python:

resp = requests.get(
    "https://api.buywhere.ai/v1/products/export",
    params={"format": "json", "limit": 100},
    headers={"Authorization": "Bearer <your-api-key>"},
    stream=True
)
with open("products_export.json", "wb") as f:
    for chunk in resp.iter_content(chunk_size=65536):
        f.write(chunk)

4. Full-Text Search

Search with Ranking

Advanced full-text search using PostgreSQL ts_rank for relevance ranking.

curl "https://api.buywhere.ai/v1/search?q=nike+shoes+men&limit=20&in_stock=true" \
  -H "Authorization: Bearer <your-api-key>"

Python:

resp = requests.get(
    "https://api.buywhere.ai/v1/search",
    params={"q": "nike shoes men", "limit": 20, "in_stock": True},
    headers={"Authorization": "Bearer <your-api-key>"}
)
print(resp.json())

With price filters:

curl "https://api.buywhere.ai/v1/search?q=running+shoes&min_price=50&max_price=200&platform=shopee_sg" \
  -H "Authorization: Bearer <your-api-key>"

Benchmark Search Performance

Run benchmark queries to measure search latency.

curl "https://api.buywhere.ai/v1/search/benchmark" \
  -H "Authorization: Bearer <your-api-key>"

Python:

resp = requests.get(
    "https://api.buywhere.ai/v1/search/benchmark",
    headers={"Authorization": "Bearer <your-api-key>"}
)
print(resp.json())

Response:

{
  "benchmarks": [
    {"query": "nike shoes", "elapsed_ms": 12.34, "result_count": 45},
    {"query": "iphone 15 case", "elapsed_ms": 8.21, "result_count": 120}
  ],
  "average_ms": 10.27,
  "total_queries": 10
}

5. Product Details

Get Product by ID

Retrieve a specific product by its unique ID.

curl "https://api.buywhere.ai/v1/products/12345" \
  -H "Authorization: Bearer <your-api-key>"

Python:

resp = requests.get(
    "https://api.buywhere.ai/v1/products/12345",
    headers={"Authorization": "Bearer <your-api-key>"}
)
print(resp.json())

Response:

{
  "id": 12345,
  "sku": "SHOPEE-ABC123",
  "source": "shopee_sg",
  "merchant_id": "shop_123",
  "name": "ASUS VivoBook 15 Laptop",
  "description": "Intel Core i5, 8GB RAM, 512GB SSD, Windows 11...",
  "price": 1299.00,
  "currency": "SGD",
  "buy_url": "https://shopee.sg/product/...",
  "affiliate_url": "https://buywhere.ai/track/...",
  "image_url": "https://cf.shopee.sg/file/...",
  "brand": "ASUS",
  "category": "Computers & Laptops",
  "category_path": "Electronics > Computers > Laptops",
  "rating": 4.5,
  "is_available": true,
  "metadata": {"original_price": 1499.00},
  "updated_at": "2026-04-04T10:30:00Z",
  "price_trend": "down"
}

Get Price History

Get historical price data for a product.

curl "https://api.buywhere.ai/v1/products/12345/price-history?limit=100" \
  -H "Authorization: Bearer <your-api-key>"

Python:

resp = requests.get(
    "https://api.buywhere.ai/v1/products/12345/price-history",
    params={"limit": 100},
    headers={"Authorization": "Bearer <your-api-key>"}
)
print(resp.json())

Response:

{
  "product_id": 12345,
  "total": 30,
  "entries": [
    {
      "price": 1299.00,
      "currency": "SGD",
      "source": "shopee_sg",
      "recorded_at": "2026-04-04T00:00:00Z"
    },
    {
      "price": 1349.00,
      "currency": "SGD",
      "source": "shopee_sg",
      "recorded_at": "2026-03-28T00:00:00Z"
    }
  ]
}

Get Price Statistics

Get price statistics and 30-day trend for a product.

curl "https://api.buywhere.ai/v1/products/12345/price-stats" \
  -H "Authorization: Bearer <your-api-key>"

Python:

resp = requests.get(
    "https://api.buywhere.ai/v1/products/12345/price-stats",
    headers={"Authorization": "Bearer <your-api-key>"}
)
print(resp.json())

Response:

{
  "current_price": 1299.00,
  "currency": "SGD",
  "min_price": 1199.00,
  "max_price": 1499.00,
  "avg_price": 1349.50,
  "price_trend": "down",
  "price_trend_pct": -10.5,
  "record_count": 30
}

Track Product Click

Track a click on a product and redirect to the affiliate URL.

curl -X POST "https://api.buywhere.ai/v1/products/12345/click" \
  -H "Authorization: Bearer <your-api-key>"

Python:

resp = requests.post(
    "https://api.buywhere.ai/v1/products/12345/click",
    headers={"Authorization": "Bearer <your-api-key>"}
)
# Returns 302 redirect to affiliate URL
print(resp.url)

6. Product Comparison

Compare Same Product Across Platforms

Given a source product ID, find matching products from other merchants.

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

Python:

resp = requests.get(
    "https://api.buywhere.ai/v1/products/compare",
    params={"product_id": 12345},
    headers={"Authorization": "Bearer <your-api-key>"}
)
print(resp.json())

Response:

{
  "source_product_id": 12345,
  "source_product_name": "ASUS VivoBook 15 Laptop",
  "total_matches": 5,
  "matches": [
    {
      "id": 67890,
      "sku": "LAZADA-XYZ789",
      "source": "lazada_sg",
      "name": "ASUS VivoBook 15 Laptop",
      "price": 1249.00,
      "currency": "SGD",
      "buy_url": "https://www.lazada.sg/products/...",
      "brand": "ASUS",
      "category": "Computers & Laptops",
      "match_score": 0.95
    }
  ]
}

Compare Multiple Products (Matrix)

Compare multiple products at once in a matrix view.

curl -X POST "https://api.buywhere.ai/v1/products/compare" \
  -H "Authorization: Bearer <your-api-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "product_ids": [12345, 67890, 11111],
    "min_price": 500,
    "max_price": 3000
  }'

Python:

resp = requests.post(
    "https://api.buywhere.ai/v1/products/compare",
    json={
        "product_ids": [12345, 67890, 11111],
        "min_price": 500,
        "max_price": 3000
    },
    headers={"Authorization": "Bearer <your-api-key>"}
)
print(resp.json())

Compare Product Differences (Diff)

Get a structured field-level diff between 2-5 products.

curl -X POST "https://api.buywhere.ai/v1/products/compare/diff" \
  -H "Authorization: Bearer <your-api-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "product_ids": [12345, 67890, 11111],
    "include_image_similarity": false
  }'

Python:

resp = requests.post(
    "https://api.buywhere.ai/v1/products/compare/diff",
    json={
        "product_ids": [12345, 67890, 11111],
        "include_image_similarity": False
    },
    headers={"Authorization": "Bearer <your-api-key>"}
)
print(resp.json())

Response:

{
  "products": [
    {
      "id": 12345,
      "name": "ASUS VivoBook 15",
      "price": 1299.00,
      "price_rank": 2
    },
    {
      "id": 67890,
      "name": "ASUS VivoBook 15",
      "price": 1249.00,
      "price_rank": 1
    }
  ],
  "field_diffs": [
    {
      "field": "price",
      "values": [1299.00, 1249.00],
      "all_identical": false
    }
  ],
  "identical_fields": ["brand", "category"],
  "cheapest_product_id": 67890,
  "most_expensive_product_id": 12345,
  "price_spread": 50.00,
  "price_spread_pct": 3.85
}

7. Deals Discovery

Find Discounted Products

Find products currently priced below their historical/original price.

curl "https://api.buywhere.ai/v1/deals?min_discount_pct=20&limit=20" \
  -H "Authorization: Bearer <your-api-key>"

Python:

resp = requests.get(
    "https://api.buywhere.ai/v1/deals",
    params={"min_discount_pct": 20, "limit": 20},
    headers={"Authorization": "Bearer <your-api-key>"}
)
print(resp.json())

With category filter:

curl "https://api.buywhere.ai/v1/deals?category=electronics&min_discount_pct=30" \
  -H "Authorization: Bearer <your-api-key>"

Response:

{
  "total": 45,
  "limit": 20,
  "offset": 0,
  "items": [
    {
      "id": 12345,
      "name": "Samsung 55\" Smart TV",
      "price": 699.00,
      "original_price": 999.00,
      "discount_pct": 30.0,
      "currency": "SGD",
      "source": "shopee_sg",
      "category": "TVs",
      "buy_url": "https://shopee.sg/product/...",
      "affiliate_url": "https://buywhere.ai/track/...",
      "image_url": "https://cf.shopee.sg/file/..."
    }
  ]
}

8. Categories

List Categories (Flat)

List all available categories with product counts.

curl "https://api.buywhere.ai/v1/categories" \
  -H "Authorization: Bearer <your-api-key>"

Python:

resp = requests.get(
    "https://api.buywhere.ai/v1/categories",
    headers={"Authorization": "Bearer <your-api-key>"}
)
print(resp.json())

Response:

{
  "categories": [
    {"name": "Electronics", "count": 15420},
    {"name": "Fashion", "count": 12350},
    {"name": "Home & Garden", "count": 8920}
  ],
  "total": 25
}

Get Category Taxonomy

Get the full unified category taxonomy.

curl "https://api.buywhere.ai/v1/categories/taxonomy" \
  -H "Authorization: Bearer <your-api-key>"

Python:

resp = requests.get(
    "https://api.buywhere.ai/v1/categories/taxonomy",
    headers={"Authorization": "Bearer <your-api-key>"}
)
print(resp.json())

Get Category by ID

Get a specific category by its ID.

curl "https://api.buywhere.ai/v1/categories/electronics" \
  -H "Authorization: Bearer <your-api-key>"

Python:

resp = requests.get(
    "https://api.buywhere.ai/v1/categories/electronics",
    headers={"Authorization": "Bearer <your-api-key>"}
)
print(resp.json())

Browse Products by Category

Get products filtered by category.

curl "https://api.buywhere.ai/v1/categories/electronics/products?limit=20&offset=0" \
  -H "Authorization: Bearer <your-api-key>"

Python:

resp = requests.get(
    "https://api.buywhere.ai/v1/categories/electronics/products",
    params={"limit": 20, "offset": 0},
    headers={"Authorization": "Bearer <your-api-key>"}
)
print(resp.json())

With price and source filters:

curl "https://api.buywhere.ai/v1/categories/electronics/products?min_price=100&max_price=500&source=shopee_sg" \
  -H "Authorization: Bearer <your-api-key>"

9. Analytics

Get Click Analytics

Get click analytics for your API key including daily/weekly trends and top products.

curl "https://api.buywhere.ai/v1/analytics/clicks?days=7&limit=10" \
  -H "Authorization: Bearer <your-api-key>"

Python:

resp = requests.get(
    "https://api.buywhere.ai/v1/analytics/clicks",
    params={"days": 7, "limit": 10},
    headers={"Authorization": "Bearer <your-api-key>"}
)
print(resp.json())

Response:

{
  "total_clicks": 1543,
  "daily_clicks": [
    {"date": "2026-04-04", "clicks": 245},
    {"date": "2026-04-03", "clicks": 312}
  ],
  "weekly_clicks": [
    {"date": "2026-04-04", "clicks": 245},
    {"date": "2026-04-03", "clicks": 312}
  ],
  "top_products": [
    {"product_id": 12345, "clicks": 89},
    {"product_id": 67890, "clicks": 76}
  ]
}

10. Click Tracking

Track Click by Tracking ID

Track a click using a pre-generated tracking ID and redirect to affiliate URL.

curl "https://api.buywhere.ai/v1/track/{tracking_id}" \
  -H "Authorization: Bearer <your-api-key>"

Python:

resp = requests.get(
    f"https://api.buywhere.ai/v1/track/{tracking_id}",
    headers={"Authorization": "Bearer <your-api-key>"},
    allow_redirects=False
)
print(resp.headers["Location"])  # Redirect URL

Verify Tracking ID

Verify a tracking ID without recording a click.

curl "https://api.buywhere.ai/v1/track/{tracking_id}/verify" \
  -H "Authorization: Bearer <your-api-key>"

Python:

resp = requests.get(
    f"https://api.buywhere.ai/v1/track/{tracking_id}/verify",
    headers={"Authorization": "Bearer <your-api-key>"}
)
print(resp.json())

Response:

{
  "valid": true,
  "product_id": 12345,
  "platform": "shopee_sg",
  "destination_url": "https://shopee.sg/product/..."
}

11. Batch Ingestion

Ingest Product Batch

Batch ingest products from scraping pipelines. Upserts by SKU + source.

curl -X POST "https://api.buywhere.ai/v1/ingest/products" \
  -H "Authorization: Bearer <your-api-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "source": "shopee_sg",
    "products": [
      {
        "sku": "SHOPEE-ABC123",
        "merchant_id": "shop_123",
        "title": "ASUS VivoBook 15 Laptop",
        "description": "Intel Core i5, 8GB RAM",
        "price": 1299.00,
        "currency": "SGD",
        "url": "https://shopee.sg/product/...",
        "image_url": "https://cf.shopee.sg/file/...",
        "brand": "ASUS",
        "category": "Computers & Laptops",
        "is_active": true,
        "is_available": true,
        "metadata": {"original_price": 1499.00}
      }
    ]
  }'

Python:

resp = requests.post(
    "https://api.buywhere.ai/v1/ingest/products",
    json={
        "source": "shopee_sg",
        "products": [
            {
                "sku": "SHOPEE-ABC123",
                "merchant_id": "shop_123",
                "title": "ASUS VivoBook 15 Laptop",
                "description": "Intel Core i5, 8GB RAM",
                "price": 1299.00,
                "currency": "SGD",
                "url": "https://shopee.sg/product/...",
                "image_url": "https://cf.shopee.sg/file/...",
                "brand": "ASUS",
                "category": "Computers & Laptops",
                "is_active": True,
                "is_available": True,
                "metadata": {"original_price": 1499.00}
            }
        ]
    },
    headers={"Authorization": "Bearer <your-api-key>"}
)
print(resp.json())

Response:

{
  "run_id": 42,
  "status": "completed",
  "rows_inserted": 1,
  "rows_updated": 0,
  "rows_failed": 0,
  "errors": []
}

List Ingestion Runs

List recent ingestion runs.

curl "https://api.buywhere.ai/v1/ingest/runs?limit=20&offset=0" \
  -H "Authorization: Bearer <your-api-key>"

Python:

resp = requests.get(
    "https://api.buywhere.ai/v1/ingest/runs",
    params={"limit": 20, "offset": 0},
    headers={"Authorization": "Bearer <your-api-key>"}
)
print(resp.json())

Get Ingestion Run by ID

Get details of a specific ingestion run.

curl "https://api.buywhere.ai/v1/ingest/runs/42" \
  -H "Authorization: Bearer <your-api-key>"

Python:

resp = requests.get(
    "https://api.buywhere.ai/v1/ingest/runs/42",
    headers={"Authorization": "Bearer <your-api-key>"}
)
print(resp.json())

12. Ingestion Run Tracking

Register New Ingestion Run

curl -X POST "https://api.buywhere.ai/v1/ingestion" \
  -H "Authorization: Bearer <your-api-key>" \
  -H "Content-Type: application/json" \
  -d '{"source": "lazada_sg"}'

Python:

resp = requests.post(
    "https://api.buywhere.ai/v1/ingestion",
    json={"source": "lazada_sg"},
    headers={"Authorization": "Bearer <your-api-key>"}
)
run_id = resp.json()["id"]
print(f"Created run ID: {run_id}")

Response:

{
  "id": 43,
  "source": "lazada_sg",
  "status": "running",
  "started_at": "2026-04-04T12:00:00Z",
  "finished_at": null,
  "rows_inserted": 0,
  "rows_updated": 0,
  "rows_failed": 0
}

Update Ingestion Run Progress

Update row counts for a running ingestion run.

curl -X PATCH "https://api.buywhere.ai/v1/ingestion/43" \
  -H "Authorization: Bearer <your-api-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "rows_inserted": 500,
    "rows_updated": 120,
    "rows_failed": 5
  }'

Python:

resp = requests.patch(
    "https://api.buywhere.ai/v1/ingestion/43",
    json={
        "rows_inserted": 500,
        "rows_updated": 120,
        "rows_failed": 5
    },
    headers={"Authorization": "Bearer <your-api-key>"}
)
print(resp.json())

Mark Ingestion Run Complete

Mark an ingestion run as completed, failed, or cancelled.

curl -X POST "https://api.buywhere.ai/v1/ingestion/43/complete" \
  -H "Authorization: Bearer <your-api-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "completed",
    "rows_inserted": 1000,
    "rows_updated": 250,
    "rows_failed": 10
  }'

Python:

resp = requests.post(
    "https://api.buywhere.ai/v1/ingestion/43/complete",
    json={
        "status": "completed",
        "rows_inserted": 1000,
        "rows_updated": 250,
        "rows_failed": 10
    },
    headers={"Authorization": "Bearer <your-api-key>"}
)
print(resp.json())

Get Ingestion Run Status

Get the current status of an ingestion run.

curl "https://api.buywhere.ai/v1/ingestion/43" \
  -H "Authorization: Bearer <your-api-key>"

Python:

resp = requests.get(
    "https://api.buywhere.ai/v1/ingestion/43",
    headers={"Authorization": "Bearer <your-api-key>"}
)
print(resp.json())

Get Ingestion Statistics

Get aggregate statistics across all ingestion runs.

curl "https://api.buywhere.ai/v1/ingestion/stats" \
  -H "Authorization: Bearer <your-api-key>"

Python:

resp = requests.get(
    "https://api.buywhere.ai/v1/ingestion/stats",
    headers={"Authorization": "Bearer <your-api-key>"}
)
print(resp.json())

Response:

{
  "total_runs": 150,
  "completed_runs": 142,
  "failed_runs": 5,
  "running_runs": 3,
  "total_rows_inserted": 250000,
  "total_rows_updated": 75000,
  "total_rows_failed": 500
}

List Ingestion Runs

List recent ingestion runs with optional filters.

curl "https://api.buywhere.ai/v1/ingestion?source=lazada_sg&status=completed&limit=20" \
  -H "Authorization: Bearer <your-api-key>"

Python:

resp = requests.get(
    "https://api.buywhere.ai/v1/ingestion",
    params={"source": "lazada_sg", "status": "completed", "limit": 20},
    headers={"Authorization": "Bearer <your-api-key>"}
)
print(resp.json())

13. Catalog Quality

Get Catalog Health

Get catalog health and quality report.

curl "https://api.buywhere.ai/v1/catalog/health" \
  -H "Authorization: Bearer <your-api-key>"

Python:

resp = requests.get(
    "https://api.buywhere.ai/v1/catalog/health",
    headers={"Authorization": "Bearer <your-api-key>"}
)
print(resp.json())

List Incomplete Products

List products missing required fields (title, price, or URL).

curl "https://api.buywhere.ai/v1/catalog/incomplete?limit=20&offset=0" \
  -H "Authorization: Bearer <your-api-key>"

Python:

resp = requests.get(
    "https://api.buywhere.ai/v1/catalog/incomplete",
    params={"limit": 20, "offset": 0},
    headers={"Authorization": "Bearer <your-api-key>"}
)
print(resp.json())

With source filter:

curl "https://api.buywhere.ai/v1/catalog/incomplete?source=shopee_sg" \
  -H "Authorization: Bearer <your-api-key>"

Get Catalog Statistics

Get catalog statistics including total products by platform and category.

curl "https://api.buywhere.ai/v1/catalog/stats" \
  -H "Authorization: Bearer <your-api-key>"

Python:

resp = requests.get(
    "https://api.buywhere.ai/v1/catalog/stats",
    headers={"Authorization": "Bearer <your-api-key>"}
)
print(resp.json())

Response:

{
  "generated_at": "2026-04-04T12:00:00Z",
  "total_products": 500000,
  "by_platform": {
    "shopee_sg": 200000,
    "lazada_sg": 150000,
    "carousell": 100000,
    "amazon_sg": 50000
  },
  "by_category": {
    "Electronics": 180000,
    "Fashion": 120000,
    "Home & Garden": 80000
  }
}

14. Admin

Get Admin Statistics

Get admin dashboard statistics including products, API keys, and clicks.

curl "https://api.buywhere.ai/v1/admin/stats" \
  -H "Authorization: Bearer <your-api-key>"

Python:

resp = requests.get(
    "https://api.buywhere.ai/v1/admin/stats",
    headers={"Authorization": "Bearer <your-api-key>"}
)
print(resp.json())

Response:

{
  "total_products": 500000,
  "products_by_source": {
    "shopee_sg": 200000,
    "lazada_sg": 150000
  },
  "products_by_category": [
    {"category": "Electronics", "count": 180000}
  ],
  "total_api_keys": 250,
  "active_keys_last_24h": 45,
  "total_clicks_today": 3200,
  "total_clicks_week": 18500,
  "top_clicked_products": [
    {"product_id": 12345, "clicks": 150}
  ],
  "data_freshness": {
    "oldest_updated_at": "2026-04-01T00:00:00Z",
    "newest_updated_at": "2026-04-04T12:00:00Z"
  }
}

Query API Logs

Query recent API request logs.

curl "https://api.buywhere.ai/v1/admin/logs?limit=100&offset=0" \
  -H "Authorization: Bearer <your-api-key>"

With filters:

curl "https://api.buywhere.ai/v1/admin/logs?path=/v1/products&status=200&limit=50" \
  -H "Authorization: Bearer <your-api-key>"

Python:

resp = requests.get(
    "https://api.buywhere.ai/v1/admin/logs",
    params={"path": "/v1/products", "status": 200, "limit": 50},
    headers={"Authorization": "Bearer <your-api-key>"}
)
print(resp.json())

15. System Status

Get Catalog Status

Get overall catalog health, platform counts, and goal progress.

curl "https://api.buywhere.ai/v1/status" \
  -H "Authorization: Bearer <your-api-key>"

Python:

resp = requests.get(
    "https://api.buywhere.ai/v1/status",
    headers={"Authorization": "Bearer <your-api-key>"}
)
print(resp.json())

Response:

{
  "total_unique_products": 500000,
  "platforms": [
    {
      "source": "shopee_sg",
      "product_count": 200000,
      "last_updated": "2026-04-04T12:00:00Z"
    }
  ],
  "ingestion_runs": [
    {
      "source": "shopee_sg",
      "last_run_at": "2026-04-04T11:00:00Z",
      "last_run_status": "completed",
      "last_rows_inserted": 5000,
      "last_rows_updated": 1200
    }
  ],
  "goal_million": 1.0,
  "progress_percent": 50.0
}

Get Scraper Health Status

Get detailed health status for each scraper/platform.

curl "https://api.buywhere.ai/v1/status/scrapers" \
  -H "Authorization: Bearer <your-api-key>"

Python:

resp = requests.get(
    "https://api.buywhere.ai/v1/status/scrapers",
    headers={"Authorization": "Bearer <your-api-key>"}
)
print(resp.json())

Get System Health

Get system health including database latency and scraper status.

curl "https://api.buywhere.ai/v1/status/health" \
  -H "Authorization: Bearer <your-api-key>"

Python:

resp = requests.get(
    "https://api.buywhere.ai/v1/status/health",
    headers={"Authorization": "Bearer <your-api-key>"}
)
print(resp.json())

Response:

{
  "db": {
    "status": "healthy",
    "latency_ms": 5.2,
    "pool_size": 10,
    "pool_available": 8
  },
  "scrapers": {
    "shopee_sg": {"status": "healthy", "last_run": "2026-04-04T11:00:00Z"},
    "lazada_sg": {"status": "healthy", "last_run": "2026-04-04T10:30:00Z"}
  }
}

Common Error Responses

401 Unauthorized

{"detail": "Invalid or missing API key"}

403 Forbidden

{"detail": "Bootstrap is only allowed when no API keys exist"}

404 Not Found

{"detail": "Product not found"}

422 Validation Error

{"detail": "min_price cannot be greater than max_price"}

429 Rate Limited

{"detail": "Rate limit exceeded. Try again in 60 seconds."}

Rate Limits

Endpoint Group	Limit
Default	1000/minute
Developer signup	5/hour
Key bootstrap	1 (first-time only)
Ingestion (batch)	100/minute
Ingestion (tracking)	100/minute
Catalog health	100/minute

See docs/rate-limits.md for full details.

16. V2 API Endpoints

The v2 API provides enhanced product discovery with cursor-based pagination, streaming, and agent-optimized responses.

V2 Product Search

Full-text search with region and country filtering.

curl "https://api.buywhere.ai/v2/search?q=laptop&region=sg&limit=10" \
  -H "Authorization: Bearer <your-api-key>"

Python:

resp = requests.get(
    "https://api.buywhere.ai/v2/search",
    params={"q": "laptop", "region": "sg", "limit": 10},
    headers={"Authorization": "Bearer <your-api-key>"}
)
print(resp.json())

With filters:

curl "https://api.buywhere.ai/v2/search?q=iphone&country=SG,MY&min_price=500&max_price=2000&in_stock=true" \
  -H "Authorization: Bearer <your-api-key>"

Response:

{
  "query": "iphone",
  "total": 342,
  "limit": 10,
  "offset": 0,
  "items": [
    {
      "id": 18472931,
      "sku": "IPHONE15PRO256",
      "source": "shopee_sg",
      "title": "iPhone 15 Pro 256GB Natural Titanium",
      "price": "1349.00",
      "currency": "SGD",
      "buy_url": "https://shopee.sg/product/...",
      "affiliate_url": "https://buywhere.ai/track/...",
      "brand": "Apple",
      "category": "Mobile Phones",
      "rating": 4.8,
      "review_count": 2341,
      "is_available": true
    }
  ],
  "has_more": true
}

V2 Product List with Cursor Pagination

List products with cursor-based pagination for efficient deep scrolling.

curl "https://api.buywhere.ai/v2/products?category=electronics&limit=20" \
  -H "Authorization: Bearer <your-api-key>"

Using cursor pagination:

# First request
curl "https://api.buywhere.ai/v2/products?limit=20" \
  -H "Authorization: Bearer <your-api-key>"

# Next page using 'after' cursor
curl "https://api.buywhere.ai/v2/products?limit=20&after=18472000" \
  -H "Authorization: Bearer <your-api-key>"

V2 Batch Product Lookup (Agent-Optimized)

Batch lookup up to 100 products by ID in a single request.

curl -X POST "https://api.buywhere.ai/v2/products/batch-details" \
  -H "Authorization: Bearer <your-api-key>" \
  -H "Content-Type: application/json" \
  -d '{"product_ids": [18472931, 18472932, 18472933], "include_metadata": true}'

Python:

resp = requests.post(
    "https://api.buywhere.ai/v2/products/batch-details",
    headers={"Authorization": "Bearer <your-api-key>"},
    json={
        "product_ids": [18472931, 18472932, 18472933],
        "include_metadata": True
    }
)
print(resp.json())

Response:

{
  "results": [
    {
      "id": 18472931,
      "sku": "IPHONE15PRO256",
      "source": "shopee_sg",
      "title": "iPhone 15 Pro 256GB Natural Titanium",
      "price": "1349.00",
      "currency": "SGD",
      "is_available": true,
      "confidence_score": 0.95
    }
  ],
  "errors": []
}

V2 Streaming Product Updates

Subscribe to real-time product update stream.

curl "https://api.buywhere.ai/v2/products/stream?category=electronics" \
  -H "Authorization: Bearer <your-api-key>"

V2 Price Stream

Subscribe to real-time price change notifications.

curl "https://api.buywhere.ai/v2/prices/stream?min_price=100&max_price=500" \
  -H "Authorization: Bearer <your-api-key>"

17. Agent-Native Endpoints (v2/agents)

The agent-native endpoints are optimized for AI agent workflows with confidence scoring, availability predictions, and competitor analysis.

Agent Search

Natural language product search optimized for AI agents.

curl "https://api.buywhere.ai/v2/agents/search?q=best+laptop+for+students&limit=10" \
  -H "Authorization: Bearer <your-api-key>"

Python:

resp = requests.get(
    "https://api.buywhere.ai/v2/agents/search",
    params={"q": "best laptop for students", "limit": 10},
    headers={"Authorization": "Bearer <your-api-key>"}
)
print(resp.json())

Response:

{
  "query": "best laptop for students",
  "total": 156,
  "results": [
    {
      "id": 18472931,
      "sku": "ASUS-VIVOBOOK-15",
      "source": "shopee_sg",
      "title": "ASUS VivoBook 15 Laptop",
      "price": "1299.00",
      "currency": "SGD",
      "url": "https://shopee.sg/product/...",
      "brand": "ASUS",
      "category": "Computers & Laptops",
      "rating": 4.5,
      "review_count": 892,
      "is_available": true,
      "confidence_score": 0.92,
      "availability_prediction": "in_stock",
      "competitor_count": 15,
      "buybox_price": "1249.00",
      "affiliate_url": "https://buywhere.ai/track/..."
    }
  ]
}

Agent Price Comparison

Compare prices for a product across all platforms.

curl "https://api.buywhere.ai/v2/agents/price-comparison?product_name=iphone+15+pro+256gb" \
  -H "Authorization: Bearer <your-api-key>"

Python:

resp = requests.get(
    "https://api.buywhere.ai/v2/agents/price-comparison",
    params={"product_name": "iphone 15 pro 256gb"},
    headers={"Authorization": "Bearer <your-api-key>"}
)
print(resp.json())

Response:

{
  "query": "iphone 15 pro 256gb",
  "total": 8,
  "results": [
    {
      "id": 18472931,
      "sku": "IPHONE15PRO256-SG",
      "source": "shopee_sg",
      "title": "iPhone 15 Pro 256GB Natural Titanium",
      "price": "1349.00",
      "currency": "SGD",
      "buy_url": "https://shopee.sg/product/...",
      "brand": "Apple",
      "rating": 4.8,
      "review_count": 2341,
      "is_available": true,
      "confidence_score": 0.95,
      "availability_prediction": "in_stock",
      "competitor_count": 8,
      "buybox_price": "1349.00"
    },
    {
      "id": 18472932,
      "sku": "IPHONE15PRO256-LAZ",
      "source": "lazada_sg",
      "title": "iPhone 15 Pro 256GB - Natural Titanium",
      "price": "1399.00",
      "currency": "SGD",
      "buy_url": "https://www.lazada.sg/products/...",
      "brand": "Apple",
      "rating": 4.7,
      "review_count": 1245,
      "is_available": true,
      "confidence_score": 0.93,
      "availability_prediction": "in_stock",
      "competitor_count": 8,
      "buybox_price": "1349.00"
    }
  ],
  "highlights": {
    "cheapest": {"source": "shopee_sg", "price": "1349.00"},
    "best_rated": {"source": "shopee_sg", "rating": 4.8},
    "fastest_shipping": {"source": "lazada_sg", "shipping_days": 1}
  }
}

Agent Product Exploration

Randomized product discovery for agent exploration.

curl "https://api.buywhere.ai/v2/agents/explore?category=electronics&limit=10" \
  -H "Authorization: Bearer <your-api-key>"

Python:

resp = requests.get(
    "https://api.buywhere.ai/v2/agents/explore",
    params={"category": "electronics", "limit": 10},
    headers={"Authorization": "Bearer <your-api-key>"}
)
print(resp.json())

Agent Best Price Lookup

Find the best price across all platforms for a product.

curl "https://api.buywhere.ai/v2/agents/best-price?product_name=nike+air+max&limit=5" \
  -H "Authorization: Bearer <your-api-key>"

Python:

resp = requests.get(
    "https://api.buywhere.ai/v2/agents/best-price",
    params={"product_name": "nike air max", "limit": 5},
    headers={"Authorization": "Bearer <your-api-key>"}
)
print(resp.json())

Agent Batch Lookup

Batch lookup products by ID with full metadata.

curl -X POST "https://api.buywhere.ai/v2/agents/batch-lookup" \
  -H "Authorization: Bearer <your-api-key>" \
  -H "Content-Type: application/json" \
  -d '{"product_ids": [18472931, 18472932, 18472933], "target_currency": "USD", "affiliate_links": true}'

Python:

resp = requests.post(
    "https://api.buywhere.ai/v2/agents/batch-lookup",
    headers={"Authorization": "Bearer <your-api-key>"},
    json={
        "product_ids": [18472931, 18472932, 18472933],
        "target_currency": "USD",
        "affiliate_links": True
    }
)
print(resp.json())

Response:

{
  "results": [
    {
      "id": 18472931,
      "sku": "IPHONE15PRO256",
      "source": "shopee_sg",
      "title": "iPhone 15 Pro 256GB Natural Titanium",
      "price": "999.00",
      "currency": "USD",
      "price_sgd": "1349.00",
      "url": "https://shopee.sg/product/...",
      "brand": "Apple",
      "category": "Mobile Phones",
      "rating": 4.8,
      "review_count": 2341,
      "is_available": true,
      "confidence_score": 0.95,
      "availability_prediction": "in_stock",
      "competitor_count": 8,
      "buybox_price": "999.00",
      "affiliate_url": "https://buywhere.ai/track/..."
    }
  ],
  "total": 3,
  "has_more": false
}

Agent Bulk Compare

Bulk compare multiple products by ID.

curl -X POST "https://api.buywhere.ai/v2/agents/bulk-compare" \
  -H "Authorization: Bearer <your-api-key>" \
  -H "Content-Type: application/json" \
  -d '{"product_ids": [18472931, 18472932, 18472933]}'

Python:

resp = requests.post(
    "https://api.buywhere.ai/v2/agents/bulk-compare",
    headers={"Authorization": "Bearer <your-api-key>"},
    json={"product_ids": [18472931, 18472932, 18472933]}
)
print(resp.json())

Agent Compare Matrix

Compare multiple products in a matrix format.

curl -X POST "https://api.buywhere.ai/v2/agents/compare-matrix" \
  -H "Authorization: Bearer <your-api-key>" \
  -H "Content-Type: application/json" \
  -d '{"product_ids": [18472931, 18472932, 18472933], "include_fields": ["price", "rating", "review_count"]}'

Python:

resp = requests.post(
    "https://api.buywhere.ai/v2/agents/compare-matrix",
    headers={"Authorization": "Bearer <your-api-key>"},
    json={
        "product_ids": [18472931, 18472932, 18472933],
        "include_fields": ["price", "rating", "review_count"]
    }
)
print(resp.json())

18. MCP Integration Examples

Connect BuyWhere to AI agents via the Model Context Protocol (MCP).

Claude Desktop Configuration

Add to your Claude Desktop config (~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

{
  "mcpServers": {
    "buywhere": {
      "command": "python",
      "args": ["/path/to/buywhere-api/mcp_server.py"],
      "env": {
        "BUYWHERE_API_KEY": "your_api_key_here",
        "BUYWHERE_API_URL": "https://api.buywhere.ai"
      }
    }
  }
}

Available MCP Tools

Tool	Description
`search_products`	Full-text search across 1.5M+ products
`get_product`	Get product details by BuyWhere ID
`compare_prices`	Compare prices across platforms
`get_deals`	Find products with 10%+ discounts
`find_deals`	Find products with 20%+ discounts
`browse_categories`	Browse category taxonomy tree
`get_category_products`	Get products within a category

Example MCP Tool Call (search_products)

{
  "tool": "search_products",
  "params": {
    "query": "iphone 15 pro",
    "limit": 5,
    "platform": "shopee_sg"
  }
}

Example MCP Tool Call (compare_prices)

{
  "tool": "compare_prices",
  "params": {
    "product_name": "iphone 15 pro 256gb",
    "limit": 10
  }
}

Running MCP Server via Docker

docker run -d \
  --name buywhere-mcp \
  -p 8080:8080 \
  -e BUYWHERE_API_KEY="your_api_key_here" \
  -e BUYWHERE_API_URL="https://api.buywhere.ai" \
  buywhere-mcp

See docs/guides/mcp-deployment.md for full MCP deployment guide.

API_EXAMPLES

BuyWhere API Usage Examples

Table of Contents

1. Authentication & Developer Setup

Developer Signup (No Auth)

Get Developer Profile

2. API Keys

Bootstrap First Key (No Auth)

Create API Key

List API Keys

Revoke API Key

3. Product Search

Search Products

Find Best Price

Get Trending Products

Export Products

4. Full-Text Search

Search with Ranking

Benchmark Search Performance

5. Product Details

Get Product by ID

Get Price History

Get Price Statistics

Track Product Click

6. Product Comparison

Compare Same Product Across Platforms

Compare Multiple Products (Matrix)

Compare Product Differences (Diff)

7. Deals Discovery

Find Discounted Products

8. Categories

List Categories (Flat)

Get Category Taxonomy

Get Category by ID

Browse Products by Category

9. Analytics

Get Click Analytics

10. Click Tracking

Track Click by Tracking ID

Verify Tracking ID

11. Batch Ingestion

Ingest Product Batch

List Ingestion Runs

Get Ingestion Run by ID

12. Ingestion Run Tracking

Register New Ingestion Run

Update Ingestion Run Progress

Mark Ingestion Run Complete

Get Ingestion Run Status

Get Ingestion Statistics

List Ingestion Runs

13. Catalog Quality

Get Catalog Health

List Incomplete Products

Get Catalog Statistics

14. Admin

Get Admin Statistics

Query API Logs

15. System Status

Get Catalog Status

Get Scraper Health Status

Get System Health

Common Error Responses

401 Unauthorized

403 Forbidden

404 Not Found

422 Validation Error

429 Rate Limited

Rate Limits

16. V2 API Endpoints

V2 Product Search

V2 Product List with Cursor Pagination

V2 Batch Product Lookup (Agent-Optimized)

V2 Streaming Product Updates

V2 Price Stream

17. Agent-Native Endpoints (v2/agents)

Agent Search

Agent Price Comparison

Agent Product Exploration

Agent Best Price Lookup