{"openapi":"3.1.0","info":{"title":"VoltCraft Grid & Load Engine","version":"1.0.0","description":"Serviceability, NEC load calculation, quoting and booking for home EV charger installs."},"components":{"schemas":{"GridCheck":{"type":"object","properties":{"zip":{"type":"string"},"utility":{"type":"object","properties":{"name":{"type":"string"},"matched":{"type":"boolean"}},"required":["name","matched"]},"permit_fee":{"type":"integer","description":"Municipal permit fee in USD"},"ev_rebate":{"type":"integer","description":"Utility EV charger rebate in USD"},"federal_30c":{"type":"object","properties":{"eligible":{"type":"boolean"},"note":{"type":"string"}},"required":["eligible","note"]}},"required":["zip","utility","permit_fee","ev_rebate","federal_30c"]},"Error":{"type":"object","properties":{"error":{"type":"string"},"issues":{}},"required":["error"]},"Quote":{"type":"object","properties":{"quote_id":{"type":"string","example":"VC-2026-A7K2"},"status":{"type":"string","enum":["QUOTED","BOOKED"]},"inputs":{"type":"object","properties":{"zip_code":{"type":"string","pattern":"^\\d{5}$","example":"78701"},"vehicle_model":{"type":"string","minLength":1,"example":"Tesla Model Y"},"panel_amps":{"anyOf":[{"type":"number","enum":[100]},{"type":"number","enum":[125]},{"type":"number","enum":[150]},{"type":"number","enum":[200]},{"type":"null"}],"description":"Main breaker rating, or null if the homeowner does not know"},"home_build_year":{"type":["integer","null"]},"wire_run_feet":{"type":"integer","minimum":1,"maximum":500},"charger_type":{"type":"string","enum":["tesla_universal","chargepoint_flex","empowered_solar_ev"]},"has_heavy_loads":{"type":"boolean","description":"Pool heat pump, electric dryer, or similar"},"panel_upgrade":{"type":"boolean","description":"Quote a main panel upgrade to 200A (defaults to false)"}},"required":["zip_code","vehicle_model","panel_amps","home_build_year","wire_run_feet","charger_type","has_heavy_loads","panel_upgrade"]},"panel":{"type":"object","properties":{"amps":{"anyOf":[{"type":"number","enum":[100]},{"type":"number","enum":[125]},{"type":"number","enum":[150]},{"type":"number","enum":[200]}]},"estimated":{"type":"boolean"}},"required":["amps","estimated"]},"load":{"type":"object","properties":{"status":{"type":"string","enum":["OK","LOAD_MANAGEMENT_REQUIRED","PANEL_UPGRADE_REQUIRED"]},"evse_breaker_amps":{"type":"number"},"calculated_load_amps":{"type":"number"}},"required":["status","evse_breaker_amps","calculated_load_amps"]},"utility":{"type":"string"},"line_items":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string"},"label":{"type":"string"},"amount":{"type":"integer"}},"required":["code","label","amount"]}},"total":{"type":"integer"},"savings_vs_panel_upgrade":{"type":"integer"},"previous_total":{"type":["integer","null"]},"delta":{"type":["integer","null"]},"created_at":{"type":"string"},"updated_at":{"type":"string"}},"required":["quote_id","status","inputs","panel","load","utility","line_items","total","savings_vs_panel_upgrade","previous_total","delta","created_at","updated_at"]},"CreateQuote":{"type":"object","properties":{"zip_code":{"type":"string","pattern":"^\\d{5}$","example":"78701"},"vehicle_model":{"type":"string","minLength":1,"example":"Tesla Model Y"},"panel_amps":{"anyOf":[{"type":"number","enum":[100]},{"type":"number","enum":[125]},{"type":"number","enum":[150]},{"type":"number","enum":[200]},{"type":"null"}],"description":"Main breaker rating, or null if the homeowner does not know"},"home_build_year":{"type":"integer","minimum":1800,"maximum":2100,"description":"Used to estimate panel_amps when it is null"},"wire_run_feet":{"type":"integer","minimum":1,"maximum":500},"charger_type":{"type":"string","enum":["tesla_universal","chargepoint_flex","empowered_solar_ev"]},"has_heavy_loads":{"type":"boolean","description":"Pool heat pump, electric dryer, or similar"},"panel_upgrade":{"type":"boolean","description":"Quote a main panel upgrade to 200A (defaults to false)"}},"required":["zip_code","vehicle_model","panel_amps","wire_run_feet","charger_type","has_heavy_loads"]},"UpdateQuote":{"type":"object","properties":{"zip_code":{"type":"string","pattern":"^\\d{5}$","example":"78701"},"vehicle_model":{"type":"string","minLength":1,"example":"Tesla Model Y"},"panel_amps":{"anyOf":[{"type":"number","enum":[100]},{"type":"number","enum":[125]},{"type":"number","enum":[150]},{"type":"number","enum":[200]},{"type":"null"}],"description":"Main breaker rating, or null if the homeowner does not know"},"home_build_year":{"type":"integer","minimum":1800,"maximum":2100,"description":"Used to estimate panel_amps when it is null"},"wire_run_feet":{"type":"integer","minimum":1,"maximum":500},"charger_type":{"type":"string","enum":["tesla_universal","chargepoint_flex","empowered_solar_ev"]},"has_heavy_loads":{"type":"boolean","description":"Pool heat pump, electric dryer, or similar"},"panel_upgrade":{"type":"boolean","description":"Quote a main panel upgrade to 200A (defaults to false)"}}},"Booking":{"type":"object","properties":{"confirmation_code":{"type":"string","example":"VCB-7H2KQ9"},"quote_id":{"type":"string"},"customer_name":{"type":"string"},"customer_email":{"type":"string"},"slot":{"type":"string"},"status":{"type":"string","enum":["BOOKED"]}},"required":["confirmation_code","quote_id","customer_name","customer_email","slot","status"]},"CreateBooking":{"type":"object","properties":{"quote_id":{"type":"string","example":"VC-2026-A7K2"},"customer_name":{"type":"string","minLength":1},"customer_email":{"type":"string","format":"email"},"preferred_slot":{"type":"string","format":"date-time","example":"2026-11-12T15:00:00Z"}},"required":["quote_id","customer_name","customer_email","preferred_slot"]},"Telemetry":{"type":"object","properties":{"logs":{"type":"array","items":{"type":"object","additionalProperties":{}}},"quotes":{"type":"array","items":{"type":"object","additionalProperties":{}}},"bookings":{"type":"array","items":{"type":"object","additionalProperties":{}}}},"required":["logs","quotes","bookings"]}},"parameters":{}},"paths":{"/api/v1/grid-check":{"get":{"operationId":"gridCheck","summary":"Look up utility, permit fee, rebate and 30C eligibility for a ZIP code","parameters":[{"schema":{"type":"string","pattern":"^\\d{5}$","example":"78701"},"required":true,"name":"zip","in":"query"}],"responses":{"200":{"description":"Grid details","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GridCheck"}}}},"400":{"description":"Invalid ZIP code","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/quotes":{"post":{"operationId":"createQuote","summary":"Run the NEC 220.82 load calculation, price the install, and persist the quote","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateQuote"}}}},"responses":{"201":{"description":"Itemized quote","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Quote"}}}},"400":{"description":"Validation failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/quotes/{quoteId}":{"get":{"operationId":"getQuote","summary":"Fetch a saved quote","parameters":[{"schema":{"type":"string","example":"VC-2026-A7K2"},"required":true,"name":"quoteId","in":"path"}],"responses":{"200":{"description":"Itemized quote","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Quote"}}}},"404":{"description":"Quote not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"patch":{"operationId":"updateQuote","summary":"Change any input of a saved quote, recalculate, and return the price delta","parameters":[{"schema":{"type":"string","example":"VC-2026-A7K2"},"required":true,"name":"quoteId","in":"path"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateQuote"}}}},"responses":{"200":{"description":"Itemized quote","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Quote"}}}},"400":{"description":"Validation failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Quote not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Quote already booked","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/bookings":{"post":{"operationId":"createBooking","summary":"Lock a technician slot for a quote","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateBooking"}}}},"responses":{"201":{"description":"Booking confirmed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Booking"}}}},"400":{"description":"Validation failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Quote not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Slot or quote already booked","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/telemetry":{"get":{"operationId":"telemetry","summary":"Last 25 API calls and current database state","responses":{"200":{"description":"Telemetry snapshot","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Telemetry"}}}}}}}},"webhooks":{}}