{
  "openapi": "3.1.0",
  "info": {
    "title": "SepticHelp.ca Agent API",
    "version": "1.0.0",
    "description": "Submit septic service quote requests on behalf of users who have given explicit consent. See /agents.md and /.well-known/quote.json."
  },
  "servers": [
    {
      "url": "https://septichelp.ca"
    }
  ],
  "paths": {
    "/api/v1/quotes": {
      "post": {
        "operationId": "submitQuoteRequest",
        "summary": "Submit a septic quote request",
        "description": "User must explicitly agree to share name, phone, email, and property address for contractor matching.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/QuoteRequest"
              },
              "example": {
                "consent": true,
                "issue_type": "pumpout",
                "system_type": "gravity",
                "tank_access": "easy",
                "urgency": "week",
                "last_pumped": "3-5",
                "occupants": "3-4",
                "name": "Jane Doe",
                "email": "jane@example.com",
                "phone": "(403) 555-0100",
                "address": "123 Rural Road",
                "city": "Red Deer",
                "province": "Alberta",
                "postal_code": "T4N 1A1",
                "details": "Tank is due for routine pumping.",
                "agent_source": "chatgpt"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Quote created",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/QuoteSuccess"
                }
              }
            }
          },
          "400": {
            "description": "Validation error"
          },
          "401": {
            "description": "Invalid or missing API key when required"
          },
          "429": {
            "description": "Rate limited"
          },
          "502": {
            "description": "Upstream error"
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "QuoteRequest": {
        "type": "object",
        "required": [
          "consent",
          "issue_type",
          "system_type",
          "tank_access",
          "urgency",
          "name",
          "email",
          "phone",
          "address",
          "city",
          "province"
        ],
        "properties": {
          "consent": {
            "type": "boolean",
            "const": true
          },
          "website": {
            "type": "string",
            "description": "Honeypot - leave empty",
            "maxLength": 0
          },
          "issue_type": {
            "type": "string",
            "enum": [
              "pumpout",
              "backup",
              "alarm",
              "wetarea",
              "inspection",
              "replace",
              "repair",
              "other"
            ]
          },
          "system_type": {
            "type": "string",
            "enum": [
              "gravity",
              "pump",
              "advanced",
              "unknown"
            ]
          },
          "tank_access": {
            "type": "string",
            "enum": [
              "easy",
              "buried",
              "deck",
              "unknown"
            ]
          },
          "urgency": {
            "type": "string",
            "enum": [
              "emergency",
              "soon",
              "week",
              "flexible"
            ]
          },
          "last_pumped": {
            "type": "string",
            "enum": [
              "less1",
              "1-3",
              "3-5",
              "more5",
              "unknown"
            ]
          },
          "occupants": {
            "type": "string",
            "enum": [
              "1-2",
              "3-4",
              "5+",
              "cottage"
            ]
          },
          "constraints": {
            "type": "array",
            "items": {
              "type": "string",
              "enum": [
                "Waterfront property",
                "Steep driveway",
                "Tight access",
                "Near well"
              ]
            }
          },
          "name": {
            "type": "string"
          },
          "email": {
            "type": "string",
            "format": "email"
          },
          "phone": {
            "type": "string"
          },
          "address": {
            "type": "string"
          },
          "city": {
            "type": "string"
          },
          "province": {
            "type": "string",
            "description": "Canadian province or territory name"
          },
          "postal_code": {
            "type": "string"
          },
          "details": {
            "type": "string"
          },
          "vendor_slug": {
            "type": "string",
            "description": "Optional contractor slug from /vendor/{slug}"
          },
          "agent_source": {
            "type": "string",
            "description": "Identifier for the submitting agent (e.g. chatgpt, claude)"
          }
        }
      },
      "QuoteSuccess": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean"
          },
          "id": {
            "type": "string"
          },
          "status": {
            "type": "string"
          },
          "message": {
            "type": "string"
          },
          "human_url": {
            "type": "string",
            "format": "uri"
          }
        }
      }
    }
  }
}