{
  "openapi": "3.1.0",
  "info": {
    "title": "Baldwin Pergolas Quote API",
    "version": "2.0.0",
    "description": "Estimated material pricing from Baldwin Pergolas' 3D configurators.\nReturns the same price shown to customers on the live website.\n\n**Important:** This is a budgetary estimate only, not a binding quote.\nFinal pricing is confirmed after design review. Prices exclude lighting,\nfootings, electrical, permits, shipping, installation, and applicable tax.\n",
    "contact": {
      "email": "sales@baldwinpergolas.com",
      "url": "https://www.baldwinpergolas.com"
    }
  },
  "servers": [
    {
      "url": "https://www.baldwinpergolas.com"
    }
  ],
  "paths": {
    "/api/pergola/quote.php": {
      "post": {
        "operationId": "quotePergola",
        "summary": "Get an estimated material price for a pergola or lattice panel",
        "description": "Returns the estimated material price in USD, specifications, and a URL\nthat opens the design in the 3D configurator. The price covers materials\nonly: columns, beams, rafters, purlins, stainless fasteners, and paint.\n",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/QuoteRequest"
              },
              "examples": {
                "classic_freestanding": {
                  "summary": "Classic freestanding pergola",
                  "value": {
                    "product": "classic",
                    "config": "freestanding",
                    "width": 216,
                    "depth": 144,
                    "height": 96,
                    "colStyleIdx": 2,
                    "columnQTY": 4,
                    "beam": "2x8",
                    "tail": "windsor",
                    "colorKey": "white",
                    "rafterSpacing": 20,
                    "purlinSpacing": 16
                  }
                },
                "classic_colonnade": {
                  "summary": "Classic colonnade (covered walkway)",
                  "value": {
                    "product": "classic",
                    "config": "colonnade",
                    "width": 168,
                    "depth": 42,
                    "height": 96,
                    "colStyleIdx": 2,
                    "beam": "2x8",
                    "tail": "windsor",
                    "colorKey": "white",
                    "rafterSpacing": 20,
                    "purlinSpacing": 20
                  }
                },
                "modern_classic": {
                  "summary": "Modern classic pergola",
                  "value": {
                    "product": "modern",
                    "width": 168,
                    "depth": 168,
                    "height": 96,
                    "colorKey": "white",
                    "rafterSpacing": 20,
                    "purlinSpacing": 15,
                    "packageKey": "modern_classic"
                  }
                },
                "curved": {
                  "summary": "Curved fiberglass pergola",
                  "value": {
                    "product": "curved",
                    "radius": 15,
                    "arc": 90,
                    "depth": 14,
                    "colHeight": 8,
                    "colStyleIdx": 2,
                    "tail": "windsor",
                    "colorKey": "white",
                    "rafterSpacing": 15,
                    "purlinSpacing": 18
                  }
                },
                "lattice": {
                  "summary": "Lattice panel with supports",
                  "value": {
                    "product": "lattice",
                    "panelWidthFt": 12,
                    "panelHeightFt": 8,
                    "supportType": "fiberglass_8",
                    "supportSizeIn": 8,
                    "supportHeightFt": 8,
                    "anchorType": "post_mount",
                    "colorKey": "white"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Estimated material price and configuration",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/QuoteResponse"
                }
              }
            }
          },
          "400": {
            "description": "Invalid configuration — see error message for details",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string",
                      "description": "Plain-language explanation of what is invalid and how to fix it"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key"
          },
          "429": {
            "description": "Rate limit exceeded (60 requests per minute)"
          },
          "502": {
            "description": "Pricing service temporarily unavailable"
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "description": "API key obtained from Baldwin Pergolas (sales@baldwinpergolas.com)"
      }
    },
    "schemas": {
      "QuoteRequest": {
        "type": "object",
        "additionalProperties": false,
        "description": "Configuration parameters. Not all fields apply to every product.\nRequired fields depend on the `product` value.\n",
        "properties": {
          "product": {
            "type": "string",
            "enum": [
              "classic",
              "modern",
              "curved",
              "lattice"
            ],
            "default": "classic",
            "description": "Which configurator to price"
          },
          "config": {
            "type": "string",
            "enum": [
              "freestanding",
              "attached",
              "colonnade"
            ],
            "default": "freestanding",
            "description": "Configuration type (classic and curved only)"
          },
          "width": {
            "type": "number",
            "minimum": 96,
            "maximum": 720,
            "default": 168,
            "description": "Width in inches (classic, modern). For curved, use `radius` instead."
          },
          "depth": {
            "type": "number",
            "default": 144,
            "description": "Depth in inches (classic: 96–288; colonnade: 24–48).\nFor curved, use `depth` in feet (0–60).\nFor lattice, not used.\n"
          },
          "height": {
            "type": "integer",
            "minimum": 72,
            "maximum": 144,
            "default": 96,
            "description": "Column height in inches (classic, modern). For curved, use `colHeight` in feet."
          },
          "colStyleIdx": {
            "type": "integer",
            "minimum": 0,
            "maximum": 3,
            "default": 2,
            "description": "Column style index:\n0 = 10-inch round,\n1 = 12-inch round,\n2 = 10-inch square,\n3 = 12-inch square\n"
          },
          "colType": {
            "type": "string",
            "description": "Legacy column type code (derived from colStyleIdx and height)"
          },
          "columnQTY": {
            "oneOf": [
              {
                "type": "integer",
                "minimum": 2,
                "maximum": 40
              },
              {
                "type": "string",
                "enum": [
                  ""
                ]
              }
            ],
            "default": "",
            "description": "Number of columns. Omit or empty string for automatic.\nFreestanding must be even and at least 4.\nAttached/colonnade must be at least 2.\n"
          },
          "beam": {
            "type": "string",
            "enum": [
              "2x8",
              "4x12"
            ],
            "default": "2x8",
            "description": "Beam size (classic only)"
          },
          "tail": {
            "type": "string",
            "enum": [
              "windsor",
              "cove",
              "kensington",
              "baldwin",
              "huntington"
            ],
            "default": "windsor",
            "description": "Rafter tail profile"
          },
          "colorKey": {
            "type": "string",
            "enum": [
              "white",
              "linen",
              "platinum",
              "driftwood",
              "sandstone",
              "sage",
              "navy",
              "black",
              "custom"
            ],
            "default": "white",
            "description": "Paint color key"
          },
          "color": {
            "type": "string",
            "pattern": "^#[0-9a-fA-F]{6}$",
            "description": "Hex color value (optional; defaults from colorKey)"
          },
          "colorName": {
            "type": "string",
            "maxLength": 100,
            "description": "Display name for the color (optional; defaults from colorKey)"
          },
          "mount": {
            "type": "string",
            "enum": [
              "Concrete Footings",
              "Concrete Slab",
              "Deck",
              "I don't know"
            ],
            "default": "Concrete Footings",
            "description": "Mounting surface type"
          },
          "rafterSpacing": {
            "type": "number",
            "minimum": 6,
            "maximum": 48,
            "default": 20,
            "description": "Desired rafter spacing in inches"
          },
          "purlinSpacing": {
            "type": "number",
            "minimum": 6,
            "maximum": 48,
            "default": 20,
            "description": "Desired purlin spacing in inches"
          },
          "rafters": {
            "type": "integer",
            "minimum": 2,
            "maximum": 200,
            "description": "Legacy URL field; the configurator derives the count"
          },
          "purlins": {
            "type": "integer",
            "minimum": 2,
            "maximum": 200,
            "description": "Legacy URL field; the configurator derives the count"
          },
          "sunTime": {
            "type": "number",
            "minimum": 0,
            "maximum": 24,
            "description": "Sun time in hours (0–24) for lighting simulation"
          },
          "sunAnimating": {
            "oneOf": [
              {
                "type": "integer",
                "enum": [
                  0,
                  1
                ]
              },
              {
                "type": "string",
                "enum": [
                  "0",
                  "1"
                ]
              }
            ],
            "description": "Whether the sun animation is playing"
          },
          "downlight": {
            "type": "number",
            "minimum": 0,
            "maximum": 100,
            "description": "Downlight intensity percentage"
          },
          "uplight": {
            "type": "number",
            "minimum": 0,
            "maximum": 100,
            "description": "Uplight intensity percentage"
          },
          "colSize": {
            "type": "number",
            "minimum": 6,
            "maximum": 14,
            "default": 9.625,
            "description": "Actual column outside diameter in inches (modern classic)"
          },
          "columnShape": {
            "type": "string",
            "enum": [
              "square",
              "round"
            ],
            "default": "square",
            "description": "Column shape (modern classic)"
          },
          "hatSize": {
            "type": "number",
            "minimum": 2,
            "maximum": 10,
            "default": 5,
            "description": "Hat extrusion width in inches (modern classic)"
          },
          "hatHeight": {
            "type": "number",
            "minimum": 4,
            "maximum": 14,
            "default": 8.5,
            "description": "Hat extrusion height in inches (modern classic)"
          },
          "hatOffset": {
            "type": "number",
            "minimum": 0,
            "maximum": 8,
            "default": 2.75,
            "description": "Hat offset toward exterior in inches (modern classic)"
          },
          "dentils": {
            "type": "boolean",
            "default": true,
            "description": "Whether dentil molding is included (modern classic)"
          },
          "dentilGap": {
            "type": "number",
            "minimum": 0,
            "maximum": 12,
            "default": 2.5,
            "description": "Gap between dentils in inches (modern classic)"
          },
          "packageKey": {
            "type": "string",
            "enum": [
              "modern_classic",
              "modern"
            ],
            "default": "modern_classic",
            "description": "Package type (modern classic)"
          },
          "dentilQTY": {
            "type": "integer",
            "minimum": 0,
            "maximum": 500,
            "default": 0,
            "description": "Number of dentils (modern classic)"
          },
          "radius": {
            "type": "number",
            "minimum": 4,
            "maximum": 60,
            "default": 15,
            "description": "Inner radius in feet (curved)"
          },
          "arc": {
            "type": "number",
            "minimum": 30,
            "maximum": 360,
            "default": 90,
            "description": "Arc angle in degrees (curved)"
          },
          "frontCols": {
            "type": "integer",
            "minimum": 2,
            "maximum": 40,
            "default": 5,
            "description": "Front row columns (curved)"
          },
          "backCols": {
            "type": "integer",
            "minimum": 0,
            "maximum": 40,
            "default": 5,
            "description": "Back row columns (curved; 0 for colonnade)"
          },
          "optFrontCols": {
            "type": "integer",
            "minimum": 0,
            "maximum": 40,
            "default": 0,
            "description": "Optional extra front columns (curved)"
          },
          "optBackCols": {
            "type": "integer",
            "minimum": 0,
            "maximum": 40,
            "default": 0,
            "description": "Optional extra back columns (curved)"
          },
          "colHeight": {
            "type": "number",
            "minimum": 6,
            "maximum": 12,
            "default": 8,
            "description": "Column height in feet (curved)"
          },
          "bearing": {
            "type": "number",
            "minimum": -180,
            "maximum": 180,
            "default": 0,
            "description": "Compass bearing in degrees (curved)"
          },
          "panelWidthFt": {
            "type": "number",
            "minimum": 2,
            "maximum": 40,
            "description": "Panel width in feet (lattice)"
          },
          "panelHeightFt": {
            "type": "number",
            "minimum": 2,
            "maximum": 20,
            "description": "Panel height in feet (lattice)"
          },
          "supportType": {
            "type": "string",
            "enum": [
              "fiberglass_8",
              "fiberglass_10",
              "fiberglass_12",
              "aluminum_4",
              "aluminum_6",
              "aluminum_8",
              "aluminum_10",
              "aluminum_12",
              "fiberglass_column",
              "aluminum_post"
            ],
            "default": "fiberglass_8",
            "description": "Support type (lattice)"
          },
          "supportSizeIn": {
            "type": "number",
            "minimum": 4,
            "maximum": 16,
            "default": 8,
            "description": "Support size in inches (lattice)"
          },
          "supportHeightFt": {
            "type": "number",
            "minimum": 4,
            "maximum": 20,
            "default": 8,
            "description": "Support height in feet (lattice)"
          },
          "anchorType": {
            "type": "string",
            "enum": [
              "post_mount",
              "wall_mount"
            ],
            "default": "post_mount",
            "description": "How the panel is anchored (lattice)"
          },
          "mountSurface": {
            "type": "string",
            "default": "Concrete Footings",
            "description": "Mounting surface (lattice)"
          },
          "sconcesEnabled": {
            "type": "boolean",
            "default": false,
            "description": "Whether sconce lights are enabled (lattice)"
          },
          "sconceLevel": {
            "type": "number",
            "minimum": 0,
            "maximum": 100,
            "default": 50,
            "description": "Sconce brightness percentage (lattice)"
          },
          "frameStyle": {
            "type": "string",
            "description": "Frame style (lattice)"
          },
          "railStyle": {
            "type": "string",
            "description": "Rail style (lattice)"
          },
          "verticalSpacingIn": {
            "type": "number",
            "description": "Vertical lattice spacing in inches (lattice)"
          },
          "horizontalSpacingIn": {
            "type": "number",
            "description": "Horizontal lattice spacing in inches (lattice)"
          }
        }
      },
      "QuoteResponse": {
        "type": "object",
        "required": [
          "price",
          "currency",
          "price_description",
          "product",
          "configuration",
          "specifications",
          "configurator_url"
        ],
        "properties": {
          "price": {
            "type": "integer",
            "description": "Estimated material price in whole USD"
          },
          "currency": {
            "type": "string",
            "enum": [
              "USD"
            ]
          },
          "price_description": {
            "type": "string",
            "description": "What the price includes and excludes"
          },
          "product": {
            "type": "string",
            "enum": [
              "classic",
              "modern",
              "curved",
              "lattice"
            ]
          },
          "configuration": {
            "$ref": "#/components/schemas/QuoteRequest"
          },
          "specifications": {
            "type": "object",
            "properties": {
              "columns": {
                "type": "integer",
                "description": "Number of columns"
              },
              "rafters": {
                "type": "integer",
                "description": "Number of rafters"
              },
              "purlins": {
                "type": "integer",
                "description": "Number of purlins"
              },
              "beams": {
                "type": "integer",
                "description": "Number of beams"
              },
              "rafter_length": {
                "type": "integer",
                "description": "Rafter length in inches"
              },
              "purlin_length": {
                "type": "integer",
                "description": "Purlin length in inches"
              }
            }
          },
          "configurator_url": {
            "type": "string",
            "format": "uri",
            "description": "URL to open this design in the 3D configurator (includes ref=ai for tracking)"
          }
        }
      }
    }
  }
}