{"openapi":"3.1.0","info":{"title":"CasaCaddy Connections API","version":"1.0.0","description":"Pro-only delegation from the CasaCaddy iPhone app. Two operations on inputs you supply; no access to the on-device home library, task history, device identity or billing.","termsOfService":"https://casacaddy.com/terms"},"servers":[{"url":"https://api.casacaddy.com"}],"externalDocs":{"url":"https://api.casacaddy.com/developers"},"components":{"securitySchemes":{"ConnectionKey":{"type":"apiKey","in":"header","name":"x-api-key","description":"Expiring cck_ delegation key created in native Settings → Connected tools. Never use the native device JWT."}}},"paths":{"/api/guide":{"post":{"operationId":"generateMaintenanceGuide","description":"Generate a maintenance guide for supplied appliance details and question. Preserve all safetyWarnings, step cautions, whenToCallPro and call_a_pro difficulty. Shares the same installation’s Pro quota; exact cached requests are unmetered.","x-required-scope":"guides:generate","security":[{"ConnectionKey":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"item":{"type":"object","properties":{"category":{"type":"string","enum":["furnace","boiler","heat_pump","ac_condenser","mini_split","water_heater_tank","water_heater_tankless","water_softener","refrigerator","dishwasher","washer","dryer","range_oven","microwave","garbage_disposal","sump_pump","garage_door_opener","smoke_co_detector","thermostat","roof","gutter","deck","siding","window","other"]},"brand":{"type":"string","maxLength":120},"model":{"type":"string","maxLength":120},"specs":{"type":"object","propertyNames":{"type":"string","maxLength":60},"additionalProperties":{"type":"string","maxLength":200}}},"required":["category"],"additionalProperties":false},"question":{"type":"string","maxLength":300}},"required":["item"],"additionalProperties":false}}}},"responses":{"200":{"description":"Result with shared quota and cache status.","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"guide":{"type":"object","properties":{"title":{"type":"string"},"difficulty":{"type":"string","enum":["easy","moderate","call_a_pro"]},"estMinutes":{"default":30,"type":"integer","minimum":1,"maximum":1440},"tools":{"default":[],"type":"array","items":{"type":"string"}},"parts":{"default":[],"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"spec":{"type":"string"},"exampleSearch":{"type":"string"}},"required":["name","spec","exampleSearch"],"additionalProperties":false}},"steps":{"type":"array","items":{"type":"object","properties":{"n":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"text":{"type":"string"},"caution":{"type":"string"}},"required":["n","text"],"additionalProperties":false}},"whenToCallPro":{"default":[],"type":"array","items":{"type":"string"}},"safetyWarnings":{"default":[],"type":"array","items":{"type":"string"}}},"required":["title","difficulty","estMinutes","tools","parts","steps","whenToCallPro","safetyWarnings"],"additionalProperties":false},"cached":{"type":"boolean"},"quota":{"type":"object","properties":{"used":{"type":"number"},"limit":{"type":"number"}},"required":["used","limit"],"additionalProperties":false}},"required":["guide","cached","quota"],"additionalProperties":false}}}},"400":{"description":"Invalid request or image."},"401":{"description":"Invalid, expired, revoked or insufficiently scoped key."},"402":{"description":"The owning installation no longer has active server-verified Pro."},"403":{"description":"Action unavailable to connections."},"413":{"description":"Request or image too large."},"422":{"description":"Recognition confidence is low; partial fields require user confirmation."},"429":{"description":"Shared device quota or per-key transport limit reached. Transport limits return Retry-After:60."},"502":{"description":"Guide or recognition provider unavailable."},"503":{"description":"Global budget, kill switch, or connection service unavailable."}}}},"/api/recognize":{"post":{"operationId":"recognizeAppliance","description":"Analyze appliance and optional model-plate photos chosen by the user. The result may include serial/model numbers. Ask the user to confirm recognition before acting. Photos reach the existing model pipeline; this does not read the local photo library. Shares installation Pro quota. A cached recognition requires the same installation, both supplied photos and exact hint; changed inputs require a fresh allowance.","x-required-scope":"recognition:analyze","security":[{"ConnectionKey":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"imageBase64":{"type":"string","minLength":64},"imageBase64Plate":{"type":"string","minLength":64},"hint":{"type":"string","maxLength":200}},"required":["imageBase64"],"additionalProperties":false}}}},"responses":{"200":{"description":"Result with shared quota and cache status.","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"category":{"default":"other","type":"string","enum":["furnace","boiler","heat_pump","ac_condenser","mini_split","water_heater_tank","water_heater_tankless","water_softener","refrigerator","dishwasher","washer","dryer","range_oven","microwave","garbage_disposal","sump_pump","garage_door_opener","smoke_co_detector","thermostat","roof","gutter","deck","siding","window","other"]},"name":{"default":"Unknown item","type":"string"},"brand":{"default":null,"anyOf":[{"type":"string"},{"type":"null"}]},"model":{"default":null,"anyOf":[{"type":"string"},{"type":"null"}]},"serial":{"default":null,"anyOf":[{"type":"string"},{"type":"null"}]},"confidence":{"default":0,"type":"number","minimum":0,"maximum":1},"specs":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{"type":"string"}},"ageEstimate":{"default":{"year":null,"source":null},"type":"object","properties":{"year":{"default":null,"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"source":{"default":null,"anyOf":[{"type":"string","enum":["serial","plate","visual"]},{"type":"null"}]}},"required":["year","source"],"additionalProperties":false},"suggested_tasks":{"type":"array","items":{"type":"object","properties":{"templateId":{"anyOf":[{"type":"string"},{"type":"null"}]},"title":{"type":"string"},"rrule":{"type":"string"},"season":{"anyOf":[{"type":"string","enum":["spring","summer","fall","winter"]},{"type":"null"}]},"difficulty":{"anyOf":[{"type":"number","const":1},{"type":"number","const":2},{"type":"number","const":3}]}},"required":["templateId","title","rrule","season","difficulty"],"additionalProperties":false}},"cached":{"type":"boolean"},"quota":{"type":"object","properties":{"used":{"type":"number"},"limit":{"type":"number"}},"required":["used","limit"],"additionalProperties":false}},"required":["category","name","brand","model","serial","confidence","specs","ageEstimate","suggested_tasks","cached","quota"],"additionalProperties":false}}}},"400":{"description":"Invalid request or image."},"401":{"description":"Invalid, expired, revoked or insufficiently scoped key."},"402":{"description":"The owning installation no longer has active server-verified Pro."},"403":{"description":"Action unavailable to connections."},"413":{"description":"Request or image too large."},"422":{"description":"Recognition confidence is low; partial fields require user confirmation."},"429":{"description":"Shared device quota or per-key transport limit reached. Transport limits return Retry-After:60."},"502":{"description":"Guide or recognition provider unavailable."},"503":{"description":"Global budget, kill switch, or connection service unavailable."}}}}}}