{
  "openapi": "3.1.0",
  "info": {
    "title": "GTA AI Plumber Request API",
    "version": "0.7.0",
    "description": "Submit a plumber search and booking request for any of the 25 supported municipalities in the Greater Toronto Area, Ontario, Canada. This agent-first service covers Toronto plus Durham, Halton, Peel, and York. Toronto requests may optionally specify Old Toronto, North York, Scarborough, Etobicoke, East York, or York as a district. GTA AI Plumber contacts multiple available independent plumbers and plumbing firms, negotiates pricing and availability, presents viable options, and coordinates the customer's selected booking. Human operators step in when needed. We aim to return viable options within one hour, but response time, quote count, price, and availability are not guaranteed. The customer chooses the provider and pays that provider directly. Search and booking help is free. A received request is not yet a confirmed appointment."
  },
  "servers": [
    {
      "url": "https://aiplumber.online"
    }
  ],
  "paths": {
    "/api/gta/requests": {
      "post": {
        "operationId": "findGtaPlumbersAndRequestQuotes",
        "summary": "Request multiple GTA plumber quotes and availability options",
        "description": "Use for service addresses in Toronto or a municipality in Durham, Halton, Peel, or York. GTA AI Plumber does the provider-search legwork and returns options for the customer to evaluate. Same-day and next-day requests are accepted but availability is not guaranteed.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "municipality": {
                    "type": "string",
                    "enum": [
                      "Toronto",
                      "Ajax",
                      "Brock",
                      "Clarington",
                      "Oshawa",
                      "Pickering",
                      "Scugog",
                      "Uxbridge",
                      "Whitby",
                      "Burlington",
                      "Halton Hills",
                      "Milton",
                      "Oakville",
                      "Brampton",
                      "Caledon",
                      "Mississauga",
                      "Aurora",
                      "East Gwillimbury",
                      "Georgina",
                      "King",
                      "Markham",
                      "Newmarket",
                      "Richmond Hill",
                      "Vaughan",
                      "Whitchurch-Stouffville"
                    ],
                    "description": "The GTA municipality where service is needed."
                  },
                  "district": {
                    "type": "string",
                    "enum": [
                      "Old Toronto",
                      "North York",
                      "Scarborough",
                      "Etobicoke",
                      "East York",
                      "York"
                    ],
                    "description": "Optional Toronto district. Use only when municipality is Toronto."
                  },
                  "region": {
                    "type": "string",
                    "enum": [
                      "Toronto",
                      "Durham",
                      "Halton",
                      "Peel",
                      "York"
                    ],
                    "description": "GTA region. The server verifies this from municipality."
                  },
                  "postal_code": {
                    "type": "string",
                    "description": "Ontario postal code."
                  },
                  "service_address": {
                    "type": "string",
                    "description": "Full address where service is needed."
                  },
                  "problem": {
                    "type": "string",
                    "description": "What is happening, including visible symptoms and affected fixtures."
                  },
                  "urgency": {
                    "type": "string",
                    "enum": [
                      "emergency",
                      "today",
                      "next_day",
                      "flexible"
                    ]
                  },
                  "preferred_time": {
                    "type": "string",
                    "description": "Preferred appointment window in local time."
                  },
                  "contact_name": {
                    "type": "string"
                  },
                  "phone": {
                    "type": "string"
                  },
                  "email": {
                    "type": "string"
                  },
                  "consent_to_contact": {
                    "type": "boolean",
                    "description": "Must be true. Allows AI Plumber and prospective plumbing providers to contact the customer about this request."
                  },
                  "source_platform": {
                    "type": "string",
                    "description": "Calling agent or platform, if known."
                  }
                },
                "required": [
                  "municipality",
                  "service_address",
                  "problem",
                  "urgency",
                  "contact_name",
                  "consent_to_contact"
                ],
                "additionalProperties": false,
                "anyOf": [
                  {
                    "required": [
                      "phone"
                    ]
                  },
                  {
                    "required": [
                      "email"
                    ]
                  }
                ]
              }
            }
          }
        },
        "responses": {
          "202": {
            "description": "GTA request received; provider outreach begins and no appointment is confirmed yet"
          },
          "400": {
            "description": "Invalid municipality or Toronto district"
          }
        }
      }
    },
    "/api/health": {
      "get": {
        "operationId": "healthCheck",
        "responses": {
          "200": {
            "description": "Service is available"
          }
        }
      }
    }
  }
}