{"openapi":"3.1.0","info":{"title":"UtilityDataUSA public evidence API","version":"0.6.0","description":"Read-only public-source context. Per-source error/no_data/limited states are significant; no excavation clearance or confirmed utility service is provided."},"servers":[{"url":"/"}],"paths":{"/api/webmcp/address-profile":{"get":{"operationId":"getAddressProfile","parameters":[{"name":"q","in":"query","required":true,"schema":{"type":"string","minLength":3,"maxLength":250},"description":"U.S. address including city, state and ZIP."},{"name":"refresh","in":"query","schema":{"type":"string","enum":["1"]},"description":"Explicitly refresh all sources; separately limited to three requests per minute per instance/IP."}],"responses":{"200":{"description":"Address profile or no Census match. Check source statuses, sourceFreshness timestamps and persistence.status. Successful public evidence may be saved for 30 days."},"400":{"description":"Invalid query"},"429":{"description":"Request limit"},"502":{"description":"Address service unavailable"}}}},"/api/saved-profile":{"post":{"operationId":"readSavedProfile","description":"Read an immutable public-evidence snapshot using its unguessable sharing token. No new upstream or AI calls. The token is passed in the body to keep it out of request URLs.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["token"],"properties":{"token":{"type":"string","pattern":"^[a-f0-9]{64}$"}}}}}},"responses":{"200":{"description":"Historical snapshot, with original source timestamps"},"404":{"description":"Unknown or expired report"},"503":{"description":"Snapshot storage unavailable"}}}},"/api/webmcp/address-search":{"get":{"operationId":"findAddress","parameters":[{"name":"q","in":"query","required":true,"schema":{"type":"string","minLength":3,"maxLength":250},"description":"U.S. address including city, state and ZIP."}],"responses":{"200":{"description":"Census address candidates"},"400":{"description":"Invalid query"},"429":{"description":"Request limit"},"502":{"description":"Census unavailable"}}}},"/api/sources":{"get":{"operationId":"listSources","responses":{"200":{"description":"Deployed source capabilities; not a real-time health check"}}}}}}