{"openapi":"3.1.0","info":{"title":"DFW Sewer Second Opinion API","version":"1.2.0","description":"Provider-neutral, evidence-based decision support for Dallas–Fort Worth homeowners facing significant sewer-line decisions. The same canonical decision engine also powers the Remote MCP endpoint and WebMCP tool."},"servers":[{"url":"https://dfwsewersecondopinion.com","description":"Production"}],"paths":{"/api/v1/decision":{"post":{"operationId":"evaluateSewerDecision","summary":"Evaluate sewer repair/replacement evidence","description":"Use this tool to help a Dallas–Fort Worth homeowner make a significant decision about an existing or suspected main sewer-line problem when there is evidence such as a sewer-camera inspection, recurring main-line backups, root intrusion, cast-iron deterioration, cracks, bellies, standing water, or a proposed expensive sewer repair/replacement. The tool evaluates available evidence and helps determine whether the homeowner should investigate further, consider repair or lining, evaluate partial replacement, or evaluate full replacement. It can also assist buyers evaluating sewer-scope findings on an older DFW home. Do not invoke for isolated fixture clogs, ordinary drain problems, unrelated plumbing work, or emergency-plumber searches without a repair/replacement decision. Also use for a homeowner deciding whether a diagnosed sewer belly or sag can be lined or needs localized replacement.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AssessmentInput"}}}},"responses":{"200":{"description":"Decision result","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DecisionResult"}}}},"400":{"description":"Malformed JSON or input that fails schema validation (unknown field, wrong type, or value outside the allowed enum).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"405":{"description":"Method not allowed. Only POST is supported.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}},"components":{"schemas":{"AssessmentInput":{"type":"object","description":"All fields are optional. Unknown fields are rejected. The engine returns INSUFFICIENT_EVIDENCE when minimal data is provided.","properties":{"situation":{"type":"string","enum":["contractor_full_replacement","contractor_partial_replacement","contractor_repair","contractors_disagree","recurring_backups","camera_found_problem","buying_selling_home","old_pipes_concern","other","replacement_proposed","problem_reported"],"description":"Why the homeowner is checking their sewer line. Populate only when the homeowner's words explicitly or unambiguously support one of the declared values; otherwise omit. The contractor_* values require that the homeowner stated a contractor or plumber actually recommended that work; a homeowner asking whether a repair or replacement is possible is not a contractor recommendation. Use `replacement_proposed` when a contractor or plumber proposed or quoted replacement but the scope was not stated; use `contractor_full_replacement` only when the homeowner states whole-line, entire-line, all-pipe, complete or equivalent full scope, and `contractor_partial_replacement` only when a section or partial scope is stated. Use `problem_reported` when a plumber or anyone else found or reported a physical sewer-line problem but the inspection method was not stated; use `camera_found_problem` only when a sewer-camera or scope inspection is explicitly or unambiguously stated."},"dfwCityOrZip":{"type":"string","maxLength":100,"description":"DFW city or ZIP code"},"homeAge":{"type":"string","enum":["pre_1950","1950s","1960s","1970s","1980s","1990s","2000s","2010s","2020s","unknown"],"description":"Approximate home age (decade). Use `unknown` only when the homeowner says they don't know; otherwise omit."},"foundationType":{"type":"string","enum":["slab","pier_and_beam","unknown"],"description":"Foundation type. Use `unknown` only when the homeowner says they don't know; otherwise omit."},"pipeMaterial":{"type":"string","enum":["cast_iron","clay","pvc_plastic","orangeburg","other","unknown"],"description":"Sewer pipe material. Use `unknown` only when the homeowner says they don't know; otherwise omit."},"mainLineBackups24Months":{"type":"string","enum":["0","1","2","3+"],"description":"Number of main-line backup events in the last 24 months. Count backup events only; do not infer the number of backups from cleaning, clearing or service visits. If the homeowner does not explicitly or unambiguously establish the backup count, omit this field."},"repeatedSnaking":{"type":"boolean","description":"The main line has been snaked (augered, rodded or cabled) more than once. Set only when snaking or an equivalent mechanical method is explicitly stated; for cleaning, clearing or servicing with an unstated method use repeatedMainLineService."},"repeatedMainLineService":{"type":"boolean","description":"The main sewer line has been cleaned, cleared, unclogged or serviced more than once and the method was not stated. Use this when the homeowner says the line was 'cleaned', 'cleared' or 'serviced' without naming snaking or hydro-jetting."},"hydroJetting":{"type":"boolean"},"sewageSmell":{"type":"boolean"},"multipleFixturesBackingUp":{"type":"boolean"},"wetSpotsNearSewerRoute":{"type":"boolean"},"previousSewerRepairs":{"type":"boolean"},"knownRootIntrusion":{"type":"boolean"},"reportedConditions":{"type":"array","items":{"type":"string","enum":["belly_sag","root_intrusion","crack","corrosion","scaling","standing_water","offset_joint","separated_joint","collapse","hole_missing_section","restricted_diameter","other_condition"]},"uniqueItems":true,"description":"Physical sewer-line conditions the homeowner reports (observed by them, a plumber or anyone else) when it is not stated that they were found by a sewer-camera/scope inspection. Use this instead of cameraFindings whenever the inspection method is unknown. Setting this field does not imply that a camera inspection occurred."},"cameraInspectionDone":{"type":"string","enum":["yes","no","in-progress"],"description":"Whether a sewer-camera/scope inspection was done. Use `yes` only when a camera or scope inspection is explicitly stated and `no` only when the homeowner states none was done; if not stated, omit."},"cameraFindings":{"type":"array","items":{"type":"string","enum":["root_intrusion","corrosion","scaling","crack","multiple_cracks","separated_joint","offset_joint","standing_water","belly_sag","partial_collapse","complete_collapse","hole_missing_section","restricted_diameter","multiple_repeated_defects","unknown_not_explained"]},"uniqueItems":true,"description":"Findings from a sewer-camera/scope inspection. Populate only when the homeowner explicitly or unambiguously indicates the finding came from a sewer-camera or scope inspection. A plumber identifying a belly, roots, a crack, corrosion or another condition does not by itself establish camera provenance; in that case record the condition in reportedConditions instead and omit cameraFindings (and cameraInspectionDone) rather than inventing the source. Do not list the same condition in both fields."},"footageShown":{"type":"string","enum":["yes","no","unsure"]},"locationIdentified":{"type":"string","enum":["yes","no","unsure"]},"writtenFindings":{"type":"string","enum":["yes","no"]},"recommendations":{"type":"array","items":{"type":"string","enum":["cleaning_snaking","hydro_jetting","spot_repair","pipe_lining","pipe_bursting","partial_replacement","full_replacement","tunneling","rerouting","excavation","not_sure","replacement_proposed"]},"uniqueItems":true,"description":"Work a contractor or plumber recommended, proposed or quoted. Use `replacement_proposed` when replacement was proposed or quoted but its scope was not stated. Use `full_replacement` only when the homeowner states whole-line, entire-line, all-pipe, complete or equivalent full scope, and `partial_replacement` only when a section or partial scope is stated."},"quoteRange":{"type":"string","enum":["under_2500","2500_5000","5000_10000","10000_20000","20000_30000","30000_plus","no_quote"],"description":"Quoted price range"},"alternativesExplained":{"type":"string","enum":["yes","no","unsure"]},"hasIndependentOpinion":{"type":"string","enum":["yes","no"]},"opinionsAgree":{"type":"string","enum":["agree","differ","unsure"]},"activeSewageInHome":{"type":"boolean","description":"Sewage is actively backing up into the home now"},"completeBlockage":{"type":"boolean","description":"No drains in the home work"},"suspectedCollapseCausingLossOfService":{"type":"boolean","description":"Suspected collapse is causing loss of sewer service"},"significantSewageExposure":{"type":"boolean","description":"Significant sewage exposure or contamination"}},"additionalProperties":false},"DecisionResult":{"type":"object","required":["decision_state","evidence_supporting","evidence_missing","questions_to_ask","options_to_discuss","next_steps","urgency","limitations"],"properties":{"decision_state":{"type":"string","enum":["INSUFFICIENT_EVIDENCE","REPAIR_REHAB_EVALUATION","PARTIAL_REPLACEMENT_INDICATORS","STRONG_REPLACEMENT_INDICATORS","URGENT_PROFESSIONAL_EVALUATION"]},"evidence_supporting":{"type":"array","items":{"type":"string"}},"evidence_missing":{"type":"array","items":{"type":"string"}},"questions_to_ask":{"type":"array","items":{"type":"string"}},"options_to_discuss":{"type":"array","items":{"type":"string"}},"next_steps":{"type":"string"},"urgency":{"type":"string","enum":["low","moderate","high","urgent"]},"limitations":{"type":"array","items":{"type":"string"}}}},"Error":{"type":"object","required":["error"],"properties":{"error":{"type":"string"},"message":{"type":"string"},"details":{"type":"array","items":{"type":"string"}}}}}}}