{"openapi":"3.1.0","info":{"title":"Business Change Intelligence API","version":"1.0.0","description":"Temporal, evidence-backed business and location changes for research agents."},"servers":[{"url":"https://api.businesschanges.dev","description":"Canonical production API","x-access-status":"public"}],"paths":{"/v1/events/search":{"post":{"operationId":"business_changes.find_leads","summary":"Find business-change leads","description":"Discover previously unknown businesses and locations by geography, intent, event time, observation time, evidence, and confidence.","x-agent-tool-name":"find_business_change_leads","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"jurisdictions":{"type":"array","items":{"type":"string","examples":["US-FL"]}},"geography":{"type":"object","additionalProperties":false,"properties":{"cities":{"type":"array","items":{"type":"string"}},"counties":{"type":"array","items":{"type":"string"}},"regionCodes":{"type":"array","items":{"type":"string"}},"postalCodes":{"type":"array","items":{"type":"string"}},"near":{"type":"object","required":["latitude","longitude","radiusKm"],"properties":{"latitude":{"type":"number","minimum":-90,"maximum":90},"longitude":{"type":"number","minimum":-180,"maximum":180},"radiusKm":{"type":"number","exclusiveMinimum":0,"maximum":250}}}}},"intents":{"type":"array","items":{"type":"string","enum":["opening_leads","construction_activity","remodels","operator_changes","closure_risk","compliance_activity"]}},"eventTypes":{"type":"array","items":{"type":"string"}},"industries":{"type":"array","items":{"type":"string"}},"effectiveAfter":{"type":"string","format":"date"},"effectiveBefore":{"type":"string","format":"date"},"observedAfter":{"type":"string","format":"date-time"},"minEvidenceStrength":{"type":"string","enum":["weak","moderate","strong","authoritative"],"default":"strong"},"minClassificationConfidence":{"type":"number","minimum":0,"maximum":1,"default":0.75},"projection":{"type":"string","enum":["compact","standard","full"],"default":"compact"},"limit":{"type":"integer","minimum":1,"maximum":100,"default":25},"cursor":{"type":"string"}}},"example":{"jurisdictions":["US-FL"],"geography":{"cities":["Orlando"]},"intents":["opening_leads"],"industries":["restaurant"],"observedAfter":"2026-07-01T00:00:00.000Z","projection":"compact","limit":25}}}},"responses":{"200":{"description":"Successful evidence-backed response"},"400":{"description":"Invalid typed input or cursor"},"402":{"description":"Payment required when x402 is enabled"},"503":{"description":"Database unavailable or not configured"}}}},"/v1/events/evidence":{"post":{"operationId":"business_changes.get_evidence","summary":"Expand primary-source evidence","description":"Expand only selected event IDs into immutable, dated source records with native identifiers and URLs.","x-agent-tool-name":"get_business_event_evidence","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["eventIds"],"properties":{"eventIds":{"type":"array","minItems":1,"maxItems":50,"items":{"type":"string","format":"uuid"}}}},"example":{"eventIds":["<event UUID 1>","<event UUID 2>","<event UUID 3>"]}}}},"responses":{"200":{"description":"Successful evidence-backed response"},"400":{"description":"Invalid typed input or cursor"},"402":{"description":"Payment required when x402 is enabled"},"503":{"description":"Database unavailable or not configured"}}}},"/v1/locations/timeline":{"post":{"operationId":"business_changes.location_timeline","summary":"Research a location timeline","description":"Retrieve chronological business changes for an exact premises or an explicitly requested parent building.","x-agent-tool-name":"get_location_timeline","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"locationId":{"type":"string","format":"uuid"},"address":{"type":"string"},"city":{"type":"string"},"regionCode":{"type":"string"},"matchScope":{"type":"string","enum":["exact_premise","building"],"default":"exact_premise"},"limit":{"type":"integer","minimum":1,"maximum":100,"default":50},"cursor":{"type":"string"}}},"example":{"address":"5959 Lake Nona Blvd Ste 115","city":"Orlando","regionCode":"FL"}}}},"responses":{"200":{"description":"Successful evidence-backed response"},"400":{"description":"Invalid typed input or cursor"},"402":{"description":"Payment required when x402 is enabled"},"503":{"description":"Database unavailable or not configured"}}}},"/v1/changes":{"post":{"operationId":"business_changes.changes_since","summary":"Poll newly observed changes","description":"Consume a stable observed-time delta feed, including corrections, supersessions, and retractions.","x-agent-tool-name":"get_changes_since","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"cursor":{"type":"string"},"observedAfter":{"type":"string","format":"date-time"},"jurisdictions":{"type":"array","items":{"type":"string"}},"intents":{"type":"array","items":{"type":"string","enum":["opening_leads","construction_activity","remodels","operator_changes","closure_risk","compliance_activity"]}},"minEvidenceStrength":{"type":"string","enum":["weak","moderate","strong","authoritative"],"default":"strong"},"minClassificationConfidence":{"type":"number","minimum":0,"maximum":1,"default":0.75},"projection":{"type":"string","enum":["compact","standard","full"],"default":"compact"},"limit":{"type":"integer","minimum":1,"maximum":100,"default":50}}},"example":{"cursor":"<cursor from prior response>","limit":50}}}},"responses":{"200":{"description":"Successful evidence-backed response"},"400":{"description":"Invalid typed input or cursor"},"402":{"description":"Payment required when x402 is enabled"},"503":{"description":"Database unavailable or not configured"}}}},"/v1/coverage":{"post":{"operationId":"business_changes.coverage","summary":"Inspect source coverage","description":"Check supported sources, jurisdictions, collection windows, freshness, failures, and limitations before interpreting results.","x-agent-tool-name":"get_business_change_coverage","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"jurisdictions":{"type":"array","items":{"type":"string"}},"sourceSlugs":{"type":"array","items":{"type":"string"}},"includeInactive":{"type":"boolean","default":false}}},"example":{"jurisdictions":["US-FL"]}}}},"responses":{"200":{"description":"Successful evidence-backed response"},"400":{"description":"Invalid typed input or cursor"},"402":{"description":"Payment required when x402 is enabled"},"503":{"description":"Database unavailable or not configured"}}}}}}