buywhere-api-v1-launch

title: BuyWhere API v1.0 Launch: Powering AI Agent Commerce Globally date: 2026-04-04

BuyWhere API v1.0 Launch: Powering AI Agent Commerce Globally

Today we're thrilled to announce the general availability of BuyWhere API v1.0 — the product catalog infrastructure built specifically for AI agents doing commerce in Singapore and beyond.

What is BuyWhere?

BuyWhere indexes real-time product data from Singapore's major e-commerce platforms into a single, queryable API. It gives AI agents the ability to:

Search products across platforms with relevant ranking (BM25/FTS5)
Compare prices for the same product across Shopee, Lazada, Amazon.sg, and more
Track affiliate clicks for monetization
Ingest new product data from scraping pipelines

If you're building an AI shopping agent, a price comparison tool, a deal-finding bot, or any product discovery experience — BuyWhere is your API layer.

What's New in v1.0

Search — BM25-ranked, not just keyword match

The /v1/search endpoint uses PostgreSQL's websearch_to_tsquery with ts_rank_cd for BM25-style ranking. Results are ordered by relevance, not just recency. You can filter by category, price range, platform, and availability in a single request.

curl "https://api.buywhere.ai/v1/search?q=iphone+15+pro+case&platform=shopee_sg&max_price=50" \
  -H "X-API-Key: $BUYWHERE_API_KEY"

Price Comparison — find the cheapest anywhere

/v1/products/best-price finds the lowest price across all platforms for a given product name. POST /v1/products/compare/diff directly compares 2–5 products you already have IDs for, returning a structured diff of every field plus price spread percentage.

Deals — discount discovery

GET /v1/deals surfaces products currently priced below their original price. Filter by minimum discount percentage and sort by discount depth (biggest savings first).

Scraping Pipeline Integration

Two ingestion systems for different pipeline styles:

/v1/ingest/products — push model: send a batch of products in one request; the API handles upserts via PostgreSQL ON CONFLICT DO UPDATE.
/v1/ingestion — pull/track model: register a run, push periodic row counts, then mark it complete; cache is automatically invalidated on completion.

Both integrate with Redis caching so search results reflect fresh data immediately after ingestion.

AI Agent Integration — MCP Server + Python SDK

Two first-class developer experiences for AI agents:

MCP Server (mcp_server.py) — connect BuyWhere to Claude Desktop, Cursor, or any MCP-compatible AI client in under 5 minutes. Four tools: search_products, get_product, compare_prices, get_deals.

# macOS: add to ~/Library/Application Support/Claude/claude_desktop_config.json
{
  "mcpServers": {
    "buywhere": {
      "command": "python",
      "args": ["/path/to/buywhere-api/mcp_server.py"],
      "env": {
        "BUYWHERE_API_KEY": "your_key",
        "BUYWHERE_API_URL": "https://api.buywhere.ai"
      }
    }
  }
}

Python SDK (buywhere-sdk on PyPI) — integrate into Python AI pipelines with full type safety.

from buywhere_sdk import BuyWhereClient

client = BuyWhereClient(api_key="...")
results = client.search("nike air max", max_price=150)

LangChain and CrewAI integrations included.

All v1.0 Endpoints

Method	Path	Description
GET	`/v1/search`	Full-text search with BM25 ranking
GET	`/v1/search/benchmark`	Query latency benchmark
GET	`/v1/products`	Search + filter products
GET	`/v1/products/{id}`	Get product by ID
GET	`/v1/products/best-price`	Cheapest listing across platforms
GET	`/v1/products/compare`	Cross-platform match comparison
POST	`/v1/products/compare`	Batch compare multiple products
POST	`/v1/products/compare/diff`	Direct diff of 2–5 products
GET	`/v1/products/trending`	Recently updated products
GET	`/v1/products/export`	Streaming CSV/JSON export
POST	`/v1/products/{id}/click`	Track click + redirect
GET	`/v1/categories`	List all categories
GET	`/v1/deals`	Discounted products
GET	`/v1/catalog/health`	Catalog quality report
GET	`/v1/catalog/incomplete`	Products with missing fields
GET	`/v1/catalog/stats`	Catalog statistics
POST	`/v1/ingest/products`	Batch ingest from scraper
GET	`/v1/ingest/runs`	List ingestion runs
GET	`/v1/ingest/runs/{id}`	Get specific ingestion run
POST	`/v1/ingestion`	Register scraping run
GET	`/v1/ingestion`	List ingestion runs
GET	`/v1/ingestion/{id}`	Get ingestion run
PATCH	`/v1/ingestion/{id}`	Update run progress
POST	`/v1/ingestion/{id}/complete`	Mark run complete
GET	`/v1/ingestion/stats`	Aggregate ingestion stats
GET	`/v1/track/{id}`	Track click via tracking ID
GET	`/v1/track/{id}/verify`	Verify tracking ID
GET	`/v1/analytics/clicks`	Click analytics
POST	`/v1/keys`	Create API key
GET	`/v1/keys`	List your API keys
DELETE	`/v1/keys/{id}`	Revoke API key
GET	`/v1/admin/stats`	Admin dashboard
GET	`/v1/admin/logs`	Query API logs
GET	`/v1/status`	Catalog status
GET	`/v1/status/scrapers`	Scraper health
GET	`/v1/status/health`	System health

Full OpenAPI 3.1 spec at openapi.yaml — import into Postman, Insomnia, or any OpenAPI-compatible tool.

Get Started

Sign up at buywhere.ai/api to get your API key
Read the docs at api.buywhere.ai/docs
Install the SDK: pip install buywhere-sdk
Connect to Claude: follow the guide in MCP.md

What's Next

Over the coming weeks we'll be adding:

Price history — 30-day price trend data for every product
Wishlist alerts — notify users when a tracked product drops below a target price
Additional platforms — Qoo10, Carousell, and regional platforms across Southeast Asia
Streaming search — SSE-based real-time search results

Follow the project at github.com/buywhere/buywhere-api.

Questions? Email eng@buywhere.com.

BuyWhere API v1.0 — April 4, 2026