Quickstart: First Query in Under 5 Minutes

This guide is the fastest path from zero to a working BuyWhere request against the live API at https://api.buywhere.ai.

It is written against the live deployment behavior verified on April 4, 2026:

• GET /health responds publicly
• product search is available at GET /v1/products
• authenticated requests currently expect the X-API-Key header

Prerequisites

• A BuyWhere API key
• curl
• Python 3.10+ if you want to run the Python examples

Optional:

• pip install buywhere
• pip install requests
• pip install langchain-core
• pip install crewai

Set your API key once:

export BUYWHERE_API_KEY="your_api_key_here"
export BUYWHERE_BASE_URL="https://api.buywhere.ai"

1. Sanity Check The API

Confirm the live API is reachable before you spend time debugging auth or code:

curl -sS "$BUYWHERE_BASE_URL/health"

Expected shape:

{
  "status": "ok"
}

2. Make Your First Product Query

Use GET /v1/products for the quickest working search flow.

curl -sS --get "$BUYWHERE_BASE_URL/v1/products" \
  -H "X-API-Key: $BUYWHERE_API_KEY" \
  --data-urlencode "q=wireless headphones" \
  --data-urlencode "limit=3"

Expected response shape:

{
  "total": 248,
  "limit": 3,
  "offset": 0,
  "items": [
    {
      "id": 78234,
      "sku": "SHOPEE-SG-HEP-001",
      "source": "shopee_sg",
      "merchant_id": "shop_abc123",
      "name": "Sony WH-1000XM5 Wireless Headphones",
      "price": "449.00",
      "currency": "SGD",
      "buy_url": "https://shopee.sg/product/12345",
      "affiliate_url": "https://api.buywhere.ai/v1/track/abc123",
      "category": "Electronics",
      "category_path": ["Electronics", "Audio", "Headphones"],
      "is_available": true,
      "updated_at": "2026-04-03T14:30:00Z"
    }
  ],
  "has_more": true
}

3. Parse The Response

The fields most developers need first are:

• items[].name
• items[].price
• items[].currency
• items[].source
• items[].affiliate_url
• items[].buy_url

Quick jq example:

curl -sS --get "$BUYWHERE_BASE_URL/v1/products" \
  -H "X-API-Key: $BUYWHERE_API_KEY" \
  --data-urlencode "q=nintendo switch oled" \
  --data-urlencode "limit=5" \
| jq '.items[] | {name, price, currency, source, affiliate_url, buy_url}'

Python example:

import os
import requests

base_url = os.environ["BUYWHERE_BASE_URL"]
api_key = os.environ["BUYWHERE_API_KEY"]

response = requests.get(
    f"{base_url}/v1/products",
    headers={"X-API-Key": api_key},
    params={"q": "nintendo switch oled", "limit": 5},
    timeout=30,
)
response.raise_for_status()

data = response.json()

for item in data.get("items", []):
    buy_link = item.get("affiliate_url") or item.get("buy_url")
    print(item["name"])
    print(f"  Price: {item['currency']} {item['price']}")
    print(f"  Source: {item['source']}")
    print(f"  Buy: {buy_link}")

4. Add Filters

The live product search route supports the filters most agent builders need:

• q
• category
• min_price
• max_price
• source
• limit
• offset

Examples:

curl -sS --get "$BUYWHERE_BASE_URL/v1/products" \
  -H "X-API-Key: $BUYWHERE_API_KEY" \
  --data-urlencode "q=laptop" \
  --data-urlencode "category=Electronics" \
  --data-urlencode "min_price=800" \
  --data-urlencode "max_price=2500" \
  --data-urlencode "source=shopee_sg" \
  --data-urlencode "limit=10"

Useful source values already used in the codebase include:

• shopee_sg
• lazada_sg
• carousell
• amazon_sg

5. Raw HTTP Integration

If you are wiring BuyWhere into an agent stack today, raw HTTP is the safest production path.

import os
import requests


def search_products(query: str, *, category: str | None = None) -> dict:
    params = {"q": query, "limit": 5}
    if category:
        params["category"] = category

    response = requests.get(
        f"{os.environ['BUYWHERE_BASE_URL']}/v1/products",
        headers={"X-API-Key": os.environ["BUYWHERE_API_KEY"]},
        params=params,
        timeout=30,
    )
    response.raise_for_status()
    return response.json()

6. LangChain Tool Example

import os
import requests
from langchain_core.tools import tool


@tool
def buywhere_search(query: str) -> str:
    """Search BuyWhere products and return the top results."""
    response = requests.get(
        f"{os.environ['BUYWHERE_BASE_URL']}/v1/products",
        headers={"X-API-Key": os.environ["BUYWHERE_API_KEY"]},
        params={"q": query, "limit": 5},
        timeout=30,
    )
    response.raise_for_status()
    items = response.json().get("items", [])

    if not items:
        return f"No results for {query!r}."

    lines = []
    for item in items:
        link = item.get("affiliate_url") or item.get("buy_url")
        lines.append(
            f"{item['name']} | {item['currency']} {item['price']} | "
            f"{item['source']} | {link}"
        )
    return "\n".join(lines)

7. CrewAI Tool Example

import os
import requests
from crewai.tools import tool


@tool("buywhere_best_price")
def buywhere_best_price(product_name: str) -> str:
    """Find the cheapest BuyWhere listing for a product query."""
    response = requests.get(
        f"{os.environ['BUYWHERE_BASE_URL']}/v1/products/best-price",
        headers={"X-API-Key": os.environ["BUYWHERE_API_KEY"]},
        params={"q": product_name},
        timeout=30,
    )
    response.raise_for_status()
    item = response.json()
    link = item.get("affiliate_url") or item.get("buy_url")
    return (
        f"{item['name']} | {item['currency']} {item['price']} | "
        f"{item['source']} | {link}"
    )

8. SDK Note

The repo currently contains Python SDK code in both:

• buywhere at /home/paperclip/buywhere-py
• buywhere_sdk at /home/paperclip/buywhere-api/sdk

Those SDK examples still show Authorization: Bearer ..., while the live API currently responds with X-API-Key header required when auth is missing. For that reason, the examples above use raw HTTP so a new developer can get to a real first query without hitting avoidable auth drift.