{
 "openapi": "3.1.0",
 "info": {
  "title": "DFW Solar and Battery API",
  "version": "1.0.0",
  "description": "Public answers, estimates and consultation requests for residential solar and battery backup in Dallas–Fort Worth, plus private CRM endpoints (API key) for the business owners’ tools such as Kronos Sales AI, Meta Muse, GoHighLevel, Zapier and Make.",
  "contact": {
   "name": "DFW Solar and Battery",
   "url": "https://dallassolarandbattery.com"
  }
 },
 "servers": [
  {
   "url": "https://dallassolarandbattery.com"
  }
 ],
 "components": {
  "securitySchemes": {
   "bearer": {
    "type": "http",
    "scheme": "bearer",
    "description": "Create an API key in Admin → Marketing → AI agents & API."
   }
  },
  "schemas": {
   "ConsultationRequest": {
    "type": "object",
    "required": [
     "first_name",
     "phone",
     "zip",
     "consent_to_contact"
    ],
    "properties": {
     "first_name": {
      "type": "string"
     },
     "last_name": {
      "type": "string"
     },
     "phone": {
      "type": "string",
      "description": "10-digit US phone"
     },
     "zip": {
      "type": "string",
      "description": "5-digit ZIP"
     },
     "email": {
      "type": "string"
     },
     "address": {
      "type": "string"
     },
     "monthly_bill": {
      "type": "string",
      "description": "e.g. \"$175–$250\" or a dollar amount"
     },
     "goal": {
      "type": "string",
      "enum": [
       "Lower bill",
       "Backup power",
       "Both",
       "Compare a quote"
      ]
     },
     "notes": {
      "type": "string"
     },
     "consent_to_contact": {
      "type": "boolean",
      "description": "Must be true: the homeowner agrees to be called/texted about the request."
     }
    }
   }
  }
 },
 "paths": {
  "/api/v1/info": {
   "get": {
    "operationId": "getBusinessInfo",
    "summary": "Business profile, service area, hours and booking link",
    "responses": {
     "200": {
      "description": "OK"
     }
    }
   }
  },
  "/api/v1/answers": {
   "get": {
    "operationId": "searchAnswers",
    "summary": "Search sourced answers about solar and home batteries in Texas",
    "parameters": [
     {
      "name": "q",
      "in": "query",
      "schema": {
       "type": "string"
      }
     },
     {
      "name": "topic",
      "in": "query",
      "schema": {
       "type": "string"
      }
     }
    ],
    "responses": {
     "200": {
      "description": "OK"
     }
    }
   }
  },
  "/api/v1/facts": {
   "get": {
    "operationId": "getFacts",
    "summary": "Dated, sourced facts dataset",
    "responses": {
     "200": {
      "description": "OK"
     }
    }
   }
  },
  "/api/v1/estimate": {
   "get": {
    "operationId": "estimateSolar",
    "summary": "Planning estimate of solar size, panels, price range and 25-year utility spend from a monthly bill",
    "parameters": [
     {
      "name": "monthly_bill",
      "in": "query",
      "required": true,
      "schema": {
       "type": "number"
      }
     },
     {
      "name": "price_per_kwh",
      "in": "query",
      "schema": {
       "type": "number"
      }
     },
     {
      "name": "coverage_percent",
      "in": "query",
      "schema": {
       "type": "number"
      }
     }
    ],
    "responses": {
     "200": {
      "description": "OK"
     }
    }
   }
  },
  "/api/v1/service-area": {
   "get": {
    "operationId": "checkServiceArea",
    "summary": "Check whether a ZIP code is in the North Texas service area",
    "parameters": [
     {
      "name": "zip",
      "in": "query",
      "required": true,
      "schema": {
       "type": "string"
      }
     }
    ],
    "responses": {
     "200": {
      "description": "OK"
     }
    }
   }
  },
  "/api/v1/consultation-requests": {
   "post": {
    "operationId": "requestConsultation",
    "summary": "Request a free in-home solar & battery review on behalf of a homeowner who consented",
    "requestBody": {
     "required": true,
     "content": {
      "application/json": {
       "schema": {
        "$ref": "#/components/schemas/ConsultationRequest"
       }
      }
     }
    },
    "responses": {
     "200": {
      "description": "Created; returns a booking link to pick a time"
     }
    }
   }
  },
  "/api/v1/leads": {
   "get": {
    "operationId": "listLeads",
    "security": [
     {
      "bearer": []
     }
    ],
    "summary": "List leads (private)",
    "parameters": [
     {
      "name": "stage",
      "in": "query",
      "schema": {
       "type": "string"
      }
     },
     {
      "name": "since",
      "in": "query",
      "schema": {
       "type": "string",
       "format": "date"
      }
     },
     {
      "name": "limit",
      "in": "query",
      "schema": {
       "type": "integer"
      }
     }
    ],
    "responses": {
     "200": {
      "description": "OK"
     }
    }
   },
   "post": {
    "operationId": "createLead",
    "security": [
     {
      "bearer": []
     }
    ],
    "summary": "Push a lead from another tool (Kronos, GoHighLevel, Zapier, Meta lead forms)",
    "requestBody": {
     "content": {
      "application/json": {
       "schema": {
        "type": "object"
       }
      }
     }
    },
    "responses": {
     "200": {
      "description": "OK"
     }
    }
   }
  },
  "/api/v1/leads/{id}": {
   "get": {
    "operationId": "getLead",
    "security": [
     {
      "bearer": []
     }
    ],
    "parameters": [
     {
      "name": "id",
      "in": "path",
      "required": true,
      "schema": {
       "type": "string"
      }
     }
    ],
    "responses": {
     "200": {
      "description": "OK"
     }
    }
   },
   "patch": {
    "operationId": "updateLead",
    "security": [
     {
      "bearer": []
     }
    ],
    "parameters": [
     {
      "name": "id",
      "in": "path",
      "required": true,
      "schema": {
       "type": "string"
      }
     }
    ],
    "requestBody": {
     "content": {
      "application/json": {
       "schema": {
        "type": "object",
        "properties": {
         "stage": {
          "type": "string"
         },
         "assignedTo": {
          "type": "string",
          "enum": [
           "jeremy",
           "dakota",
           ""
          ]
         },
         "note": {
          "type": "string"
         }
        }
       }
      }
     }
    },
    "responses": {
     "200": {
      "description": "OK"
     }
    }
   }
  },
  "/api/v1/appointments": {
   "get": {
    "operationId": "listAppointments",
    "security": [
     {
      "bearer": []
     }
    ],
    "responses": {
     "200": {
      "description": "OK"
     }
    }
   }
  },
  "/api/v1/stats": {
   "get": {
    "operationId": "getStats",
    "security": [
     {
      "bearer": []
     }
    ],
    "summary": "Funnel stats: leads, booked, held, sold by period",
    "responses": {
     "200": {
      "description": "OK"
     }
    }
   }
  },
  "/api/v1/campaigns": {
   "get": {
    "operationId": "getCampaignReport",
    "security": [
     {
      "bearer": []
     }
    ],
    "summary": "Leads, bookings and sales by UTM campaign/ad (for Kronos ad audits and Meta optimization)",
    "responses": {
     "200": {
      "description": "OK"
     }
    }
   }
  }
 }
}