myAI BDC DEVELOPER PORTAL

AI-powered product search, Agent-to-Agent protocol, and Parlay negotiation system

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


$ # NEW: Parlay Negotiation

$ curl -X POST /api/v1/parlay/initiate \

-H "Authorization: Bearer YOUR_API_KEY" \

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

-d '{"productId": "prod_123", "initialOffer": 45.00}'

Available Protocols

  • ▶ REST API - Traditional HTTP endpoints
  • ▶ A2A Protocol - Agent-to-Agent communication
  • ▶ Parlay Negotiation - AI-powered price negotiation NEW
  • ▶ WebSocket - Real-time updates (coming soon)

AUTHENTICATION PROTOCOLS

[AUTH_METHODS]

The API supports two authentication methods:

Bearer Token

HTTP
1
Authorization: Bearer YOUR_API_KEY

API Key Header

HTTP
1
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
enableParlay boolean Optional Enable Parlay negotiation for results

GET /products/{productId}

Retrieve detailed product information

PUT /products/{productId}/view

Register product view for analytics

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"
      ],
      "parlayEnabled": true,
      "minParlayPrice": 42.49,
      "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,
    "parlayAvailable": 28
  }
}

PARLAY NEGOTIATION SYSTEM

Intelligent Price Negotiation

The Parlay system enables AI-powered price negotiations between buyer agents and merchants, creating win-win scenarios through intelligent bargaining.

parlay_endpoints.json

POST /parlay/initiate

Start a new price negotiation session

Request Body

Parameter Type Required Description
productId string Required ID of the product to negotiate
buyerAgentId string Required Buyer agent identifier
initialOffer number Required Initial price offer
context object Optional Negotiation context (bulk order, repeat customer, etc.)

POST /parlay/{sessionId}/counter

Submit a counter-offer in an active negotiation

GET /parlay/{sessionId}/status

Check negotiation status and history

POST /parlay/{sessionId}/accept

Accept the current offer and finalize the deal

Parlay Response Example

JSON
{
  "sessionId": "parlay_session_xyz",
  "status": "negotiating",
  "currentOffer": {
    "price": 47.50,
    "offerBy": "merchant",
    "timestamp": "2024-01-15T14:30:00Z"
  },
  "negotiationHistory": [
    {
      "price": 45.00,
      "by": "buyer",
      "timestamp": "2024-01-15T14:28:00Z"
    },
    {
      "price": 47.50,
      "by": "merchant",
      "timestamp": "2024-01-15T14:30:00Z",
      "reasoning": "15% discount for bulk order of 10+ units"
    }
  ],
  "merchantLimits": {
    "minPrice": 42.49,
    "maxDiscount": 0.15
  },
  "aiAdvice": "Merchant seems willing to negotiate. Consider accepting or counter with $46.50",
  "expiresAt": "2024-01-15T14:35:00Z"
}

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
  • ▶ parlay.negotiate - Automated price negotiations NEW
  • ▶ notification.subscribe - Subscribe to product updates
  • ▶ merchant.info - Get merchant capabilities

A2A Request Format

JSON-RPC
{
  "jsonrpc": "2.0",
  "method": "parlay.negotiate",
  "params": {
    "productId": "prod_123",
    "buyerAgentId": "agent_123",
    "targetPrice": 45.00,
    "strategy": "aggressive",
    "context": {
      "orderQuantity": 10,
      "customerType": "repeat"
    }
  },
  "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 with Parlay enabled
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,
        enableParlay: true,
        ...options
      })
    });

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

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

// Initiate Parlay negotiation
const startParlay = async (productId, initialOffer) => {
  const response = await fetch(`${API_ENDPOINT}/parlay/initiate`, {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${API_KEY}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      productId: productId,
      buyerAgentId: 'my-agent-123',
      initialOffer: initialOffer,
      context: {
        orderQuantity: 10,
        customerType: 'new'
      }
    })
  });

  return await response.json();
};

// Example usage
searchProducts('summer shirts')
  .then(async (results) => {
    const parlayProduct = results.products.find(p => p.parlayEnabled);
    if (parlayProduct) {
      const parlay = await startParlay(parlayProduct.id, parlayProduct.price * 0.85);
      console.log('Negotiation started:', parlay.sessionId);
    }
  });
Python
import requests
import json
import asyncio
from typing import Optional, Dict, Any

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

class BDCClient:
    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, 
                         enable_parlay: bool = True,
                         filters: Optional[Dict[str, Any]] = None) -> Dict[str, Any]:
        """Search for products with optional Parlay negotiation"""
        
        payload = {
            'buyerAgentId': 'my-agent-123',
            'query': query,
            'enableParlay': enable_parlay
        }
        
        if filters:
            payload['filters'] = filters
        
        response = requests.post(
            f'{API_ENDPOINT}/products/search',
            headers=self.headers,
            json=payload
        )
        response.raise_for_status()
        return response.json()
    
    def initiate_parlay(self, product_id: str, 
                        initial_offer: float,
                        context: Optional[Dict[str, Any]] = None) -> Dict[str, Any]:
        """Start a Parlay negotiation for a product"""
        
        payload = {
            'productId': product_id,
            'buyerAgentId': 'my-agent-123',
            'initialOffer': initial_offer
        }
        
        if context:
            payload['context'] = context
        
        response = requests.post(
            f'{API_ENDPOINT}/parlay/initiate',
            headers=self.headers,
            json=payload
        )
        response.raise_for_status()
        return response.json()
    
    def counter_offer(self, session_id: str, 
                       new_offer: float) -> Dict[str, Any]:
        """Submit a counter offer in an active Parlay session"""
        
        response = requests.post(
            f'{API_ENDPOINT}/parlay/{session_id}/counter',
            headers=self.headers,
            json={'offer': new_offer}
        )
        response.raise_for_status()
        return response.json()

