SYSTEM INITIALIZATION

api_quickstart.sh

$ # Quick Start Guide

$ curl -X POST /api/v1/products/search \

-H "Authorization: Bearer YOUR_API_KEY" \

-H "Content-Type: application/json" \

-d '{"buyerAgentId": "test-agent", "query": "summer shirts"}'

# Response: 200 OK - 6x more visible products found

Available Protocols

▶ REST API - Traditional HTTP endpoints
▶ A2A Protocol - Agent-to-Agent communication
▶ WebSocket - Real-time product updates (coming soon)

AUTHENTICATION PROTOCOLS

[AUTH_METHODS]

The API supports two authentication methods:

Bearer Token

HTTP

                        Authorization: Bearer YOUR_API_KEY
                    

API Key Header

HTTP

                        X-API-Key: YOUR_API_KEY
                    

To obtain an API key, Contact Us

API ENDPOINTS

endpoints.json

POST /products/search

AI-powered product search with natural language understanding

Request Body

Parameter	Type	Required	Description
`buyerAgentId`	string	Required	Unique identifier for the buyer agent
`query`	string	Optional	Natural language search query
`buyerAgentName`	string	Optional	Display name for the buyer agent
`filters`	object	Optional	Structured filters (category, price range, tags)
`context`	object	Optional	Additional buyer context and preferences

Response Schema

JSON

                        {
  "products": [
    {
      "id": "prod_123",
      "title": "Premium Summer Cotton Shirt - Breathable & Lightweight",
      "description": "Experience ultimate comfort with our premium cotton shirt...",
      "price": 49.99,
      "currency": "USD",
      "image": "{CDN_PATH}/products/shirt-123.jpg",
      "url": "{STORE_PATH}/products/summer-cotton-shirt",
      "merchant": {
        "name": "Fashion Store",
        "id": "merchant_456",
        "verified": true
      },
      "relevanceScore": 0.95,
      "tags": [
        "summer", 
        "cotton", 
        "breathable",
        "lightweight",
        "casual-wear"
      ],
      "variants": [
        {
          "id": "var_001",
          "size": "M",
          "color": "Ocean Blue",
          "inventory": 15
        }
      ]
    }
  ],
  "metadata": {
    "totalResults": 42,
    "aiMessage": "Found 42 products matching your summer shirt criteria",
    "searchId": "search_789",
    "processingTime": 127,
    "confidence": 0.92
  }
}
                    

AGENT-TO-AGENT PROTOCOL

[A2A_CAPABILITIES]

myAI BDC implements the A2A v1.0 protocol for seamless agent communication

Supported Methods

▶ product.search - Natural language product discovery
▶ notification.subscribe - Subscribe to product updates
▶ merchant.info - Get merchant capabilities

A2A Request Format

JSON-RPC

                        {
  "jsonrpc": "2.0",
  "method": "product.search",
  "params": {
    "query": "summer beach shirts under $50",
    "buyerAgentId": "agent_123",
    "context": {
      "location": "California",
      "preferences": {
        "style": "casual"
      }
    }
  },
  "id": 1
}
                    

CODE EXAMPLES

JavaScript

Python

cURL

JavaScript

                            // Initialize API client
const API_ENDPOINT = '{YOUR_API_ENDPOINT}/api/v1';
const API_KEY = 'YOUR_API_KEY';

// Search for products
const searchProducts = async (query, options = {}) => {
  try {
    const response = await fetch(`${API_ENDPOINT}/products/search`, {
      method: 'POST',
      headers: {
        'Authorization': `Bearer ${API_KEY}`,
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        buyerAgentId: 'my-agent-123',
        query: query,
        ...options
      })
    });

    if (!response.ok) {
      throw new Error(`API Error: ${response.status}`);
    }

    return await response.json();
  } catch (error) {
    console.error('Search failed:', error);
    throw error;
  }
};

// Example usage with filters
searchProducts('summer shirts', {
  filters: {
    maxPrice: 100,
    category: 'apparel',
    tags: ['cotton', 'breathable']
  }
}).then(results => {
  console.log(`Found ${results.products.length} products`);
  results.products.forEach(product => {
    console.log(`- ${product.title}: ${product.price}`);
  });
});
                        

Python

                            import requests
import json
from typing import Optional, Dict, Any

# Configuration
API_ENDPOINT = '{YOUR_API_ENDPOINT}/api/v1'
API_KEY = 'YOUR_API_KEY'

class ProductSearchClient:
    def __init__(self, api_key: str):
        self.api_key = api_key
        self.headers = {
            'Authorization': f'Bearer {api_key}',
            'Content-Type': 'application/json'
        }
    
    def search_products(self, query: str, 
                         filters: Optional[Dict[str, Any]] = None) -> Dict[str, Any]:
        """Search for products using natural language query"""
        
        payload = {
            'buyerAgentId': 'my-agent-123',
            'query': query
        }
        
        if filters:
            payload['filters'] = filters
        
        try:
            response = requests.post(
                f'{API_ENDPOINT}/products/search',
                headers=self.headers,
                json=payload,
                timeout=30
            )
            response.raise_for_status()
            return response.json()
            
        except requests.exceptions.RequestException as e:
            print(f'API request failed: {e}')
            raise

# Example usage
if __name__ == '__main__':
    client = ProductSearchClient(API_KEY)
    
    # Search with filters
    results = client.search_products(
        query='comfortable summer shirts',
        filters={
            'maxPrice': 100,
            'category': 'apparel',
            'tags': ['cotton', 'breathable']
        }
    )
    
    # Display results
    print(f"Found {len(results['products'])} products:")
    for product in results['products']:
        print(f"- {product['title']}: ${product['price']}")
                        

Bash

                            #!/bin/bash

# Set your API credentials
API_ENDPOINT="{YOUR_API_ENDPOINT}/api/v1"
API_KEY="YOUR_API_KEY"

# Basic product search
curl -X POST "${API_ENDPOINT}/products/search" \
  -H "Authorization: Bearer ${API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "buyerAgentId": "my-agent-123",
    "query": "comfortable summer shirts"
  }'

# Search with filters and pretty output
curl -X POST "${API_ENDPOINT}/products/search" \
  -H "Authorization: Bearer ${API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "buyerAgentId": "my-agent-123",
    "query": "beach vacation shirts",
    "filters": {
      "maxPrice": 75,
      "category": "apparel",
      "tags": ["summer", "cotton", "breathable"]
    },
    "context": {
      "location": "California",
      "preferences": {
        "style": "casual",
        "fit": "relaxed"
      }
    }
  }' | json_pp

# Using jq for selective output
curl -s -X POST "${API_ENDPOINT}/products/search" \
  -H "Authorization: Bearer ${API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{"buyerAgentId": "my-agent-123", "query": "shirts"}' \
  | jq '.products[] | {title, price, relevanceScore}'
                        