{
  "openapi": "3.1.0",
  "info": {
    "title": "Peaksea Market - Autonomous Agentic Commerce API",
    "version": "1.0.0",
    "description": "Machine-to-machine commerce API for autonomous procurement agents, Grok bots, and AI buyers. Allows instant catalog exploration, multi-parameter quotation (PI generation), and programmatic sample checkout.",
    "contact": {
      "name": "Peaksea Technology Co., Ltd. - Overseas Trade Engineering",
      "email": "export@peaksea.tech",
      "url": "https://market.peaksea.tech"
    }
  },
  "servers": [
    {
      "url": "https://market.peaksea.tech",
      "description": "Production Server"
    }
  ],
  "paths": {
    "/api/agent/catalog": {
      "get": {
        "summary": "Explore precision hardware & enclosure product catalog",
        "description": "Retrieve machine-readable list of standard and customizable CNC enclosures, sheet metal chassis, and IoT hardware with material specs, tolerances, and tier pricing.",
        "operationId": "getCatalog",
        "parameters": [
          {
            "name": "category",
            "in": "query",
            "required": false,
            "schema": { "type": "string" },
            "description": "Filter by category: 'sensor-enclosures', 'iot-hardware', 'cnc-precision-parts', 'sheet-metal'"
          },
          {
            "name": "search",
            "in": "query",
            "required": false,
            "schema": { "type": "string" },
            "description": "Keyword search in product names, materials, and descriptions"
          },
          {
            "name": "format",
            "in": "query",
            "required": false,
            "schema": { "type": "string", "enum": ["json", "markdown"], "default": "json" },
            "description": "Return format. 'markdown' is optimized for LLM reading; 'json' is standard structured data."
          }
        ],
        "responses": {
          "200": {
            "description": "Product catalog list with specifications and pricing tiers."
          }
        }
      }
    },
    "/api/agent/quote": {
      "post": {
        "summary": "Request automated RFQ & instant Proforma Invoice (PI)",
        "description": "Submits engineering parameters (quantity, material, finish, destination country) and returns an instant formal Proforma Invoice with unit price breakdown, tooling fees, shipping estimate, and banking SWIFT instructions.",
        "operationId": "requestQuotation",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["destinationCountry", "customerEmail"],
                "properties": {
                  "productId": { "type": "string", "example": "prod-al-enclosure-ip68" },
                  "quantity": { "type": "integer", "minimum": 1, "default": 100 },
                  "material": { "type": "string", "example": "Aluminum 6061-T6" },
                  "finish": { "type": "string", "example": "Anodized Black" },
                  "destinationCountry": { "type": "string", "example": "US", "description": "2-letter ISO country code" },
                  "incoterms": { "type": "string", "enum": ["EXW", "FOB", "CIF", "DDP"], "default": "FOB" },
                  "customerName": { "type": "string", "example": "AI Purchasing Agent" },
                  "companyName": { "type": "string", "example": "Global Robotics Inc" },
                  "customerEmail": { "type": "string", "format": "email", "example": "procurement@globalrobotics.com" },
                  "customNotes": { "type": "string", "example": "Require customized cable gland holes on the front panel." }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Quotation generated successfully with complete Proforma Invoice (PI)."
          }
        }
      }
    },
    "/api/agent/orders/sample": {
      "post": {
        "summary": "Place autonomous prototype/sample order",
        "description": "Allows an AI agent to programmatically purchase prototypes/samples (1-5 units per item) with automated shipping calculation, checkout URL generation, and settlement token creation.",
        "operationId": "createSampleOrder",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["items", "shippingAddress"],
                "properties": {
                  "items": {
                    "type": "array",
                    "items": {
                      "type": "object",
                      "required": ["productId"],
                      "properties": {
                        "productId": { "type": "string", "example": "prod-al-enclosure-ip68" },
                        "quantity": { "type": "integer", "minimum": 1, "maximum": 5, "default": 1 }
                      }
                    }
                  },
                  "shippingAddress": {
                    "type": "object",
                    "required": ["recipientName", "streetAddress", "city", "country", "email"],
                    "properties": {
                      "recipientName": { "type": "string", "example": "Engineering Sample Team" },
                      "companyName": { "type": "string", "example": "Smart IoT Labs" },
                      "streetAddress": { "type": "string", "example": "450 Technology Parkway" },
                      "city": { "type": "string", "example": "Sunnyvale" },
                      "stateOrProvince": { "type": "string", "example": "CA" },
                      "postalCode": { "type": "string", "example": "94086" },
                      "country": { "type": "string", "example": "US" },
                      "phone": { "type": "string", "example": "+1-408-555-1212" },
                      "email": { "type": "string", "format": "email", "example": "sample-receiver@smartiot.com" }
                    }
                  },
                  "paymentMethod": { "type": "string", "enum": ["stripe", "crypto", "invoice"], "default": "stripe" },
                  "agentId": { "type": "string", "example": "grok-agent-buyer-01" }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Sample order created with payment token and checkout link."
          }
        }
      }
    },
    "/api/agent/orders/{id}": {
      "get": {
        "summary": "Query sample order status and fulfillment tracking",
        "description": "Returns the current state of a sample order, payment confirmation, and courier tracking details.",
        "operationId": "getOrderStatus",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": { "type": "string" },
            "description": "The orderId returned when creating the sample order (e.g. ORD-SMP-XXXXX)"
          }
        ],
        "responses": {
          "200": {
            "description": "Order status and fulfillment details."
          },
          "404": {
            "description": "Order not found."
          }
        }
      }
    }
  }
}