# Example: Automated negotiation bot
async def negotiate_best_price(client: BDCClient, product_id: str, 
                               target_price: float, max_rounds: int = 5):
    """Automatically negotiate to reach target price"""
    
    # Start negotiation at 80% of listing price
    initial_offer = target_price * 0.8
    
    parlay = client.initiate_parlay(
        product_id=product_id,
        initial_offer=initial_offer,
        context={
            'orderQuantity': 10,
            'customerType': 'business'
        }
    )
    
    session_id = parlay['sessionId']
    rounds = 0
    
    while rounds < max_rounds and parlay['status'] == 'negotiating':
        current_price = parlay['currentOffer']['price']
        
        if current_price <= target_price:
            # Accept the offer
            response = requests.post(
                f'{API_ENDPOINT}/parlay/{session_id}/accept',
                headers=client.headers
            )
            print(f"Deal accepted at ${current_price}!")
            break
        
        # Counter with gradual increase
        new_offer = initial_offer + (
            (target_price - initial_offer) * (rounds + 1) / max_rounds
        )
        
        parlay = client.counter_offer(session_id, new_offer)
        rounds += 1
        
        await asyncio.sleep(2)  # Wait between rounds
    
    return parlay

# Usage example
if __name__ == '__main__':
    client = BDCClient(API_KEY)
    
    # Search for negotiable products
    results = client.search_products(
        query='premium office chairs',
        enable_parlay=True
    )
    
    parlay_products = [p for p in results['products'] if p['parlayEnabled']]
    
    print(f"Found {len(parlay_products)} negotiable products")
    
    if parlay_products:
        # Start negotiation on first product
        product = parlay_products[0]
        target = product['price'] * 0.85  # Target 15% discount
        
        asyncio.run(negotiate_best_price(
            client, product['id'], target
        ))
Bash
#!/bin/bash

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

# Search for products with Parlay enabled
curl -X POST "${API_ENDPOINT}/products/search" \
  -H "Authorization: Bearer ${API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "buyerAgentId": "my-agent-123",
    "query": "office chairs",
    "enableParlay": true
  }'

# Initiate a Parlay negotiation
PRODUCT_ID="prod_123"
INITIAL_OFFER="150.00"

PARLAY_RESPONSE=$(curl -s -X POST "${API_ENDPOINT}/parlay/initiate" \
  -H "Authorization: Bearer ${API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "productId": "'${PRODUCT_ID}'",
    "buyerAgentId": "my-agent-123",
    "initialOffer": '${INITIAL_OFFER}',
    "context": {
      "orderQuantity": 5,
      "customerType": "business"
    }
  }')

# Extract session ID using jq
SESSION_ID=$(echo "$PARLAY_RESPONSE" | jq -r '.sessionId')
echo "Negotiation started. Session ID: $SESSION_ID"

# Check negotiation status
curl -X GET "${API_ENDPOINT}/parlay/${SESSION_ID}/status" \
  -H "Authorization: Bearer ${API_KEY}" | jq '.'

# Submit counter offer
curl -X POST "${API_ENDPOINT}/parlay/${SESSION_ID}/counter" \
  -H "Authorization: Bearer ${API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "offer": 165.00
  }'

# Accept current offer
curl -X POST "${API_ENDPOINT}/parlay/${SESSION_ID}/accept" \
  -H "Authorization: Bearer ${API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{}'

# Full negotiation workflow example
negotiate_product() {
  local product_id="$1"
  local target_price="$2"
  
  # Start negotiation at 80% of target
  local initial_offer=$(echo "$target_price * 0.8" | bc)
  
  echo "Starting negotiation for product $product_id"
  echo "Target price: $target_price, Initial offer: $initial_offer"
  
  # Initiate parlay and get session ID
  local session_response=$(curl -s -X POST "${API_ENDPOINT}/parlay/initiate" \
    -H "Authorization: Bearer ${API_KEY}" \
    -H "Content-Type: application/json" \
    -d "{
      \"productId\": \"$product_id\",
      \"buyerAgentId\": \"my-agent-123\",
      \"initialOffer\": $initial_offer
    }")
  
  local session_id=$(echo "$session_response" | jq -r '.sessionId')
  
  # Negotiation loop
  for i in {1..5}; do
    sleep 2
    
    # Check current status
    local status_response=$(curl -s -X GET \
      "${API_ENDPOINT}/parlay/${session_id}/status" \
      -H "Authorization: Bearer ${API_KEY}")
    
    local current_price=$(echo "$status_response" | \
      jq -r '.currentOffer.price')
    
    echo "Round $i: Current offer is $current_price"
    
    # Accept if price is good
    if (( $(echo "$current_price <= $target_price" | bc -l) )); then
      echo "Accepting offer at $current_price!"
      curl -s -X POST "${API_ENDPOINT}/parlay/${session_id}/accept" \
        -H "Authorization: Bearer ${API_KEY}" \
        -d '{}'
      break
    fi
    
    # Counter offer
    local new_offer=$(echo "$initial_offer + ($target_price - $initial_offer) * $i / 5" | bc)
    echo "Countering with $new_offer"
    
    curl -s -X POST "${API_ENDPOINT}/parlay/${session_id}/counter" \
      -H "Authorization: Bearer ${API_KEY}" \
      -H "Content-Type: application/json" \
      -d "{\"offer\": $new_offer}"
  done
}

# Example usage
negotiate_product "prod_456" "175.00"