openapi: 3.1.0
info:
  title: Vulcan Laser Restoration API
  version: 1.0.0
  description: |
    REST API for Vulcan Laser Restoration service inquiries, health checks, and mobile rig dispatch.
    Officially operating at https://vulcanlr.com.
  contact:
    name: Vulcan Laser Restoration Support
    email: restoration@vulcanlr.com
    url: https://vulcanlr.com
servers:
  - url: https://vulcanlr.com
    description: Production Server
paths:
  /api/health:
    get:
      summary: Health check endpoint
      description: Returns operational status and current server timestamp.
      operationId: getHealthStatus
      responses:
        '200':
          description: Service is healthy and operational.
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    example: "ok"
                  timestamp:
                    type: string
                    format: date-time
                    example: "2026-09-18T16:00:00.000Z"
                required:
                  - status
                  - timestamp
  /api/contact:
    post:
      summary: Submit service inquiry or quote request
      description: Submits a project inquiry for mobile industrial laser cleaning and surface remediation.
      operationId: submitContactInquiry
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                  description: Full name of the contact person or engineering manager.
                  example: "Alex Johnson"
                email:
                  type: string
                  format: email
                  description: Work email address.
                  example: "alex.johnson@petroplant.com"
                phone:
                  type: string
                  description: Direct contact telephone number.
                  example: "+1 (832) 555-0199"
                notes:
                  type: string
                  description: Project specifications, location, substrate type, and timeline.
                  example: "Refinery pipe rack CUI rust removal, 500 linear ft."
                recaptcha_token:
                  type: string
                  description: Google reCAPTCHA v3 verification token.
              required:
                - name
                - email
      responses:
        '200':
          description: Inquiry successfully received and queued for application engineer review.
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  message:
                    type: string
                    example: "Thank you! Your rooftop wind screen restoration inquiry has been received. Our team will contact you shortly."
        '400':
          description: Invalid request payload or failed security verification.
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: false
                  error:
                    type: string
                    example: "reCAPTCHA verification failed. Please try again."
        '429':
          description: Rate limit exceeded. Too many requests from this IP address.
          headers:
            Retry-After:
              description: Number of seconds to wait before retrying.
              schema:
                type: integer
                example: 900
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: false
                  error:
                    type: string
                    example: "Too many requests. Please try again later."