PermitBot API — For AI Agents

Quick Reference

• Base URL: https://permitbot.co.nz
• Content-Type: application/json (all endpoints)
• Authentication: None required
• Price: $299 NZD per AEE document (launch special)
• Supported zones: MHS, MHU, SH, THAB, MU (Auckland residential)
• Supported projects: deck, fence, shed, carport
• OpenAPI spec: https://permitbot.co.nz/openapi.json

API Endpoints

POST https://permitbot.co.nz/api/lookup
Content-Type: application/json

{
  "address": "42 Example Street, Remuera, Auckland"
}

{
  "success": true,
  "data": {
    "address": "42 Example Street, Remuera, Auckland",
    "zoning": {
      "baseZone": "Residential - Single House Zone",
      "zoneCode": "SH",
      "precinct": null
    },
    "overlays": [
      {
        "type": "volcanic_viewshaft",
        "name": "Volcanic Viewshaft - VS1",
        "subArea": null
      }
    ],
    "boundaries": {
      "coordinates": [[...]],
      "area": 650
    }
  }
}

{
  "success": false,
  "error": "Address is required"
}

POST https://permitbot.co.nz/api/generate
Content-Type: application/json

{
  "address": "42 Example Street, Remuera, Auckland",
  "property": {
    "address": "42 Example Street, Remuera, Auckland",
    "zoning": {
      "baseZone": "Residential - Single House Zone",
      "zoneCode": "SH"
    },
    "overlays": []
  },
  "specs": {
    "type": "deck",
    "length": 5,
    "width": 4,
    "height": 0.8,
    "setback": 1.5,
    "location": "rear",
    "roofCovered": false
  },
  "applicantName": "Jane Smith"
}

{
  "success": true,
  "data": {
    "markdown": "# Assessment of Environmental Effects\n\n...",
    "compliance": {
      "status": "permitted",
      "summary": "This deck complies with all Auckland Unitary Plan rules..."
    },
    "citations": [
      {
        "ruleId": "H3.6.1",
        "fullReference": "Auckland Unitary Plan Rule H3.6.1(1)",
        "verified": true
      }
    ]
  }
}

POST https://permitbot.co.nz/api/checkout
Content-Type: application/json

{
  "address": "42 Example Street, Remuera, Auckland",
  "property": {
    "address": "42 Example Street, Remuera, Auckland",
    "zoning": {
      "baseZone": "Residential - Single House Zone",
      "zoneCode": "SH"
    },
    "overlays": []
  },
  "specs": {
    "type": "deck",
    "length": 5,
    "width": 4,
    "height": 0.8,
    "setback": 1.5,
    "location": "rear",
    "roofCovered": false
  },
  "applicantName": "Jane Smith",
  "email": "jane@example.com"
}

{
  "success": true,
  "url": "https://checkout.stripe.com/c/pay/cs_..."
}

Project Specification Schemas

The specs field in /api/generate and /api/checkout accepts these project types:

Deck

{
  "type": "deck",
  "length": 5,        // meters
  "width": 4,         // meters
  "height": 0.8,      // meters above ground level
  "setback": 1.5,     // meters from nearest boundary
  "location": "rear", // "front" | "side" | "rear"
  "roofCovered": false // optional, default false
}

Fence

{
  "type": "fence",
  "length": 12,           // meters
  "height": 1.8,          // meters
  "material": "timber",   // free text
  "location": "side"      // "front" | "side" | "rear"
}

Shed

{
  "type": "shed",
  "length": 4,        // meters
  "width": 3,         // meters
  "height": 2.5,      // meters
  "setback": 1,       // meters from nearest boundary
  "location": "rear"  // "front" | "side" | "rear"
}

Carport

{
  "type": "carport",
  "length": 6,        // meters
  "width": 3,         // meters
  "height": 2.7,      // meters
  "setback": 1,       // meters from nearest boundary
  "location": "front", // "front" | "side" | "rear"
  "attached": true     // optional, default false
}

Recommended Agent Workflow

Here's how an AI agent should guide a user through the process:

1. User says: "I want to build a deck at 42 Example Street, Remuera"
2. Agent: Call POST /api/lookup with the address to get property zoning and overlays.
3. Agent: Tell the user their zone (e.g. "Your property is in the Single House Zone") and any relevant overlays. Ask for deck specifications: length, width, height above ground, distance from boundary, and location (front/side/rear).
4. Agent: Call POST /api/generate with property info and specs. Show the user the compliance result (permitted vs. consent required) and a summary of the assessment.
5. Agent: If the user wants the full AEE document, call POST /api/checkout with their details. Present the Stripe payment link.
6. User: Clicks the payment link, pays $299 NZD, and lands on the success page. PDF is generated and emailed automatically.

Example Conversation

User: I want to build a 5m x 4m deck at 15 Main Road, Grey Lynn

Agent: Let me look up your property...
       [POST /api/lookup {"address": "15 Main Road, Grey Lynn, Auckland"}]

Agent: Your property at 15 Main Road is in the Mixed Housing Urban zone (MHU).
       No special overlays detected. To check compliance, I need a few details:
       - How high will the deck be above ground? (meters)
       - How far from the nearest boundary? (meters)
       - Will it be at the front, side, or rear?
       - Will it have a roof covering?

User: 0.6m high, 1.5m from boundary, at the rear, no roof

Agent: Let me check compliance...
       [POST /api/generate {address, property, specs}]

Agent: Great news! Your 5m × 4m rear deck at 0.6m height COMPLIES with
       Auckland Unitary Plan rules for the MHU zone. Key findings:
       - Height under 1.5m ✓
       - Setback of 1.5m meets the 1m minimum ✓
       - No overlays requiring additional assessment ✓

       Would you like the full AEE document ($299 NZD)? This includes:
       - Professional PDF document
       - All rule citations
       - Emailed to you automatically

User: Yes please, my email is jane@example.com

Agent: [POST /api/checkout {address, property, specs, applicantName, email}]
       Here's your payment link: [Stripe URL]
       After payment, your AEE document will be generated and emailed to
       jane@example.com within a few minutes.

Rate Limits

When rate limited, you'll receive HTTP 429 with a Retry-After header (seconds until reset).

Supported Zones

If a property is not in one of these zones, the lookup will still return data but compliance checking may not cover all rules.

Error Handling

All error responses follow the same format:

{
  "success": false,
  "error": "Human-readable error message"
}