{
	"openapi": "3.1.0",
	"info": {
		"title": "PermitBot API",
		"description": "Auckland property zoning lookup, building compliance checking, and AEE document generation.",
		"version": "1.0.0",
		"contact": {
			"name": "PermitBot Support",
			"email": "help@support.permitbot.co.nz",
			"url": "https://permitbot.co.nz"
		}
	},
	"servers": [
		{
			"url": "https://permitbot.co.nz",
			"description": "Production"
		}
	],
	"paths": {
		"/api/lookup": {
			"post": {
				"operationId": "lookupProperty",
				"summary": "Look up property zoning and overlays",
				"description": "Query Auckland Council GIS for property zoning, overlays, and boundary information. Free, no authentication required.",
				"requestBody": {
					"required": true,
					"content": {
						"application/json": {
							"schema": {
								"$ref": "#/components/schemas/LookupRequest"
							}
						}
					}
				},
				"responses": {
					"200": {
						"description": "Property information found",
						"content": {
							"application/json": {
								"schema": {
									"$ref": "#/components/schemas/LookupResponse"
								}
							}
						}
					},
					"400": {
						"description": "Invalid request",
						"content": {
							"application/json": {
								"schema": {
									"$ref": "#/components/schemas/ErrorResponse"
								}
							}
						}
					},
					"429": {
						"description": "Rate limit exceeded",
						"headers": {
							"Retry-After": {
								"description": "Seconds until rate limit resets",
								"schema": {
									"type": "integer"
								}
							}
						},
						"content": {
							"application/json": {
								"schema": {
									"$ref": "#/components/schemas/ErrorResponse"
								}
							}
						}
					}
				}
			}
		},
		"/api/generate": {
			"post": {
				"operationId": "generateCompliance",
				"summary": "Generate compliance check and AEE preview",
				"description": "Generate a compliance assessment and AEE document preview for a building project. Free — returns markdown content and compliance status.",
				"requestBody": {
					"required": true,
					"content": {
						"application/json": {
							"schema": {
								"$ref": "#/components/schemas/GenerateRequest"
							}
						}
					}
				},
				"responses": {
					"200": {
						"description": "AEE document generated",
						"content": {
							"application/json": {
								"schema": {
									"$ref": "#/components/schemas/GenerateResponse"
								}
							}
						}
					},
					"400": {
						"description": "Invalid request",
						"content": {
							"application/json": {
								"schema": {
									"$ref": "#/components/schemas/ErrorResponse"
								}
							}
						}
					},
					"429": {
						"description": "Rate limit exceeded",
						"headers": {
							"Retry-After": {
								"description": "Seconds until rate limit resets",
								"schema": {
									"type": "integer"
								}
							}
						},
						"content": {
							"application/json": {
								"schema": {
									"$ref": "#/components/schemas/ErrorResponse"
								}
							}
						}
					}
				}
			}
		},
		"/api/checkout": {
			"post": {
				"operationId": "createCheckout",
				"summary": "Create Stripe payment link",
				"description": "Create a Stripe checkout session for an AEE document. Returns a URL to redirect the user to for payment ($299 NZD).",
				"requestBody": {
					"required": true,
					"content": {
						"application/json": {
							"schema": {
								"$ref": "#/components/schemas/CheckoutRequest"
							}
						}
					}
				},
				"responses": {
					"200": {
						"description": "Checkout session created",
						"content": {
							"application/json": {
								"schema": {
									"$ref": "#/components/schemas/CheckoutResponse"
								}
							}
						}
					},
					"400": {
						"description": "Invalid request",
						"content": {
							"application/json": {
								"schema": {
									"$ref": "#/components/schemas/ErrorResponse"
								}
							}
						}
					},
					"429": {
						"description": "Rate limit exceeded",
						"headers": {
							"Retry-After": {
								"description": "Seconds until rate limit resets",
								"schema": {
									"type": "integer"
								}
							}
						},
						"content": {
							"application/json": {
								"schema": {
									"$ref": "#/components/schemas/ErrorResponse"
								}
							}
						}
					}
				}
			}
		}
	},
	"components": {
		"schemas": {
			"LookupRequest": {
				"type": "object",
				"required": ["address"],
				"properties": {
					"address": {
						"type": "string",
						"description": "Auckland street address",
						"example": "42 Example Street, Remuera, Auckland"
					}
				}
			},
			"LookupResponse": {
				"type": "object",
				"properties": {
					"success": {
						"type": "boolean",
						"const": true
					},
					"data": {
						"$ref": "#/components/schemas/PropertyInfo"
					}
				}
			},
			"PropertyInfo": {
				"type": "object",
				"properties": {
					"address": {
						"type": "string"
					},
					"zoning": {
						"$ref": "#/components/schemas/ZoningInfo"
					},
					"overlays": {
						"type": "array",
						"items": {
							"$ref": "#/components/schemas/Overlay"
						}
					},
					"boundaries": {
						"type": "object",
						"properties": {
							"coordinates": {
								"type": "array",
								"items": {
									"type": "array",
									"items": {
										"type": "number"
									}
								}
							},
							"area": {
								"type": "number",
								"description": "Property area in square meters"
							}
						}
					}
				}
			},
			"ZoningInfo": {
				"type": "object",
				"properties": {
					"baseZone": {
						"type": "string",
						"description": "Full zone name",
						"example": "Residential - Single House Zone"
					},
					"zoneCode": {
						"type": "string",
						"description": "Zone abbreviation",
						"enum": ["SH", "MHS", "MHU", "THAB", "MU"],
						"example": "SH"
					},
					"precinct": {
						"type": ["string", "null"]
					}
				}
			},
			"Overlay": {
				"type": "object",
				"properties": {
					"type": {
						"type": "string",
						"description": "Overlay category",
						"example": "volcanic_viewshaft"
					},
					"name": {
						"type": "string",
						"description": "Overlay display name",
						"example": "Volcanic Viewshaft - VS1"
					},
					"subArea": {
						"type": ["string", "null"]
					}
				}
			},
			"GenerateRequest": {
				"type": "object",
				"required": ["address", "property", "specs"],
				"properties": {
					"address": {
						"type": "string"
					},
					"property": {
						"$ref": "#/components/schemas/PropertyInfo"
					},
					"specs": {
						"$ref": "#/components/schemas/ProjectSpecs"
					},
					"applicantName": {
						"type": "string",
						"description": "Optional name for the AEE document"
					}
				}
			},
			"GenerateResponse": {
				"type": "object",
				"properties": {
					"success": {
						"type": "boolean",
						"const": true
					},
					"data": {
						"type": "object",
						"properties": {
							"markdown": {
								"type": "string",
								"description": "Full AEE document in markdown format"
							},
							"compliance": {
								"type": "object",
								"properties": {
									"status": {
										"type": "string",
										"enum": ["permitted", "consent_required"]
									},
									"summary": {
										"type": "string"
									}
								}
							},
							"citations": {
								"type": "array",
								"items": {
									"$ref": "#/components/schemas/Citation"
								}
							}
						}
					}
				}
			},
			"Citation": {
				"type": "object",
				"properties": {
					"ruleId": {
						"type": "string",
						"example": "H3.6.1"
					},
					"fullReference": {
						"type": "string",
						"example": "Auckland Unitary Plan Rule H3.6.1(1)"
					},
					"verified": {
						"type": "boolean"
					}
				}
			},
			"CheckoutRequest": {
				"type": "object",
				"required": ["address", "property", "specs"],
				"properties": {
					"address": {
						"type": "string"
					},
					"property": {
						"$ref": "#/components/schemas/PropertyInfo"
					},
					"specs": {
						"$ref": "#/components/schemas/ProjectSpecs"
					},
					"applicantName": {
						"type": "string"
					},
					"email": {
						"type": "string",
						"format": "email",
						"description": "Email to send the completed AEE PDF to"
					}
				}
			},
			"CheckoutResponse": {
				"type": "object",
				"properties": {
					"success": {
						"type": "boolean",
						"const": true
					},
					"url": {
						"type": "string",
						"format": "uri",
						"description": "Stripe checkout URL — redirect the user here"
					}
				}
			},
			"ProjectSpecs": {
				"oneOf": [
					{ "$ref": "#/components/schemas/DeckSpecs" },
					{ "$ref": "#/components/schemas/FenceSpecs" },
					{ "$ref": "#/components/schemas/ShedSpecs" },
					{ "$ref": "#/components/schemas/CarportSpecs" }
				],
				"discriminator": {
					"propertyName": "type"
				}
			},
			"DeckSpecs": {
				"type": "object",
				"required": ["type", "length", "width", "height", "setback", "location"],
				"properties": {
					"type": {
						"type": "string",
						"const": "deck"
					},
					"length": {
						"type": "number",
						"description": "Length in meters"
					},
					"width": {
						"type": "number",
						"description": "Width in meters"
					},
					"height": {
						"type": "number",
						"description": "Height above ground in meters"
					},
					"setback": {
						"type": "number",
						"description": "Distance from nearest boundary in meters"
					},
					"location": {
						"type": "string",
						"enum": ["front", "side", "rear"]
					},
					"roofCovered": {
						"type": "boolean",
						"default": false
					}
				}
			},
			"FenceSpecs": {
				"type": "object",
				"required": ["type", "length", "height", "material", "location"],
				"properties": {
					"type": {
						"type": "string",
						"const": "fence"
					},
					"length": {
						"type": "number",
						"description": "Length in meters"
					},
					"height": {
						"type": "number",
						"description": "Height in meters"
					},
					"material": {
						"type": "string",
						"description": "Fence material (e.g. timber, steel)"
					},
					"location": {
						"type": "string",
						"enum": ["front", "side", "rear"]
					}
				}
			},
			"ShedSpecs": {
				"type": "object",
				"required": ["type", "length", "width", "height", "setback", "location"],
				"properties": {
					"type": {
						"type": "string",
						"const": "shed"
					},
					"length": {
						"type": "number",
						"description": "Length in meters"
					},
					"width": {
						"type": "number",
						"description": "Width in meters"
					},
					"height": {
						"type": "number",
						"description": "Height in meters"
					},
					"setback": {
						"type": "number",
						"description": "Distance from nearest boundary in meters"
					},
					"location": {
						"type": "string",
						"enum": ["front", "side", "rear"]
					}
				}
			},
			"CarportSpecs": {
				"type": "object",
				"required": ["type", "length", "width", "height", "setback", "location"],
				"properties": {
					"type": {
						"type": "string",
						"const": "carport"
					},
					"length": {
						"type": "number",
						"description": "Length in meters"
					},
					"width": {
						"type": "number",
						"description": "Width in meters"
					},
					"height": {
						"type": "number",
						"description": "Height in meters"
					},
					"setback": {
						"type": "number",
						"description": "Distance from nearest boundary in meters"
					},
					"location": {
						"type": "string",
						"enum": ["front", "side", "rear"]
					},
					"attached": {
						"type": "boolean",
						"default": false
					}
				}
			},
			"ErrorResponse": {
				"type": "object",
				"properties": {
					"success": {
						"type": "boolean",
						"const": false
					},
					"error": {
						"type": "string"
					}
				}
			}
		}
	}
}