{"openapi":"3.1.0","info":{"title":"NorCal Repairs API","version":"1.0.0","description":"API for AI agents to discover services, check pricing, find rebates, match contractors, and submit service requests for Northern California home services. Supports HVAC, plumbing, roofing, electrical, fencing, flooring, and painting across 190+ cities.","contact":{"name":"NorCal Repairs","email":"info@norcalrepairs.com","url":"https://norcalrepairs.com"}},"servers":[{"url":"https://norcalrepairs.com","description":"Production"}],"paths":{"/api/catalog":{"get":{"operationId":"getServiceCatalog","summary":"Get full service catalog with pricing, rebates, and contractor info","description":"Returns all services, pricing, applicable rebates, and booking instructions. Filter by vertical, service, city, or section.","parameters":[{"name":"vertical","in":"query","schema":{"type":"string","enum":["hvac","plumbing","roofing","electrical","fencing","flooring","painting","windows","garage-doors","handyman","concrete","junk-removal","cleaning","landscaping","tree-service","water-damage","pest-control"]},"description":"Filter by trade vertical"},{"name":"service","in":"query","schema":{"type":"string"},"description":"Filter by service slug (e.g., ac-repair, fence-installation)"},{"name":"city","in":"query","schema":{"type":"string"},"description":"City slug for coverage check (e.g., sacramento, elk-grove)"},{"name":"section","in":"query","schema":{"type":"string","enum":["services","rebates","contractors","coverage"]},"description":"Return only a specific section of the catalog"}],"responses":{"200":{"description":"Catalog data","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/api/knowledge":{"get":{"operationId":"getKnowledge","summary":"Get structured data about a specific service or city","description":"Returns detailed information about a service (pricing, FAQs, related services, rebates) or a city (county, utility provider, population, nearby cities).","parameters":[{"name":"service","in":"query","schema":{"type":"string"},"description":"Service slug (e.g., ac-repair, heat-pump-installation, fence-installation)"},{"name":"city","in":"query","schema":{"type":"string"},"description":"City slug (e.g., sacramento, roseville, elk-grove)"}],"responses":{"200":{"description":"Structured knowledge data with service details, city info, and rebate information","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/api/match-contractor":{"get":{"operationId":"matchContractor","summary":"Check if an exclusive contractor is available for a vertical/city","description":"Returns the matched exclusive contractor for a given trade and city, including their Google rating, review count, phone number, and whether they handle rebate paperwork.","parameters":[{"name":"vertical","in":"query","required":true,"schema":{"type":"string","enum":["hvac","plumbing","roofing","electrical","fencing","flooring","painting","windows","garage-doors","handyman","concrete","junk-removal","cleaning","landscaping","tree-service","water-damage","pest-control"]},"description":"Trade vertical"},{"name":"city","in":"query","required":true,"schema":{"type":"string"},"description":"City name or slug"}],"responses":{"200":{"description":"Contractor match result","content":{"application/json":{"schema":{"type":"object","properties":{"matched":{"type":"boolean"},"business_name":{"type":"string"},"rating":{"type":"number"},"review_count":{"type":"integer"},"phone":{"type":"string"},"handles_rebates":{"type":"boolean"}}}}}}}}},"/api/contact":{"post":{"operationId":"submitServiceRequest","summary":"Submit a service request (lead) on behalf of a homeowner","description":"Creates a service request and routes it to the exclusive contractor for that territory. Contractor calls homeowner within 2 hours (30 min for emergencies). Contractor handles rebate paperwork if applicable.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["name","phone"],"properties":{"name":{"type":"string","description":"Homeowner's full name"},"phone":{"type":"string","description":"Phone number (10-digit)"},"email":{"type":"string","description":"Email address (optional)"},"service":{"type":"string","description":"Service name or slug"},"vertical":{"type":"string","enum":["hvac","plumbing","roofing","electrical","fencing","flooring","painting","windows","garage-doors","handyman","concrete","junk-removal","cleaning","landscaping","tree-service","water-damage","pest-control"],"description":"Trade vertical"},"city":{"type":"string","description":"City name"},"urgency":{"type":"string","enum":["emergency","this_week","this_month","just_quotes"],"description":"How urgent is the request"},"message":{"type":"string","description":"Additional details about the issue"},"source":{"type":"string","default":"ai_agent","description":"Source identifier (set to 'ai_agent' for agent-submitted requests)"}}}}}},"responses":{"200":{"description":"Service request submitted successfully"},"400":{"description":"Missing required fields"}}}},"/api/a2a":{"post":{"operationId":"a2aEndpoint","summary":"A2A Protocol JSON-RPC 2.0 endpoint","description":"Agent-to-Agent protocol endpoint. Send JSON-RPC 2.0 requests with method 'SendMessage' and natural language or structured skill requests.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["jsonrpc","id","method"],"properties":{"jsonrpc":{"type":"string","const":"2.0"},"id":{"type":"string"},"method":{"type":"string","enum":["SendMessage","GetTask"]},"params":{"type":"object","properties":{"message":{"type":"object","properties":{"role":{"type":"string"},"parts":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string"},"text":{"type":"string"},"data":{"type":"object"}}}}}}}}}}}}},"responses":{"200":{"description":"JSON-RPC 2.0 response with task result"}}}}},"components":{"schemas":{"Service":{"type":"object","properties":{"slug":{"type":"string"},"name":{"type":"string"},"vertical":{"type":"string"},"price_range":{"type":"string"},"emergency_available":{"type":"boolean"},"description":{"type":"string"},"rebates":{"type":"array","items":{"type":"object"}}}},"Rebate":{"type":"object","properties":{"slug":{"type":"string"},"program":{"type":"string"},"provider":{"type":"string"},"savings":{"type":"string"},"status":{"type":"string","enum":["active","ending_soon","expired"]},"contractor_handles_paperwork":{"type":"boolean","default":true},"stackable":{"type":"boolean","default":true}}},"Contractor":{"type":"object","properties":{"business_name":{"type":"string"},"vertical":{"type":"string"},"cities":{"type":"array","items":{"type":"string"}},"handles_rebates":{"type":"boolean","description":"Whether this contractor processes rebate paperwork for homeowners"},"verified":{"type":"boolean"},"plan":{"type":"string","enum":["exclusive_territory","standard"]}}}}}}