{
  "schema_version": "1.0.0",
  "name": "A2R Marketplace",
  "description": "Agent-to-Retail commerce platform. AI agents can discover products, compare prices, and complete purchases via the UCP protocol.",
  "protocol": "ucp/2026-01-11",
  "capabilities": {
    "read": [
      {
        "name": "discovery",
        "description": "Browse and search the product catalog",
        "endpoint": "/api/products",
        "method": "GET",
        "auth": "none",
        "params": {
          "query": "Search text (optional)",
          "category": "Filter by category (optional)",
          "limit": "Max results, default 20 (optional)"
        }
      },
      {
        "name": "search_by_embedding",
        "description": "Search products using embedding vectors for semantic matching",
        "endpoint": "/api/search/tokens",
        "method": "POST",
        "auth": "none",
        "body": {
          "tokens": "Array of floats (384-1536 dim embedding vector)",
          "limit": "Max results (optional)",
          "category": "Filter by category (optional)",
          "min_price": "Minimum price in cents (optional)",
          "max_price": "Maximum price in cents (optional)"
        }
      },
      {
        "name": "categories",
        "description": "List all product categories",
        "endpoint": "/api/categories",
        "method": "GET",
        "auth": "none"
      },
      {
        "name": "product_detail",
        "description": "Get full details for a single product",
        "endpoint": "/api/products/{product_id}",
        "method": "GET",
        "auth": "none"
      },
    ],
    "write": [
      {
        "name": "cart_add",
        "description": "Add a product to the shopping cart",
        "endpoint": "/api/cart/add",
        "method": "POST",
        "auth": "api_key",
        "min_permission": "read_cart",
        "auto_escalation": "Agents with read_only are automatically upgraded to read_cart on first cart action",
        "body": {
          "product_id": "Product ID to add",
          "quantity": "Number of items (default 1)",
          "session_id": "Cart session ID (optional, auto-generated)"
        }
      },
      {
        "name": "cart_view",
        "description": "View current cart contents",
        "endpoint": "/api/cart/{session_id}",
        "method": "GET",
        "auth": "api_key",
        "min_permission": "read_cart"
      },
      {
        "name": "checkout",
        "description": "Complete a purchase and process payment",
        "endpoint": "/api/checkout/complete",
        "method": "POST",
        "auth": "api_key",
        "min_permission": "read_cart_checkout",
        "auto_escalation": "Agents with read_cart are automatically upgraded to read_cart_checkout on first checkout",
        "body": {
          "session_id": "Cart session ID",
          "buyer_email": "Buyer email address",
          "buyer_name": "Buyer name",
          "payment_method": "mock_pay | card_visa | card_mastercard"
        }
      }
    ]
  },
  "ucp_message_endpoint": {
    "description": "Unified A2A protocol endpoint. Send AgentMessage objects for any UCP capability.",
    "endpoint": "/api/ucp/message",
    "method": "POST",
    "auth": "api_key (required for write capabilities)"
  },
  "authentication": {
    "type": "api_key",
    "registration_endpoint": "/api/agents/register",
    "header": "X-Agent-Key",
    "auto_escalation": "Permissions automatically upgrade based on agent intent (read_only -> read_cart -> read_cart_checkout)",
    "permissions": [
      {
        "level": "read_only",
        "description": "Browse products, search, view reviews and inventory",
        "granted_on": "Registration"
      },
      {
        "level": "read_cart",
        "description": "All read_only capabilities plus cart operations",
        "granted_on": "First add-to-cart action"
      },
      {
        "level": "read_cart_checkout",
        "description": "Full access including checkout and payment",
        "granted_on": "First checkout action"
      }
    ]
  },
  "rate_limits": {
    "read": {
      "requests_per_minute": 60,
      "requests_per_hour": 1000
    },
    "write": {
      "requests_per_minute": 20,
      "requests_per_hour": 200
    }
  }
}