{"openapi":"3.0.3","info":{"title":"Texas Homebuyer Money Finder API","version":"1.0.0","description":"Public, no-authentication API for structured Texas homebuyer-assistance decision support. The matching engine returns POSSIBLE program matches only — never a qualification, eligibility, or approval decision. It does not pull credit, does not require a Social Security number, and does not provide legal or financial advice. Always verify details with the official program source.","contact":{"name":"Texas Homebuyer Money Finder","url":"https://homemoneyfinder.com/decision-tools"}},"servers":[{"url":"https://homemoneyfinder.com"}],"tags":[{"name":"Matching","description":"The canonical homebuyer-assistance matching engine."},{"name":"Programs","description":"Browse the program library."},{"name":"Sources","description":"Official source references."},{"name":"Analytics","description":"Aggregate agent-access counts."}],"paths":{"/api/v1/match":{"post":{"tags":["Matching"],"summary":"Find possible homebuyer-assistance program matches","description":"The canonical matching engine used by every interface (web, REST, remote MCP, in-browser WebMCP). Accepts a buyer profile and returns possible program matches with what each offers, why it matched, items to verify, and official source links.","operationId":"findHomebuyerOptions","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"answers":{"type":"object","description":"Prospective buyer profile. All fields are optional; more detail yields more precise possible matches. No credit is pulled and no Social Security number is used.","properties":{"city":{"type":"string","example":"Dallas"},"county":{"type":"string","example":"Dallas"},"householdSize":{"type":"integer","minimum":1,"example":3},"incomeRange":{"type":"string","enum":["under_40k","40k_60k","60k_80k","80k_100k","100k_120k","120k_140k","over_140k"]},"firstTimeBuyer":{"type":"string","enum":["yes","no","not_sure"]},"needDownPayment":{"type":"string","enum":["down_payment","closing_costs","both","not_sure"]},"veteranStatus":{"type":"string","enum":["none","veteran","active_duty","national_guard","surviving_spouse"]},"occupation":{"type":"string","enum":["none","teacher","nurse","first_responder","corrections","other_public","other"]},"ruralOpen":{"type":"string","enum":["yes","no","maybe"]},"creditRange":{"type":"string","enum":["below_580","580_619","620_639","640_679","680_plus"]},"priceRange":{"type":"string","enum":["under_200k","200k_300k","300k_400k","400k_500k","over_500k"]},"completedEducation":{"type":"string","enum":["yes","no","started"]}},"additionalProperties":true}},"required":["answers"]}}}},"responses":{"200":{"description":"Possible matches.","content":{"application/json":{"schema":{"type":"object","properties":{"assessmentId":{"type":"string"},"resultCount":{"type":"integer"},"results":{"type":"array","items":{"type":"object","properties":{"programId":{"type":"string","example":"TX-ST-002"},"programName":{"type":"string"},"matchCategory":{"type":"string","description":"e.g. strong_possible_match, possible_match, veteran_pathway, needs_lender_review."},"whyMatched":{"type":"string","description":"Why this program appeared as a possible match."},"whatOffered":{"type":"string","description":"What the program may offer (assistance type, amount, structure)."},"verifyChecklist":{"type":"array","items":{"type":"string"}},"nextStep":{"type":"string"},"officialUrl":{"type":"string","nullable":true},"applicationUrl":{"type":"string","nullable":true},"lastVerified":{"type":"string","nullable":true}}}},"disclaimer":{"type":"string"}}}}}},"400":{"description":"Invalid request body (malformed JSON or missing answers object).","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}}}}}},"500":{"description":"Failed to process assessment.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}}}}}}}}},"/api/v1/programs":{"get":{"tags":["Programs"],"summary":"List / filter the program library","operationId":"listPrograms","parameters":[{"name":"city","in":"query","schema":{"type":"string"},"description":"Filter to programs serving this city (statewide always included)."},{"name":"county","in":"query","schema":{"type":"string"},"description":"Filter to programs serving this county (statewide always included)."},{"name":"assistance_type","in":"query","schema":{"type":"string"},"description":"Filter by assistance-type keyword."},{"name":"filter","in":"query","schema":{"type":"string","enum":["down_payment","closing_cost","statewide","local","veteran","profession","rural","education"]}},{"name":"status","in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"Matching programs.","content":{"application/json":{"schema":{"type":"object","properties":{"programs":{"type":"array","items":{"type":"object"}},"count":{"type":"integer"}}}}}}}}},"/api/v1/programs/{id}":{"get":{"tags":["Programs"],"summary":"Get a single program by ID","operationId":"getProgram","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"example":"TX-ST-002"}],"responses":{"200":{"description":"The program record.","content":{"application/json":{"schema":{"type":"object","properties":{"program":{"type":"object"}}}}}},"404":{"description":"Program not found."}}}},"/api/v1/sources":{"get":{"tags":["Sources"],"summary":"List official source references","operationId":"listSources","responses":{"200":{"description":"Sources.","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/api/results/{id}":{"get":{"tags":["Matching"],"summary":"Retrieve saved assessment results by assessment ID","operationId":"getResults","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Saved results.","content":{"application/json":{"schema":{"type":"object","properties":{"results":{"type":"array","items":{"type":"object"}}}}}}},"404":{"description":"Assessment not found."}}}},"/api/v1/analytics":{"get":{"tags":["Analytics"],"summary":"Aggregate agent-access counts","description":"Aggregate-only counts of how the agent-access channels have been used. No personal data.","operationId":"getAnalytics","responses":{"200":{"description":"Aggregate counts.","content":{"application/json":{"schema":{"type":"object","properties":{"total":{"type":"integer"},"byInterface":{"type":"object"},"note":{"type":"string"}}}}}}}}},"/api/webmcp":{"get":{"tags":["Matching"],"summary":"Remote MCP descriptor","description":"Returns the Model Context Protocol tool descriptor. POST accepts JSON-RPC 2.0 initialize, tools/list, and tools/call.","operationId":"mcpDescriptor","responses":{"200":{"description":"MCP descriptor.","content":{"application/json":{"schema":{"type":"object"}}}}}}}}}