{
  "openapi": "3.1.0",
  "info": {
    "title": "City Wide SWLA Walkthrough Intake",
    "version": "1.0.0",
    "description": "Request review of a commercial facility inquiry. Receipt does not confirm an appointment. No CRM or private business APIs are exposed."
  },
  "servers": [
    {
      "url": "https://www.gocitywideswla.com"
    }
  ],
  "paths": {
    "/api/v1/walkthrough-request": {
      "post": {
        "operationId": "requestFacilityWalkthrough",
        "summary": "Submit a facility walkthrough request",
        "description": "Public intake; no authentication required. No browser CORS access is granted. If Origin is present it must match this website or its configured Vercel deployment. Body limit 16,384 bytes. At most 10 attempts per source IP per 15 minutes. An in-progress identical request returns 429; obey Retry-After. Retry transient 429/502/503 failures with the same Idempotency-Key and unchanged fields. Keys and matching-content fingerprints are retained for 24 hours. Retry uncertain requests for at most 23 hours; after that contact the office before creating another request. Different data with the same key returns 409. Do not log personal data.",
        "parameters": [
          {
            "in": "header",
            "name": "Idempotency-Key",
            "required": true,
            "schema": {
              "type": "string",
              "pattern": "^[A-Za-z0-9_-]{16,128}$"
            },
            "description": "A new random UUID per logical request; reuse unchanged on retry."
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/WalkthroughRequest"
              },
              "example": {
                "contact_name": "Jordan Example",
                "work_email": "jordan@example.com",
                "company": "Fictional Example Facility",
                "facility_city": "Long Beach",
                "facility_type": "Commercial Office",
                "service_needed": "Commercial Cleaning & Janitorial",
                "facility_size_sqft": "25000",
                "service_frequency": "Not sure yet",
                "facility_details": "Fictional test request. Please do not treat this example as a real inquiry."
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Acknowledged intake handoff. Duplicate retries return the original reference.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Receipt"
                }
              }
            }
          },
          "400": {
            "description": "Malformed body or idempotency key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Unacceptable browser origin",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "405": {
            "description": "Method not allowed",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "Key reused with different details",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "413": {
            "description": "Request body too large",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "415": {
            "description": "Unsupported content type",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "422": {
            "description": "Field validation or spam rejection",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Rate limit or request in progress",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer"
                },
                "description": "Seconds to wait before retrying."
              }
            }
          },
          "502": {
            "description": "Handoff not confirmed",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "Intake or duplicate-control backend unavailable",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "WalkthroughRequest": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "contact_name",
          "work_email",
          "company",
          "facility_city",
          "service_needed"
        ],
        "properties": {
          "contact_name": {
            "type": "string",
            "maxLength": 100,
            "description": "Name (required)",
            "minLength": 1
          },
          "work_email": {
            "type": "string",
            "maxLength": 254,
            "description": "Work Email (required)",
            "minLength": 1,
            "format": "email"
          },
          "company": {
            "type": "string",
            "maxLength": 150,
            "description": "Company (required)",
            "minLength": 1
          },
          "phone": {
            "type": "string",
            "maxLength": 40,
            "description": "Phone (optional; empty string allowed)"
          },
          "facility_city": {
            "type": "string",
            "maxLength": 100,
            "description": "Facility City (required)",
            "minLength": 1
          },
          "facility_type": {
            "type": "string",
            "maxLength": 100,
            "description": "Facility Type (optional; empty string allowed)",
            "enum": [
              "",
              "Logistics & Distribution",
              "Commercial Office",
              "Healthcare & Professional",
              "Education",
              "Automotive",
              "Industrial & Manufacturing",
              "Retail & Commercial Property",
              "Other / not sure yet"
            ]
          },
          "service_needed": {
            "type": "string",
            "maxLength": 100,
            "description": "Service Needed (required)",
            "minLength": 1,
            "enum": [
              "Commercial Cleaning & Janitorial",
              "Janitorial Consumables",
              "Lawn Maintenance",
              "Hard Floor Care",
              "Carpet Care",
              "Window Washing",
              "Pressure Washing",
              "Handyman Services",
              "Plumbing",
              "Electrical",
              "HVAC",
              "Parking Lot Services",
              "Tenant Improvement",
              "Multiple services / not sure yet"
            ]
          },
          "facility_size_sqft": {
            "type": "string",
            "maxLength": 12,
            "description": "Approximate Square Footage (optional; empty string allowed)",
            "pattern": "^$|^[1-9][0-9]{0,11}$"
          },
          "service_frequency": {
            "type": "string",
            "maxLength": 100,
            "description": "Desired Frequency (optional; empty string allowed)",
            "enum": [
              "",
              "Daily",
              "Several times a week",
              "Weekly",
              "Monthly",
              "One-time project",
              "Not sure yet"
            ]
          },
          "facility_details": {
            "type": "string",
            "maxLength": 3000,
            "description": "Facility Details (optional; empty string allowed)"
          },
          "website": {
            "type": "string",
            "maxLength": 0,
            "description": "Honeypot; omit or leave empty."
          }
        }
      },
      "Receipt": {
        "type": "object",
        "required": [
          "status",
          "request_id",
          "next_step"
        ],
        "additionalProperties": false,
        "properties": {
          "status": {
            "const": "received"
          },
          "request_id": {
            "type": "string",
            "format": "uuid"
          },
          "next_step": {
            "const": "A City Wide representative will review the request."
          }
        }
      },
      "Error": {
        "type": "object",
        "required": [
          "status",
          "code",
          "message"
        ],
        "properties": {
          "status": {
            "const": "error"
          },
          "code": {
            "type": "string"
          },
          "message": {
            "type": "string"
          },
          "field_errors": {
            "type": "object",
            "additionalProperties": {
              "type": "string"
            }
          }
        }
      }
    }
  }
}