{"openapi":"3.1.0","info":{"title":"Utilify Public API","version":"0.1.0","summary":"Real-time utility plan search for Texas ZIP codes. Built for AI agents.","description":"Utilify compares electricity, internet, gas, water, and trash plans across every Texas ZIP code. Use this API to power plan recommendations, move-in checklists, and promotion lookup inside ChatGPT Custom GPTs, agents, or automation tools. For interactive signup flows use the MCP server at https://utilify.io/mcp — see https://utilify.io/mcp-docs.","contact":{"email":"hello@utilify.io","url":"https://utilify.io"},"license":{"name":"Terms of Service","url":"https://utilify.io/terms.html"},"termsOfService":"https://utilify.io/terms.html"},"servers":[{"url":"https://utilify.io","description":"Production"}],"paths":{"/api/health":{"get":{"operationId":"getHealth","summary":"Service health check","responses":{"200":{"description":"Service is healthy","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","example":"ok"},"version":{"type":"string","example":"0.1.0"},"uptime":{"type":"number","example":1234.56}}}}}}}}},"/api/providers/search":{"get":{"operationId":"searchProviders","summary":"Find utility providers available at an address","description":"Returns every electricity, internet, gas, water, and trash provider that serves the given Texas ZIP. Plans are sorted by estimated monthly cost. Use this as the primary discovery endpoint when a user asks what plans are available at their move-in address.","parameters":[{"name":"address","in":"query","required":true,"description":"Street address, city + state, or 5-digit Texas ZIP code. ZIP-only inputs are fastest.","schema":{"type":"string","example":"77002"}},{"name":"types","in":"query","required":false,"description":"Comma-separated utility types to filter by. Omit to return all types.","schema":{"type":"string","example":"electricity,internet","pattern":"^(electricity|gas|internet|water|trash|security)(,(electricity|gas|internet|water|trash|security))*$"}}],"responses":{"200":{"description":"List of providers grouped by utility type","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SearchResponse"}}}},"400":{"$ref":"#/components/responses/BadRequest"}}}},"/api/providers/{slug}":{"get":{"operationId":"getProviderDetails","summary":"Get detailed plans and pricing for a single provider","parameters":[{"name":"slug","in":"path","required":true,"description":"Provider slug, e.g. 'txu-energy', 'reliant-energy', 'att-fiber', 'spectrum'.","schema":{"type":"string","example":"txu-energy"}},{"name":"address","in":"query","required":false,"description":"Optional address/ZIP to filter plans to those available at that location.","schema":{"type":"string","example":"77002"}}],"responses":{"200":{"description":"Provider detail with plans","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProviderDetail"}}}},"404":{"$ref":"#/components/responses/NotFound"}}}},"/api/providers/compare":{"post":{"operationId":"compareProviders","summary":"Compare two to five providers side by side","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["provider_slugs","address"],"properties":{"provider_slugs":{"type":"array","items":{"type":"string"},"minItems":2,"maxItems":5,"example":["txu-energy","reliant-energy","gexa-energy"]},"address":{"type":"string","example":"77002"}}}}}},"responses":{"200":{"description":"Comparison result","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ComparisonResponse"}}}},"400":{"$ref":"#/components/responses/BadRequest"}}}},"/api/checklist":{"get":{"operationId":"getMoveChecklist","summary":"Get a personalized move-in utility setup checklist","parameters":[{"name":"address","in":"query","required":true,"schema":{"type":"string","example":"77002"}},{"name":"move_date","in":"query","required":false,"description":"ISO date (YYYY-MM-DD)","schema":{"type":"string","format":"date","example":"2026-05-15"}}],"responses":{"200":{"description":"Ordered list of setup tasks","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ChecklistResponse"}}}},"400":{"$ref":"#/components/responses/BadRequest"}}}},"/api/promotions":{"get":{"operationId":"getPromotions","summary":"Current deals, sign-up bonuses, and referral codes","parameters":[{"name":"address","in":"query","required":true,"schema":{"type":"string","example":"77002"}},{"name":"types","in":"query","required":false,"description":"Comma-separated utility types","schema":{"type":"string","example":"electricity"}},{"name":"provider_slugs","in":"query","required":false,"description":"Comma-separated provider slugs to filter to","schema":{"type":"string","example":"txu-energy,reliant-energy"}}],"responses":{"200":{"description":"Promotions array","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PromotionsResponse"}}}},"400":{"$ref":"#/components/responses/BadRequest"}}}}},"components":{"schemas":{"Error":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}}},"Plan":{"type":"object","properties":{"plan_id":{"type":"string"},"plan_name":{"type":"string"},"provider_name":{"type":"string"},"provider_slug":{"type":"string"},"utility_type":{"type":"string","enum":["electricity","gas","internet","water","trash","security"]},"rate":{"type":"number"},"rate_unit":{"type":"string","enum":["per_kwh","per_therm","per_month","per_mbps"]},"estimated_monthly_cost":{"type":"number","nullable":true},"contract_months":{"type":"integer","nullable":true},"early_termination_fee":{"type":"number","nullable":true},"renewable_percentage":{"type":"integer","nullable":true},"features":{"type":"array","items":{"type":"string"}},"fcc_verified":{"type":"boolean"}}},"UtilityGroup":{"type":"object","properties":{"utility_type":{"type":"string"},"display_name":{"type":"string"},"is_deregulated":{"type":"boolean"},"plans":{"type":"array","items":{"$ref":"#/components/schemas/Plan"}}}},"SearchResponse":{"type":"object","properties":{"data":{"type":"object","properties":{"zip_code":{"type":"string"},"supported":{"type":"boolean"},"total_plans":{"type":"integer"},"total_providers":{"type":"integer"},"utility_groups":{"type":"array","items":{"$ref":"#/components/schemas/UtilityGroup"}}}}}},"ProviderDetail":{"type":"object","properties":{"data":{"type":"object","properties":{"slug":{"type":"string"},"name":{"type":"string"},"utility_type":{"type":"string"},"website":{"type":"string","format":"uri","nullable":true},"phone":{"type":"string","nullable":true},"plans":{"type":"array","items":{"$ref":"#/components/schemas/Plan"}}}}}},"ComparisonResponse":{"type":"object","properties":{"data":{"type":"object","properties":{"address":{"type":"string"},"providers":{"type":"array","items":{"type":"object"}}}}}},"ChecklistItem":{"type":"object","properties":{"utility_type":{"type":"string"},"task":{"type":"string"},"days_before_move":{"type":"integer"},"priority":{"type":"string","enum":["critical","high","medium","low"]}}},"ChecklistResponse":{"type":"object","properties":{"data":{"type":"object","properties":{"address":{"type":"string"},"move_date":{"type":"string","format":"date","nullable":true},"items":{"type":"array","items":{"$ref":"#/components/schemas/ChecklistItem"}}}}}},"Promotion":{"type":"object","properties":{"provider_slug":{"type":"string"},"provider_name":{"type":"string"},"title":{"type":"string"},"description":{"type":"string"},"code":{"type":"string","nullable":true},"expires_at":{"type":"string","format":"date-time","nullable":true}}},"PromotionsResponse":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Promotion"}}}}},"responses":{"BadRequest":{"description":"Invalid request parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"NotFound":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}