{"openapi":"3.1.0","info":{"title":"Breesy Restoration Connect API","version":"1.0.0","description":"API-first restoration intake for AI agents and approved automated clients."},"servers":[{"url":"https://breesy-connect.com","description":"Production"}],"tags":[{"name":"Restoration Requests","description":"Submit home damage help requests for water, flooding, fire, mold, storm, and other property damage."},{"name":"Discovery","description":"Machine-readable metadata for AI agents."}],"paths":{"/api/requests":{"post":{"tags":["Restoration Requests"],"operationId":"submitRestorationRequest","summary":"Submit a restoration help request","description":"Submit a customer-authorized restoration request as JSON. Use an Idempotency-Key header or idempotencyKey body field when retrying the same customer request.","parameters":[{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","maxLength":200},"description":"Stable retry key for the same customer request. The idempotencyKey request body field is also supported."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RestorationRequest"},"example":{"urgency":"urgent","serviceType":"Water damage mitigation","serviceLocation":"123 Main St, Denver, CO 80202","city":"Denver","state":"CO","postalCode":"80202","propertyType":"residential","details":"Customer has active water intrusion from a burst supply line. Two rooms affected and water is still spreading.","callbackPhone":"+13035550123","customerName":"Jordan Smith","email":"jordan@example.com","agent":{"name":"Example Personal AI","identifier":"example-agent","contact":"agent-ops@example.com"},"idempotencyKey":"example-agent-unique-request-id"}}}},"responses":{"200":{"description":"Request accepted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AcceptedResponse"}}}},"400":{"description":"Validation failed or the request was blocked","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"413":{"description":"Payload too large","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"415":{"description":"Unsupported content type","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limited","headers":{"Retry-After":{"schema":{"type":"string"},"description":"Seconds until the rate limit resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Intake storage unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/agent-info":{"get":{"tags":["Discovery"],"operationId":"getAgentInfo","summary":"Get agent integration metadata","responses":{"200":{"description":"Agent integration metadata","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentInfo"}}}}}}},"/.well-known/restoration-intake":{"get":{"tags":["Discovery"],"operationId":"getWellKnownRestorationIntake","summary":"Get well-known restoration intake metadata","responses":{"200":{"description":"Versioned restoration intake metadata","content":{"application/json":{"schema":{"allOf":[{"type":"object","required":["version"],"properties":{"version":{"type":"string","example":"1.0"}}},{"$ref":"#/components/schemas/AgentInfo"}]}}}}}}},"/llms.txt":{"get":{"tags":["Discovery"],"operationId":"getLlmsTxt","summary":"Get plain-text AI agent instructions","responses":{"200":{"description":"Plain-text AI agent instructions","content":{"text/plain":{"schema":{"type":"string"}}}}}}}},"components":{"schemas":{"RestorationRequest":{"type":"object","additionalProperties":false,"required":["urgency","serviceType","serviceLocation","state","details","callbackPhone"],"properties":{"urgency":{"type":"string","enum":["urgent","non_urgent"],"description":"Use urgent for active water, fire, unsafe conditions, or immediate property risk."},"serviceType":{"type":"string","minLength":3,"maxLength":160,"examples":["Emergency water extraction","Structural drying and dehumidification","Burst pipe and appliance leak cleanup","Flood damage mitigation","Moisture mapping and monitoring","Sewage and contaminated water cleanup"],"description":"One restoration or construction service requested by the customer."},"serviceLocation":{"type":"string","minLength":5,"maxLength":500,"description":"Street address or serviceable location description."},"city":{"type":"string","maxLength":120},"state":{"type":"string","enum":["AL","AK","AZ","AR","CA","CO","CT","DE","FL","GA","HI","ID","IL","IN","IA","KS","KY","LA","ME","MD","MA","MI","MN","MS","MO","MT","NE","NV","NH","NJ","NM","NY","NC","ND","OH","OK","OR","PA","RI","SC","SD","TN","TX","UT","VT","VA","WA","WV","WI","WY"],"description":"Two-letter US state code."},"postalCode":{"type":"string","maxLength":20},"propertyType":{"type":"string","maxLength":80},"propertyArea":{"type":"string","maxLength":120},"damageSource":{"type":"string","maxLength":160},"damageType":{"type":"string","maxLength":160},"severity":{"type":"string","maxLength":80},"affectedItems":{"type":"array","maxItems":30,"items":{"type":"string","minLength":1,"maxLength":120}},"incidentDate":{"type":"string","maxLength":30},"details":{"type":"string","minLength":20,"maxLength":4000,"description":"Plain-language description of the loss and what the customer needs."},"callbackPhone":{"type":"string","minLength":7,"maxLength":30,"pattern":"^[+()\\d\\s.-]+$","description":"Phone number where the customer can be reached."},"customerName":{"type":"string","maxLength":160},"email":{"type":"string","format":"email","maxLength":320},"consentToContact":{"type":"boolean","default":true,"description":"True when the customer has authorized contact about the restoration request."},"referralSource":{"type":"string","maxLength":160},"source":{"type":"string","maxLength":80,"default":"api"},"idempotencyKey":{"type":"string","maxLength":200},"agent":{"type":"object","additionalProperties":false,"properties":{"name":{"type":"string","maxLength":120,"description":"Human-readable AI agent name."},"identifier":{"type":"string","maxLength":160,"description":"Stable agent or application identifier."},"contact":{"type":"string","maxLength":320,"description":"Support or audit contact for the submitting agent."}}}}},"AcceptedResponse":{"type":"object","required":["accepted","duplicate","requestId","message","urgent","responseCommitment"],"properties":{"accepted":{"type":"boolean","const":true},"duplicate":{"type":"boolean"},"requestId":{"type":"string"},"message":{"type":"string"},"urgent":{"type":"boolean"},"responseCommitment":{"oneOf":[{"type":"object","required":["contactWithinMinutes","timeToSiteMinutes"],"properties":{"contactWithinMinutes":{"type":"integer","example":10},"timeToSiteMinutes":{"type":"integer","example":60}}},{"type":"object","required":["contactWithinHours","scheduledOnSiteWithinHours"],"properties":{"contactWithinHours":{"type":"integer","example":24},"scheduledOnSiteWithinHours":{"type":"integer","example":24}}}]}}},"ErrorResponse":{"type":"object","required":["accepted","error","message"],"properties":{"accepted":{"type":"boolean","const":false},"error":{"type":"string"},"message":{"type":"string"},"issues":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}}}}},"AgentInfo":{"type":"object","description":"Fast help for water, flooding, fire, mold, storm, and other property damage across all 50 US states.","additionalProperties":true}}}}