{
  "openapi": "3.1.0",
  "info": {
    "title": "Agentura API",
    "description": "Specialty coffee for humans and AI agents. Pay with USDC on Base via the x402 protocol. US shipping only.",
    "version": "1.0.0",
    "contact": {
      "url": "https://agentura.coffee"
    }
  },
  "servers": [
    { "url": "https://agentura.coffee", "description": "Production" }
  ],
  "paths": {
    "/api/health": {
      "get": {
        "operationId": "getHealth",
        "summary": "Health check",
        "description": "Returns service status. Check this before placing orders.",
        "responses": {
          "200": {
            "description": "Service is operational",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/HealthResponse" }
              }
            }
          }
        }
      }
    },
    "/api/catalog": {
      "get": {
        "operationId": "getCatalog",
        "summary": "List available products",
        "description": "Returns all coffee products with IDs, prices, and payment endpoint routing. Always fetch live before ordering — do not rely on cached product data.",
        "responses": {
          "200": {
            "description": "Product catalog",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/CatalogResponse" }
              }
            }
          }
        }
      }
    },
    "/api/order/small": {
      "post": {
        "operationId": "orderSmall",
        "summary": "Order a 12oz bag — $16.00 USDC",
        "description": "Places a 12oz coffee order. Protected by x402: the first request returns 402 with USDC payment instructions. Pay the exact amount on Base, then retry the request with the X-PAYMENT header. Use Idempotency-Key to prevent duplicate orders on retry.",
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "description": "A unique key (UUID recommended) to make this request idempotent. Retrying with the same key returns the original response without creating a duplicate order.",
            "schema": { "type": "string", "example": "550e8400-e29b-41d4-a716-446655440000" }
          },
          {
            "name": "X-PAYMENT",
            "in": "header",
            "required": false,
            "description": "x402 payment proof header. Provided automatically by x402-compatible clients after paying the 402 invoice.",
            "schema": { "type": "string" }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": { "$ref": "#/components/schemas/AgentOrderRequest" }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Order placed successfully",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/OrderResponse" }
              }
            }
          },
          "400": { "description": "Invalid request body or wrong endpoint for product size" },
          "402": {
            "description": "Payment required. Pay the USDC amount specified in the response and retry with X-PAYMENT header.",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/PaymentRequired" }
              }
            }
          },
          "404": { "description": "Product not found" },
          "409": { "description": "Payment already used" },
          "500": { "description": "Fulfillment error" }
        }
      }
    },
    "/api/order/large": {
      "post": {
        "operationId": "orderLarge",
        "summary": "Order a 1lb bag — $22.00 USDC",
        "description": "Places a 1lb coffee order. Same x402 payment flow as /api/order/small. Supports Idempotency-Key header.",
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "description": "Idempotency key to prevent duplicate orders on retry.",
            "schema": { "type": "string" }
          },
          {
            "name": "X-PAYMENT",
            "in": "header",
            "required": false,
            "description": "x402 payment proof header.",
            "schema": { "type": "string" }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": { "$ref": "#/components/schemas/AgentOrderRequest" }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Order placed successfully",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/OrderResponse" }
              }
            }
          },
          "400": { "description": "Invalid request body or wrong endpoint for product size" },
          "402": {
            "description": "Payment required. Pay the USDC amount and retry with X-PAYMENT header.",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/PaymentRequired" }
              }
            }
          },
          "404": { "description": "Product not found" },
          "409": { "description": "Payment already used" },
          "500": { "description": "Fulfillment error" }
        }
      }
    },
    "/api/order/merch/tshirt": {
      "post": {
        "operationId": "orderTshirt",
        "summary": "Order a t-shirt — $30.00 USDC",
        "description": "Places a t-shirt order. Protected by x402: first request returns 402 with USDC payment instructions. Pay on Base, retry with X-PAYMENT header. Variant format: 'color / size' e.g. 'black / M'.",
        "parameters": [
          { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string" } },
          { "name": "X-PAYMENT", "in": "header", "required": false, "schema": { "type": "string" } }
        ],
        "requestBody": {
          "required": true,
          "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MerchOrderRequest" } } }
        },
        "responses": {
          "200": { "description": "Order placed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrderResponse" } } } },
          "400": { "description": "Invalid variant or missing fields" },
          "402": { "description": "Payment required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentRequired" } } } },
          "409": { "description": "Payment already used" },
          "500": { "description": "Fulfillment error" }
        }
      }
    },
    "/api/order/merch/hoodie": {
      "post": {
        "operationId": "orderHoodie",
        "summary": "Order a hoodie — $55.00 USDC",
        "description": "Places a hoodie order. Same x402 flow. Variant format: 'color / size' e.g. 'black / L'.",
        "parameters": [
          { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string" } },
          { "name": "X-PAYMENT", "in": "header", "required": false, "schema": { "type": "string" } }
        ],
        "requestBody": {
          "required": true,
          "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MerchOrderRequest" } } }
        },
        "responses": {
          "200": { "description": "Order placed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrderResponse" } } } },
          "400": { "description": "Invalid variant or missing fields" },
          "402": { "description": "Payment required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentRequired" } } } },
          "409": { "description": "Payment already used" },
          "500": { "description": "Fulfillment error" }
        }
      }
    },
    "/api/order/merch/hat": {
      "post": {
        "operationId": "orderHat",
        "summary": "Order a hat — $28.00 USDC",
        "description": "Places a hat order. Same x402 flow. Variant is color only — e.g. 'black', 'tan'. One size fits all.",
        "parameters": [
          { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string" } },
          { "name": "X-PAYMENT", "in": "header", "required": false, "schema": { "type": "string" } }
        ],
        "requestBody": {
          "required": true,
          "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MerchOrderRequest" } } }
        },
        "responses": {
          "200": { "description": "Order placed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrderResponse" } } } },
          "400": { "description": "Invalid variant or missing fields" },
          "402": { "description": "Payment required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentRequired" } } } },
          "409": { "description": "Payment already used" },
          "500": { "description": "Fulfillment error" }
        }
      }
    },
    "/api/order/merch/mug": {
      "post": {
        "operationId": "orderMug",
        "summary": "Order a mug — $22.00 USDC",
        "description": "Places a mug order. Same x402 flow. Variant is color only — e.g. 'white', 'black'.",
        "parameters": [
          { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string" } },
          { "name": "X-PAYMENT", "in": "header", "required": false, "schema": { "type": "string" } }
        ],
        "requestBody": {
          "required": true,
          "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MerchOrderRequest" } } }
        },
        "responses": {
          "200": { "description": "Order placed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrderResponse" } } } },
          "400": { "description": "Invalid variant or missing fields" },
          "402": { "description": "Payment required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentRequired" } } } },
          "409": { "description": "Payment already used" },
          "500": { "description": "Fulfillment error" }
        }
      }
    },
    "/api/track/{orderId}": {
      "get": {
        "operationId": "trackOrder",
        "summary": "Get order status",
        "description": "Returns the current status of an order, including tracking number once shipped.",
        "parameters": [
          {
            "name": "orderId",
            "in": "path",
            "required": true,
            "schema": { "type": "string", "format": "uuid" }
          }
        ],
        "responses": {
          "200": {
            "description": "Order status",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/TrackingResponse" }
              }
            }
          },
          "404": { "description": "Order not found" }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "HealthResponse": {
        "type": "object",
        "properties": {
          "status": { "type": "string", "example": "ok" },
          "timestamp": { "type": "string", "format": "date-time" },
          "version": { "type": "string", "example": "1.0.0" }
        }
      },
      "CatalogResponse": {
        "type": "object",
        "properties": {
          "products": {
            "type": "array",
            "items": { "$ref": "#/components/schemas/Product" }
          }
        }
      },
      "Product": {
        "type": "object",
        "properties": {
          "id": { "type": "string", "example": "medium-12oz" },
          "name": { "type": "string", "example": "Medium Roast — 12oz" },
          "roast": { "type": "string", "enum": ["light", "medium", "dark"] },
          "size": { "type": "string", "enum": ["12oz", "1lb"] },
          "description": { "type": "string" },
          "roastNotes": { "type": "array", "items": { "type": "string" } },
          "price": {
            "type": "object",
            "properties": { "usd": { "type": "number", "example": 16 } }
          },
          "subscriptionPrice": {
            "type": "object",
            "properties": { "usd": { "type": "number", "example": 14 } }
          },
          "variants": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "grind": { "type": "string", "enum": ["ground", "whole-bean"] },
                "endpoint": { "type": "string" }
              }
            }
          },
          "paymentProtocol": { "type": "string", "example": "x402" },
          "paymentToken": { "type": "string", "example": "USDC" },
          "paymentNetwork": { "type": "string", "example": "base" }
        }
      },
      "ShippingAddress": {
        "type": "object",
        "required": ["name", "line1", "city", "state", "zip"],
        "properties": {
          "name": { "type": "string", "example": "Jane Doe" },
          "email": { "type": "string", "format": "email", "description": "Optional for agents" },
          "line1": { "type": "string", "example": "123 Main St" },
          "line2": { "type": "string", "example": "Apt 4B" },
          "city": { "type": "string", "example": "San Francisco" },
          "state": { "type": "string", "example": "CA", "description": "2-letter US state code" },
          "zip": { "type": "string", "example": "94105" }
        }
      },
      "AgentOrderRequest": {
        "type": "object",
        "required": ["productId", "grind", "shipping"],
        "properties": {
          "productId": {
            "type": "string",
            "enum": ["light-12oz", "medium-12oz", "dark-12oz", "light-1lb", "medium-1lb", "dark-1lb"],
            "description": "Use /api/catalog to get current product IDs"
          },
          "grind": { "type": "string", "enum": ["ground", "whole-bean"] },
          "quantity": { "type": "integer", "minimum": 1, "maximum": 10, "default": 1 },
          "shipping": { "$ref": "#/components/schemas/ShippingAddress" }
        }
      },
      "MerchOrderRequest": {
        "type": "object",
        "required": ["variant", "shipping"],
        "properties": {
          "variant": {
            "type": "string",
            "description": "For apparel: 'color / size' e.g. 'black / M'. For hat/mug: color only e.g. 'black'.",
            "example": "black / M"
          },
          "quantity": { "type": "integer", "minimum": 1, "maximum": 10, "default": 1 },
          "shipping": { "$ref": "#/components/schemas/ShippingAddress" }
        }
      },
      "OrderResponse": {
        "type": "object",
        "properties": {
          "orderId": { "type": "string", "format": "uuid" },
          "trackingNumber": { "type": "string", "nullable": true },
          "status": { "type": "string", "example": "submitted" },
          "total": { "type": "number", "nullable": true, "description": "Amount charged in USD/USDC", "example": 16 }
        }
      },
      "TrackingResponse": {
        "type": "object",
        "properties": {
          "orderId": { "type": "string", "format": "uuid" },
          "status": { "type": "string", "enum": ["pending", "paid", "submitted", "shipped", "delivered", "error"] },
          "trackingNumber": { "type": "string", "nullable": true },
          "items": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "name":     { "type": "string" },
                "grind":    { "type": "string", "enum": ["ground", "whole-bean"] },
                "quantity": { "type": "integer" }
              }
            }
          },
          "total":     { "type": "number", "nullable": true },
          "createdAt":     { "type": "string", "format": "date-time" }
        }
      },
      "PaymentRequired": {
        "type": "object",
        "description": "x402 payment instructions. Use an x402-compatible client to pay automatically.",
        "properties": {
          "error": { "type": "string", "example": "Payment required" },
          "accepts": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "protocol": { "type": "string", "example": "exact" },
                "network": { "type": "string", "example": "base" },
                "maxAmountRequired": { "type": "string", "example": "16000000" },
                "resource": { "type": "string" },
                "description": { "type": "string" },
                "mimeType": { "type": "string" },
                "payTo": { "type": "string", "description": "USDC recipient address on Base" },
                "maxTimeoutSeconds": { "type": "integer" },
                "asset": { "type": "string", "description": "USDC contract address on Base" },
                "extra": { "type": "object" }
              }
            }
          }
        }
      }
    }
  }
}