CHANGELOG

BuyWhere API Changelog

This changelog documents the evolution of the BuyWhere agent-native product catalog API. It covers all public endpoint changes, additions, and migrations for every release.

API versioning: The API is versioned in the URL path (/v1/*). SDK versions move independently.

v1.0.0 — 2026-04-04

Status: Initial public v1 release
Breaking changes: None (first public release)

Added

Search & Discovery

Endpoint	Description
`GET /v1/search`	Full-text product search via PostgreSQL FTS5 with BM25 ranking (`ts_rank_cd`). Filters: category, price range, platform, country, in_stock, currency. Paginated with `has_more` cursor.
`GET /v1/search/semantic`	Semantic search using embedding-based similarity for natural language queries. Falls back to keyword search when embeddings are unavailable.
`GET /v1/search/suggest`	Autocomplete with FTS prefix queries for search-as-you-type UX.
`GET /v1/search/benchmark`	Runs 10 representative search queries and reports per-query latency in milliseconds.
`GET /v1/search/image`	Find products by image similarity using perceptual hashing (pHash). Requires products to be indexed in the `ImageHash` table.
`GET /v1/search/filters`	Returns available filter options with counts for building dynamic filter UIs.
`GET /v1/products`	Product search endpoint with `plainto_tsquery`/`ts_rank` full-text search. Filters: category, price range, source, brand, rating.
`GET /v1/products/trending`	Recently-updated products by category, ranked by query volume and clicks. Periods: `24h`, `7d`, `30d`.
`GET /v1/categories`	List all active product categories with item counts, sorted by popularity.
`GET /v1/categories/tree`	Hierarchical category tree with product counts. Configurable depth (1–10).
`GET /v1/categories/taxonomy`	Full unified category taxonomy with hierarchical structure and product counts.
`GET /v1/categories/{category_id}`	Retrieve a specific category by ID.
`GET /v1/categories/{category_id}/products`	Browse products within a category with pagination.

Product Detail & Comparison

Endpoint	Description
`GET /v1/products/{product_id}`	Retrieve a single product by BuyWhere ID. Includes affiliate URL, brand, category, rating, availability.
`GET /v1/products/best-price`	Find the cheapest listing for a product across all platforms using full-text search with ILIKE fallback.
`GET /v1/products/compare`	Compare a product against matching listings from other platforms using `ProductMatcher` fuzzy title matching.
`POST /v1/products/compare`	Batch compare up to N products across platforms. Returns a comparison matrix.
`POST /v1/products/compare/diff`	Direct comparison of 2–5 specific products. Returns field-level diff (price, brand, currency, availability) plus `price_rank` (1 = cheapest) and `price_spread_pct`.
`GET /v1/products/{product_id}/similar`	Find similar products based on TF-IDF title similarity, category match, and price proximity.
`GET /v1/products/{product_id}/alternatives`	Find cheaper alternatives in the same category.
`GET /v1/products/{product_id}/bundles`	Suggest complementary products for bundling.
`GET /v1/products/{product_id}/matches`	Get product matches across platforms with confidence scores. Supports cached results or forced recompute.
`GET /v1/products/{product_id}/price-history`	Get price history for a product (up to 365 days). Filterable by platform.
`GET /v1/products/{product_id}/price-stats`	Price statistics and 30-day trend using linear regression on price history.
`GET /v1/products/{product_id}/price-prediction`	Predict future price trend using linear regression on price history.
`GET /v1/products/{product_id}/price-comparison`	Return all platform listings for a product with price, shipping, total cost, seller rating, delivery estimate.
`GET /v1/products/{product_id}/reviews`	Aggregated product reviews across platforms.
`GET /v1/products/{product_id}/availability`	Stock status across all platforms. Supports forced URL refresh.
`GET /v1/products/{product_id}/stock`	Stock level for a product.
`GET /v1/products/{product_id}/click`	Track a product click and redirect to affiliate URL.
`GET /v1/products/random`	Get N random products for agent exploration and testing (1–50).
`GET /v1/products/stats`	Catalog-level statistics.
`GET /v1/products/feed`	Stream all products as NDJSON for bulk data consumers. Supports `updatedSince` filter.

Deals Engine

Endpoint	Description
`GET /v1/deals`	Find products priced below their `original_price` by at least `min_discount_pct`. Sorted by discount depth. Category filterable.

Deal scoring: The deals engine computes a deal_score combining discount depth, recency, and click velocity.

Data Export

Endpoint	Description
`GET /v1/products/export`	Export products as streaming CSV or JSON. Filters: category, source, price range. Up to 10,000 records with offset pagination.

Catalog Health & Quality

Endpoint	Description
`GET /v1/catalog/health`	Catalog health and quality report. Returns active product counts, completeness scores, freshness metrics. Cached 5 minutes.
`GET /v1/catalog/incomplete`	List products with missing title, price, or URL. Filterable by source.
`GET /v1/catalog/stats`	Aggregated catalog statistics: total products, breakdown by platform and category.

Ingestion & Scraping Pipeline

Endpoint	Description
`POST /v1/ingest/products`	Batch-ingest product data from scraping pipelines. Uses PostgreSQL upsert (`ON CONFLICT DO UPDATE`). Returns `rows_inserted`, `rows_updated`, `rows_failed`. Invalidates relevant cache keys on completion.
`GET /v1/ingest/runs`	List recent ingestion runs with pagination.
`GET /v1/ingest/runs/{run_id}`	Get a specific ingestion run by ID.
`POST /v1/ingestion`	Register a new scraping pipeline run.
`GET /v1/ingestion`	List recent ingestion runs (paginated, filterable by source and status).
`GET /v1/ingestion/{run_id}`	Get a specific ingestion run.
`PATCH /v1/ingestion/{run_id}`	Update an active run's progress (row counts).
`POST /v1/ingestion/{run_id}/complete`	Mark a run as completed/failed/cancelled. Triggers cache invalidation for all product and search caches.
`GET /v1/ingestion/stats`	Aggregate ingestion statistics: total/completed/failed/running counts and row sums.

Bulk Operations

Endpoint	Description
`POST /v1/products/batch`	Batch product lookup by IDs.
`POST /v1/products/bulk-ids`	Bulk product lookup by IDs (alternative).
`POST /v1/products/bulk-lookup`	Bulk product lookup by SKU, UPC, or product URL. Returns 207 Multi-Status.
`POST /v1/products/bulk`	Bulk import products for merchant self-serve.
`POST /v1/products/availability`	Bulk check product availability for multiple products.
`POST /v1/products/check-availability`	Check if product URLs are still accessible and update availability status.
`GET /v1/products/barcode/{code}`	Find product by UPC/EAN barcode.

Click Tracking & Analytics

Endpoint	Description
`POST /v1/products/{product_id}/click`	Track a product click. Records `Click` entity with tracking ID, platform, destination URL, user agent, referrer.
`GET /v1/track/{tracking_id}`	Track a click via pre-generated tracking ID and redirect to affiliate destination.
`GET /v1/track/{tracking_id}/verify`	Verify a tracking ID is valid without recording a click.
`GET /v1/analytics/clicks`	Click analytics: total clicks, daily/weekly time series, top products by click count. Configurable window: 1–90 days.

Webhooks

Endpoint	Description
`POST /v1/webhooks`	Register a webhook endpoint for event notifications.
`GET /v1/webhooks`	List registered webhooks for the authenticated developer.
`GET /v1/webhooks/{webhook_id}`	Get a specific webhook.
`PATCH /v1/webhooks/{webhook_id}`	Update a webhook (URL, events, secret).
`DELETE /v1/webhooks/{webhook_id}`	Delete a webhook.
`POST /v1/webhooks/{webhook_id}/test`	Send a test payload to a webhook.

Supported webhook events: product.created, product.updated, product.price_drop, product.became_unavailable, ingestion.completed, ingestion.failed.

Recommendations

Endpoint	Description
`GET /v1/products/{product_id}/similar`	Find similar products based on TF-IDF title similarity, category match, and price proximity.
`GET /v1/products/{product_id}/alternatives`	Find cheaper alternatives in the same category.
`GET /v1/products/{product_id}/bundles`	Suggest complementary products for bundling.
`GET /v1/products/recommendations`	Personalized product recommendations based on click history and preferences (requires auth).

GraphQL API

Endpoint	Description
`GET /v1/graphql`	Interactive GraphQL IDE (GraphiQL playground).
`POST /v1/graphql`	GraphQL endpoint. Supports `products`, `product`, `categories`, `taxonomy`, `deals`, `priceDrops` queries.

API Key Management

Endpoint	Description
`POST /v1/keys`	Create a new API key (provisioned with same tier as calling key).
`GET /v1/keys`	List all active API keys for the authenticated developer.
`DELETE /v1/keys/{key_id}`	Revoke (soft-delete) an API key.

Saved Searches & Watchlists

Endpoint	Description
`POST /v1/saved-searches`	Save a search query for repeated use.
`GET /v1/saved-searches`	List saved searches.
`DELETE /v1/saved-searches/{id}`	Delete a saved search.
`POST /v1/watchlist`	Add a product to the authenticated user's watchlist.
`GET /v1/watchlist`	Get the user's watchlist.
`DELETE /v1/watchlist/{product_id}`	Remove a product from watchlist.

Price Alerts

Endpoint	Description
`POST /v1/alerts`	Create a price alert for a product.
`GET /v1/alerts`	List user's price alerts.
`DELETE /v1/alerts/{alert_id}`	Delete a price alert.

Admin & Operations

Endpoint	Description
`GET /v1/admin/stats`	Admin dashboard: total products, products by platform/category, total/active keys, click stats, data freshness. Cached 5 minutes.
`GET /v1/admin/logs`	Query recent API request logs by path, API key, or HTTP status. Paginated.
`GET /v1/admin/usage`	API usage breakdown by key, endpoint, and time window.

System Health

Endpoint	Description
`GET /v1/status`	Catalog status: total unique products, per-platform counts and last-ingestion timestamps, progress toward 1M product goal.
`GET /v1/status/scrapers`	Scrapers health report per platform.
`GET /v1/status/health`	System health: database latency, connection pool stats, scraper health.

Agent & Merchant Tools

Endpoint	Description
`POST /v1/agents/forward`	Forward a user query to the BuyWhere agent system for natural language product discovery.
`GET /v1/merchants/analytics`	Merchant analytics: product performance, click-through rates, revenue estimates.
`POST /v1/merchants/products`	Merchant self-serve product submission.

Internationalization

Endpoint	Description
`GET /v1/search` (`lang` param)	Query language translation: `ms` (Malay), `th` (Thai), `vi` (Vietnamese), `id` (Indonesian). Translated to English for matching.

Currency Conversion

Feature	Description
`currency` param	All search and product endpoints accept a `currency` param (SGD, USD, MYR, IDR, THB, PHP, VND) for on-the-fly price conversion.

Changed

Change	Details
Search ranking	Improved from `plainto_tsquery` to `websearch_to_tsquery` with `ts_rank_cd` BM25 ranking.
Compare diff response	Now includes `price_rank` (1 = cheapest) and `price_spread_pct` (percentage spread between cheapest and most expensive).
Ingestion runs	Now support `started_at`/`finished_at` timestamps and `error_message` field for better observability.
Rate limiting	All search and product endpoints are rate-limited per API key tier using a token bucket algorithm.
Caching	All list/detail endpoints use Redis caching with TTLs (120s–600s depending on volatility). Ingestion completions trigger targeted cache invalidation via `cache_delete_pattern`.

Deprecated

None in v1.0.0.

Migration from v0 (pre-release)

This is the first public release. There is no migration required from a previous public version.

For integrators who used pre-release endpoints:

All endpoints were available under /v0/* in pre-release. The /v0 prefix is no longer served.
The product_id field type changed from string to integer for all product detail endpoints.
The source filter in search was renamed to platform in GET /v1/search.

Pre-v1 — Internal development releases

These releases were used during the initial build phase and were not publicly advertised.

0.1.0 — Internal alpha

Basic product search with plainto_tsquery ranking
Product detail endpoint
Category listing
Ingestion endpoint (prototype)

0.2.0 — Internal beta

Full-text search with BM25 ranking (ts_rank_cd)
Product comparison endpoints
Click tracking
Redis caching layer
API key authentication

0.3.0 — Pre-release

Deals engine with deal_score computation
GraphQL API (playground + endpoint)
Webhook system
Recommendation endpoints (similar, alternatives, bundles)
Price history and prediction
Semantic search (embedding-based fallback)
Image search (pHash)
Currency conversion
Internationalized search (lang param)
Bulk operations (batch, bulk-lookup, availability)
Watchlist and saved searches
Price alerts
Agent forwarding endpoint