{
  "openapi": "3.1.0",
  "info": {
    "title": "Borek Concrete & Breaking (borekconcreteny) Public API",
    "description": "Official public REST API and developer platform for Borek Concrete & Breaking (borekconcreteny.com). Allows AI agents, automated assistants, and developers to programmatically retrieve concrete service specifications, price lock calculators, municipal sidewalk standards, and submit residential/commercial estimate requests across Central New York.\n\n### Versioning & Deprecation Policy\nThis API uses URI path versioning (/v1/). Backward compatibility is guaranteed for all /v1/ endpoints. Any future major versions (/v2/) will provide a minimum 12-month deprecation notice via standard Sunset (RFC 8594) and Deprecation HTTP headers before retirement.",
    "version": "1.0.0",
    "x-api-versioning": {
      "strategy": "uri-path",
      "current_version": "v1",
      "deprecation_policy": "12-month notice with RFC 8594 Sunset and Deprecation headers"
    },
    "contact": {
      "name": "Borek Concrete & Breaking Developer Relations (borekconcreteny)",
      "email": "brandon@borekconcreteandbreakingllc.com",
      "url": "https://borekconcreteny.com/developers"
    }
  },
  "servers": [
    {
      "url": "https://borekconcreteny.com/v1",
      "description": "Production V1 Server"
    },
    {
      "url": "https://borekconcreteny.com/api",
      "description": "Legacy Alias Server"
    }
  ],
  "paths": {
    "/health": {
      "get": {
        "summary": "Health and diagnostic check",
        "operationId": "getHealthStatus",
        "description": "Returns operational status and availability of the Borek Concrete intake automation engine.",
        "responses": {
          "200": {
            "description": "System is healthy and accepting quote submissions.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "status": { "type": "string", "example": "healthy" },
                    "version": { "type": "string", "example": "v1.0.0" },
                    "timestamp": { "type": "string", "format": "date-time" }
                  }
                }
              }
            }
          },
          "400": { "$ref": "#/components/responses/BadRequestError" },
          "404": { "$ref": "#/components/responses/NotFoundError" },
          "429": { "$ref": "#/components/responses/RateLimitError" },
          "500": { "$ref": "#/components/responses/InternalServerError" }
        }
      }
    },
    "/quote": {
      "post": {
        "summary": "Submit a concrete quote or estimate request",
        "operationId": "submitQuoteRequest",
        "description": "Submits a residential or commercial concrete quote request directly to the foreman estimating queue. No authentication required for public quote intake.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/QuoteRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Quote request successfully received and queued.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/QuoteResponse"
                }
              }
            }
          },
          "400": { "$ref": "#/components/responses/BadRequestError" },
          "404": { "$ref": "#/components/responses/NotFoundError" },
          "422": { "$ref": "#/components/responses/UnprocessableEntityError" },
          "429": { "$ref": "#/components/responses/RateLimitError" },
          "500": { "$ref": "#/components/responses/InternalServerError" }
        }
      }
    },
    "/contact": {
      "post": {
        "summary": "Submit general inquiry",
        "operationId": "submitContactInquiry",
        "description": "Submit a general contact message or project question to the Borek customer service team.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ContactRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Contact message received.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": { "type": "boolean", "example": true },
                    "message": { "type": "string", "example": "Inquiry received." }
                  }
                }
              }
            }
          },
          "400": { "$ref": "#/components/responses/BadRequestError" },
          "404": { "$ref": "#/components/responses/NotFoundError" },
          "422": { "$ref": "#/components/responses/UnprocessableEntityError" },
          "429": { "$ref": "#/components/responses/RateLimitError" },
          "500": { "$ref": "#/components/responses/InternalServerError" }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "ProblemDetails": {
        "type": "object",
        "description": "RFC 9457 compliant problem details object for typed error handling",
        "required": ["type", "title", "status", "detail", "code"],
        "properties": {
          "type": { "type": "string", "format": "uri", "example": "https://borekconcreteny.com/errors/invalid-parameter" },
          "title": { "type": "string", "example": "Bad Request" },
          "status": { "type": "integer", "example": 400 },
          "detail": { "type": "string", "example": "Customer phone number and name are required fields." },
          "code": { "type": "string", "example": "MISSING_REQUIRED_FIELD" },
          "resolution": { "type": "string", "example": "Ensure the payload includes 'name' and 'phone'." },
          "instance": { "type": "string", "format": "uri", "example": "/v1/quote/err-88319" }
        }
      },
      "QuoteRequest": {
        "type": "object",
        "required": ["name", "phone"],
        "properties": {
          "name": { "type": "string", "description": "Customer full name", "example": "John Smith" },
          "phone": { "type": "string", "description": "Contact phone number for estimate follow-up", "example": "(315) 555-0199" },
          "email": { "type": "string", "format": "email", "description": "Customer email address", "example": "john@example.com" },
          "city": { "type": "string", "description": "Project city in Central New York", "example": "Utica" },
          "classification": { "type": "string", "enum": ["residential", "commercial"], "description": "Project category", "example": "residential" },
          "service": { "type": "string", "description": "Concrete service requested (Driveway, Patio, Sidewalk, Breaking)", "example": "Concrete Driveways" },
          "square_footage": { "type": "string", "description": "Estimated square footage", "example": "800 sq ft" },
          "has_removal": { "type": "boolean", "description": "Whether old concrete tear-out is required", "example": true },
          "timeline": { "type": "string", "description": "Desired project timeframe", "example": "Spring 2027" },
          "custom_description": { "type": "string", "description": "Additional project notes or site details", "example": "Tear out existing asphalt driveway and pour new 4000 PSI concrete driveway." },
          "contact_preference": { "type": "string", "enum": ["text", "email", "phone"], "example": "text" }
        }
      },
      "QuoteResponse": {
        "type": "object",
        "properties": {
          "success": { "type": "boolean", "example": true },
          "quote_id": { "type": "string", "format": "uuid", "example": "a7b8c9d0-1234-5678-90ab-cdef12345678" },
          "message": { "type": "string", "example": "Estimate request received. Foreman will follow up via phone/SMS within 24 hours." }
        }
      },
      "ContactRequest": {
        "type": "object",
        "required": ["name", "phone", "message"],
        "properties": {
          "name": { "type": "string", "example": "Sarah Davis" },
          "phone": { "type": "string", "example": "(315) 555-0144" },
          "email": { "type": "string", "format": "email", "example": "sarah@example.com" },
          "subject": { "type": "string", "example": "Sidewalk Repair Question" },
          "message": { "type": "string", "example": "Do you handle city permit requirements for Utica sidewalk replacement?" }
        }
      }
    },
    "responses": {
      "BadRequestError": {
        "description": "Invalid input parameters (RFC 9457 Problem Details)",
        "content": {
          "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } },
          "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } }
        }
      },
      "NotFoundError": {
        "description": "Requested resource was not found (RFC 9457 Problem Details)",
        "content": {
          "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } },
          "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } }
        }
      },
      "UnprocessableEntityError": {
        "description": "Validation failure or unprocessable entity (RFC 9457 Problem Details)",
        "content": {
          "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } },
          "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } }
        }
      },
      "RateLimitError": {
        "description": "Too many requests. Real-time rate limits exceeded.",
        "headers": {
          "RateLimit-Limit": { "schema": { "type": "integer", "example": 60 }, "description": "Requests allowed per window" },
          "RateLimit-Remaining": { "schema": { "type": "integer", "example": 0 }, "description": "Requests remaining" },
          "RateLimit-Reset": { "schema": { "type": "integer", "example": 30 }, "description": "Seconds until reset" },
          "Retry-After": { "schema": { "type": "integer", "example": 30 }, "description": "Seconds to wait before retrying" }
        },
        "content": {
          "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } },
          "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } }
        }
      },
      "InternalServerError": {
        "description": "Internal server processing error (RFC 9457 Problem Details)",
        "content": {
          "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } },
          "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } }
        }
      }
    }
  }
}