Agent Native Search

AI-optimized natural language product search with confidence scoring, availability predictions, and competitor analysis.

Base URL: https://api.buywhere.ai/v2/agents/search

Overview

The Agent Native Search endpoint is specifically designed for AI agent workflows. It returns enhanced product data including confidence scores, availability predictions, competitor counts, buybox pricing, and optional agent insights. This enables AI agents to make informed decisions about which products to recommend.

HTTP Method

GET /v2/agents/search

Authentication

Requires API key in the Authorization header:

Authorization: Bearer bw_live_xxxxxxxxxxxxxxxx

Query Parameters

Session Context Header

Pass session context via the X-Session-Context header (base64-encoded JSON):

{
  "budget": {"min": 100, "max": 1000},
  "target_currency": "SGD",
  "preferences": {
    "preferred_sources": ["shopee_sg", "lazada_sg"],
    "excluded_sources": ["carousell_sg"]
  }
}

Request Example

cURL

curl -X GET "https://api.buywhere.ai/v2/agents/search?q=best+gaming+laptop+under+2000&limit=10&include_agent_insights=true" \
  -H "Authorization: Bearer bw_live_xxxxxxxxxxxxxxxx"

Python

import httpx
import base64
import json

API_KEY = "bw_live_xxxxxxxxxxxxxxxx"
BASE_URL = "https://api.buywhere.ai"

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

response = httpx.get(
    f"{BASE_URL}/v2/agents/search",
    params={
        "q": "best gaming laptop under 2000",
        "limit": 10,
        "include_agent_insights": True,
        "include_availability_prediction": True,
        "include_competitor_count": True
    },
    headers=headers
)
data = response.json()
print(f"Found {data['total']} results")
for item in data['results']:
    print(f"  {item['title']}")
    print(f"    Price: {item['currency']} {item['price']}")
    print(f"    Confidence: {item['confidence_score']}")
    print(f"    Availability: {item['availability_prediction']}")
    print(f"    Competitors: {item['competitor_count']}")
    print(f"    Buybox: {item.get('buybox_price', 'N/A')}")

JavaScript (Node.js)

const API_KEY = "bw_live_xxxxxxxxxxxxxxxx";
const BASE_URL = "https://api.buywhere.ai";

const response = await fetch(
  `${BASE_URL}/v2/agents/search?q=${encodeURIComponent("best gaming laptop under 2000")}&limit=10&include_agent_insights=true`,
  {
    headers: { "Authorization": `Bearer ${API_KEY}` }
  }
);

const data = await response.json();
console.log(`Found ${data.total} results`);
data.results.forEach(item => {
  console.log(`  ${item.title}`);
  console.log(`    Price: ${item.currency} ${item.price}`);
  console.log(`    Confidence: ${item.confidence_score}`);
  console.log(`    Availability: ${item.availability_prediction}`);
  console.log(`    Competitors: ${item.competitor_count}`);
  console.log(`    Buybox: ${item.buybox_price || 'N/A'}`);
});

Go

package main

import (
    "encoding/json"
    "fmt"
    "net/http"
    "net/url"
)

func agentSearch(apiKey, query string) error {
    baseURL, _ := url.Parse("https://api.buywhere.ai/v2/agents/search")
    params := url.Values{}
    params.Set("q", query)
    params.Set("limit", "10")
    params.Set("include_agent_insights", "true")
    params.Set("include_availability_prediction", "true")
    params.Set("include_competitor_count", "true")
    baseURL.RawQuery = params.Encode()

    req, _ := http.NewRequest("GET", baseURL.String(), nil)
    req.Header.Set("Authorization", "Bearer "+apiKey)

    client := &http.Client{}
    resp, err := client.Do(req)
    if err != nil {
        return err
    }
    defer resp.Body.Close()

    var result map[string]interface{}
    json.NewDecoder(resp.Body).Decode(&result)

    total := int(result["total"].(float64))
    fmt.Printf("Found %d results\n", total)

    results := result["results"].([]interface{})
    for _, r := range results {
        m := r.(map[string]interface{})
        fmt.Printf("  %s\n", m["title"])
        fmt.Printf("    Price: %s %s\n", m["currency"], m["price"])
        fmt.Printf("    Confidence: %.2f\n", m["confidence_score"].(float64))
    }
    return nil
}

Response

Success Response (200 OK)

{
  "query": "best gaming laptop under 2000",
  "total": 156,
  "limit": 10,
  "offset": 0,
  "has_more": true,
  "results": [
    {
      "id": 18472931,
      "sku": "ASUS-ROG-STRIX-G16",
      "source": "shopee_sg",
      "title": "ASUS ROG Strix G16 Gaming Laptop",
      "price": "1899.00",
      "currency": "SGD",
      "price_sgd": "1899.00",
      "url": "https://shopee.sg/product/18472931",
      "brand": "ASUS",
      "category": "Computers & Laptops",
      "image_url": "https://cf.shopee.sg/file/xxxxx.jpg",
      "rating": 4.8,
      "review_count": 892,
      "is_available": true,
      "in_stock": true,
      "stock_level": "in_stock",
      "confidence_score": 0.92,
      "availability_prediction": "in_stock",
      "competitor_count": 15,
      "buybox_price": "1849.00",
      "buybox_confidence": 0.87,
      "affiliate_url": "https://buywhere.ai/track/abc123",
      "data_freshness": "2026-04-15T10:00:00Z",
      "price_trend": "down",
      "price_change_percentage": -3.2,
      "demand_score": 0.78,
      "seasonal_factor": 1.1,
      "agent_insights": {
        "buybox_winner": true,
        "value_score": 0.85,
        "recommendation_reason": "Best price-to-specs ratio in category"
      }
    }
  ]
}

Response Fields

Agent-Enhanced Product Fields

Confidence Score Interpretation

Availability Prediction

Error Responses

401 Unauthorized

{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Invalid or missing API key"
  }
}

422 Validation Error

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Request validation failed",
    "details": {
      "errors": [
        {
          "field": "q",
          "message": "q cannot be empty",
          "type": "missing"
        }
      ]
    }
  }
}

---

Performance Characteristics

The Agent Native Search endpoint is optimized for AI agent workflows but carries additional overhead from AI-enhanced features. Performance varies based on requested options and load conditions:

Performance tips:

• Enable only needed options: Each include_* parameter adds latency
• Cache predictions: Availability predictions change slowly; cache for 5+ minutes
• Use session context: Reduces per-request overhead when processing multiple queries

Note: Agent Native Search is designed for accuracy over speed. For simple product lookups, use the standard V2 Search endpoint.

---

Related Endpoints

• Agent Native Price Comparison - Compare prices across platforms
• Agent Native Best Price - Find lowest price
• Agent Native Batch Lookup - Batch product lookup
• V2 Search - Standard V2 search