BuyWhere Agent Integration Guide

Quick reference for integrating the BuyWhere agent-native product catalog API into your AI agent.

Authentication

curl -H "Authorization: Bearer bw_live_your_api_key" \
  https://api.buywhere.ai/v2/products?q=laptop&limit=5

Core Endpoints

Search Products

GET /v2/products?q=<query>&limit=<n>&offset=<n>&source=<platform>&min_price=<p>&max_price=<p>&sort_by=<relevance|price_asc|price_desc|newest>

Batch Lookup (up to 100 IDs)

POST /v2/products/batch-details
{"product_ids": [123, 456, 789]}

Agent Exploration (randomized discovery)

GET /v2/agents/explore?limit=<n>&category=<cat>&source=<platform>&min_price=<p>&max_price=<p>

Price Comparison

GET /v2/agents/price-comparison?product_name=<name>&limit=<n>&sources=<s1,s2>&availability_only=true

Agent-Native Response Fields

Rate Limits

• Default: 1000 requests/minute
• Check X-RateLimit-Remaining header
• 429 response includes Retry-After header

Quick Example (Python)

import requests

API_KEY = "bw_live_your_key"
BASE = "https://api.buywhere.ai/v2"

headers = {"Authorization": f"Bearer {API_KEY}"}

# Search
r = requests.get(f"{BASE}/products", headers=headers, params={"q": "iphone", "limit": 5})
data = r.json()

for p in data["items"]:
    print(f"{p['name']} — SGD {p['price']} @ {p['source']}")
    print(f"  Confidence: {p['confidence_score']} | Available: {p['availability_prediction']}")
    print(f"  Competitors: {p['competitor_count']} | Buybox: SGD {p.get('buybox_price', p['price'])}")

SDK Usage

from buywhere_sdk import BuyWhere

client = BuyWhere(api_key="bw_live_your_key")

# Search
results = client.search("air fryer", limit=10)
for p in results.items:
    print(f"{p.name} — {p.currency} {p.price}")

# Best price
cheapest = client.best_price("nintendo switch")
print(f"Best: {cheapest.price} at {cheapest.source}")

# Batch lookup
batch = client.batch_lookup([123, 456, 789])
for p in batch.products:
    if p:
        print(f"{p.name}: {p.price}")

Base URLs

• Production: https://api.buywhere.ai
• Local dev: http://localhost:8000

Error Codes

Next Steps

• Full docs: docs/ai-agent-getting-started.md
• SDK reference: sdk/README.md
• Examples: examples/