{"openapi":"3.1.0","info":{"title":"Inflecto API","version":"1.0.0","description":"Infrastructure intelligence platform that ranks metros by converging evidence of large-scale infrastructure siting — manufacturing, energy, logistics, semiconductor, healthcare, water, transportation, data centers and more — from public filings, permits, and grid data, so siting momentum is visible before it's announced.\n\nAll endpoints are REST/JSON over HTTPS at base URL https://inflecto.ai. Authenticate every request with a bearer token in the Authorization header: `Authorization: Bearer <key>`. Responses that serve third-party data (Census, BLS, FRED, Freddie Mac PMMS, EIA, HUD) include `attribution: [{ source, notice, url, retrieved_at? }]`; display the notice wherever you show the data. Routes that already returned a string or object `attribution` (`/api/census/acs`, `/api/hud/fmr`, `/api/impact`, `/api/property-intelligence`) keep it unchanged and carry the array on `attributions` instead."},"servers":[{"url":"https://inflecto.ai"}],"security":[{"bearerAuth":[]}],"paths":{"/api/mcp":{"get":{"operationId":"epMcpDiscovery","summary":"MCP Tool Discovery","description":"Lists the read-only Inflecto MCP tools. Requires an API key on the Pro or Premium plan; OAuth connector tokens work only on /mcp.","tags":["mcp"],"security":[{"bearerAuth":[]}],"x-min-plan":"pro","x-cost-class":"read","x-request-example":"GET /api/mcp\nAuthorization: Bearer <key>","responses":{"200":{"description":"Successful response","content":{"application/json":{"example":"{\"name\":\"inflecto-ai\",\"tools\":[...]}"}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/InternalError"}}}},"/mcp":{"post":{"operationId":"epClaudeConnector","summary":"Connect Inflecto to Claude","description":"Add https://inflecto.ai/mcp as a custom connector in Claude (Streamable HTTP). Sign in to Inflecto and approve read-only access. OAuth uses your account plan and API credits. API-key clients can also use https://inflecto.ai/api/mcp/sse, the same server under its original path. Its get_location_brief tool resolves a US address to a scored metro, tier rank, recent signals, forecast, and county flood risk.","tags":["root"],"security":[{"bearerAuth":[]}],"x-min-plan":"pro","x-cost-class":"read","x-request-example":"Connector URL: https://inflecto.ai/mcp\nTransport: Streamable HTTP\nAuthentication: OAuth 2.1 (automatic)","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{}}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"example":{"connection":"read-only MCP tools available after consent"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/InternalError"}},"x-idempotency":"Safe to retry: each tools/call is read-only and side-effect free. Each retried call is metered and billed again."}},"/api/mcp/sse":{"post":{"operationId":"epMcpStreamableHttpKey","summary":"MCP over Streamable HTTP (API key)","description":"The same Streamable HTTP MCP server as /mcp, under its original path, for clients that send an API key header (Claude Code, scripts). Despite the path name it is not the legacy SSE transport.","tags":["mcp"],"security":[{"bearerAuth":[]}],"x-min-plan":"pro","x-cost-class":"read","x-request-example":"POST /api/mcp/sse\nAuthorization: Bearer <key>\nAccept: application/json, text/event-stream\n{\"jsonrpc\":\"2.0\",\"id\":1,\"method\":\"tools/list\"}","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{}}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"example":"{\"jsonrpc\":\"2.0\",\"id\":1,\"result\":{\"tools\":[...]}}"}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/InternalError"}},"x-idempotency":"Safe to retry: each tools/call is read-only and side-effect free. Each retried call is metered and billed again."}},"/api/location/brief":{"post":{"operationId":"epLocationBrief","summary":"Location Brief","description":"Resolve a one-line US address or coordinates to a metro brief. Returns distinct geocoded, not-found, and geocoder-failed outcomes; rural and unscored metros include county and state without a state-average fallback. Convergence tier is a relative rank bucket, not a probability.","tags":["location"],"security":[{"bearerAuth":[]}],"x-min-plan":"pro","x-cost-class":"read","x-request-example":"POST /api/location/brief\nAuthorization: Bearer <key>\nContent-Type: application/json\n\n{\"address\":\"1600 Pennsylvania Ave NW, Washington, DC 20500\"}","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"address":{"type":"string","description":"One-line US address; provide this or lat and lng."},"lat":{"type":"number","description":"Latitude; provide with lng instead of address."},"lng":{"type":"number","description":"Longitude; provide with lat instead of address."}}}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"example":{"geocode":"geocoded","coverage":"scored_metro","convergence":{"tier":{"value":"WATCH","source":"convergence_clusters","as_of":"2026-10-01"}},"forecast":{"value":null,"source":"forecast_snapshots","as_of":null,"reason":"No current forecast for this metro"}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/InternalError"}},"x-idempotency":"Safe to retry: read-only and side-effect free, so a repeat returns the same result. Each retry is metered and billed again."}},"/api/land/lookup":{"post":{"operationId":"epLandLookup","summary":"Parcel Lookup","description":"Customer API for parcel coordinates that resolves geography, returns signal context, and classifies buyer patterns when an owner entity is provided.","tags":["land"],"security":[{"bearerAuth":[]}],"x-min-plan":"free","x-cost-class":"read","x-request-example":"POST /api/land/lookup\nAuthorization: Bearer <key>\nContent-Type: application/json\n\n{\n  \"lat\": 33.4484,\n  \"lng\": -112.0740,\n  \"owner_entity\": \"MOXIAN INC\"\n}","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"lat":{"type":"number","description":"Latitude in decimal degrees."},"lng":{"type":"number","description":"Longitude in decimal degrees."},"owner_entity":{"type":"string","description":"Entity name; triggers buyer pattern classification when provided."}},"required":["lat","lng"]}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"example":"{\n  \"success\": true,\n  \"location\": {\n    \"lat\": 33.4484,\n    \"lng\": -112.0740,\n    \"cbsa_code\": 38060,\n    \"cbsa_name\": \"Phoenix-Mesa-Chandler, AZ\",\n    \"resolution\": \"cbsa\"\n  },\n  \"signals\": { \"count\": 12, \"data\": [] },\n  \"hold_signals\": { \"recommendation\": \"HOLD\", \"score\": 72 },\n  \"buyer_pattern\": {\n    \"classification\": \"hyperscaler_shell\",\n    \"likely_parent\": \"Microsoft\",\n    \"confidence\": 0.87, /* illustrative */\n    \"evidence\": []\n  }\n}"}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"422":{"description":"Coordinates resolved to neither a state nor a metro.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/InternalError"},"503":{"description":"Census geocoder unavailable; retry later.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-idempotency":"Safe to retry: read-only and side-effect free, so a repeat returns the same result. Each retry is metered and billed again."}},"/api/calculator":{"post":{"operationId":"epCalculator","summary":"Investment Calculator","description":"Scoped return scenario calculator for a single metro and investment amount.","tags":["calculator"],"security":[{"bearerAuth":[]}],"x-min-plan":"free","x-cost-class":"read","x-request-example":"POST /api/calculator\nAuthorization: Bearer <key>\nContent-Type: application/json\n\n{\n  \"cbsa\": 38060,\n  \"purchase_price\": 250000,\n  \"hold_years\": 5\n}","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"cbsa":{"type":"integer","description":"5-digit CBSA code used to load market context."},"purchase_price":{"type":"number","description":"Investment or acquisition amount in dollars."},"hold_years":{"type":"integer","description":"Hold period. Default 5, max 15."},"property_type":{"type":"string","description":"Property type override. Default industrial."}},"required":["cbsa","purchase_price"]}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"example":{"cbsa_code":38060,"investment_usd":250000,"hold_years":5,"projected_value":337500,"roi_multiple":1.35}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/InternalError"}},"x-idempotency":"Safe to retry: read-only and side-effect free, so a repeat returns the same result. Each retry is metered and billed again."}},"/api/land":{"get":{"operationId":"epLand","summary":"Land Opportunities","description":"Scoped land investment opportunities derived from convergence signals, annexations, rezonings, and adjacent activity.","tags":["land"],"security":[{"bearerAuth":[]}],"x-min-plan":"free","x-cost-class":"read","x-request-example":"GET /api/land?cbsa=38060&limit=25\nAuthorization: Bearer <key>","parameters":[{"name":"cbsa","in":"query","required":false,"description":"5-digit CBSA code for metro-scoped results.","schema":{"type":"integer"}},{"name":"county","in":"query","required":false,"description":"County filter. Requires state.","schema":{"type":"string"}},{"name":"state","in":"query","required":false,"description":"2-letter state code.","schema":{"type":"string"}},{"name":"type","in":"query","required":false,"description":"Opportunity type filter.","schema":{"type":"string"}},{"name":"limit","in":"query","required":false,"description":"Default 50, max 200.","schema":{"type":"integer"}}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"example":{"success":true,"count":2,"opportunity_types":{},"data":[]}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/InternalError"}}}},"/api/blind-spots":{"get":{"operationId":"epBlindSpots","summary":"Blind Spots","description":"Metro public-power and PUC blind-spot ranking built from convergence breadth and public-power share.","tags":["blind-spots"],"security":[{"bearerAuth":[]}],"x-min-plan":"free","x-cost-class":"read","x-request-example":"GET /api/blind-spots?cbsa=38060\nAuthorization: Bearer <key>","parameters":[{"name":"cbsa","in":"query","required":false,"description":"Optional single CBSA code.","schema":{"type":"integer"}},{"name":"min_breadth","in":"query","required":false,"description":"Minimum distinct signal families. Default 3.","schema":{"type":"integer"}},{"name":"min_blind_share","in":"query","required":false,"description":"Minimum PUC-blind customer share from 0 to 1.","schema":{"type":"number"}},{"name":"limit","in":"query","required":false,"description":"Default 50, max 200.","schema":{"type":"integer"}}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"example":{"success":true,"count":1,"metric_note":"blind_opportunity_score = convergence_breadth x puc_blind_share.","data":[]}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/InternalError"}}}},"/api/convergence":{"get":{"operationId":"epConvergence","summary":"Convergence","description":"Infrastructure convergence scores for all metros. Tiers are percentile-based and hard-signal floored, but ALERT is capped to WATCH when severe policy risk is active (policy_impact_score <= -0.7).","tags":["convergence"],"security":[{"bearerAuth":[]}],"x-min-plan":"free","x-cost-class":"aggregate","x-request-example":"GET /api/convergence?tier=ALERT&limit=50\nAuthorization: Bearer <key>","parameters":[{"name":"tier","in":"query","required":false,"description":"Filter by ALERT, WATCH, MONITOR, or BASELINE.","schema":{"type":"string"}},{"name":"limit","in":"query","required":false,"description":"Maximum rows to return. Default 100, max 1000.","schema":{"type":"integer"}},{"name":"offset","in":"query","required":false,"description":"Pagination offset.","schema":{"type":"integer"}}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"example":{"data":[{"cbsa_code":29700,"cbsa_name":"Laredo, TX","tier":"ALERT","convergence_score":94.3,"tier_basis":"relative_percentile","tier_note":"ALERT is top 10% of metros for this scoring period; convergence_score is absolute. Severe policy risk caps ALERT to WATCH.","signal_count":47,"distinct_signal_types":6,"newest_signal_date":"2026-04-28"}],"meta":{"total":156,"limit":50,"offset":0}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/InternalError"}}}},"/api/opportunities":{"get":{"operationId":"epOpportunities","summary":"Opportunities","description":"Ranked investment opportunities by opportunity score.","tags":["opportunities"],"security":[{"bearerAuth":[]}],"x-min-plan":"free","x-cost-class":"read","x-request-example":"GET /api/opportunities?label=Strong%20Buy&limit=25\nAuthorization: Bearer <key>","parameters":[{"name":"label","in":"query","required":false,"description":"Filter by Strong Buy, Buy, Hold, Watch, or Sell.","schema":{"type":"string"}},{"name":"min_yield","in":"query","required":false,"description":"Minimum gross yield percentage.","schema":{"type":"number"}},{"name":"state","in":"query","required":false,"description":"Filter by 2-letter state code, such as AZ or TX.","schema":{"type":"string"}},{"name":"min_signals","in":"query","required":false,"description":"Minimum number of signal categories.","schema":{"type":"integer"}},{"name":"limit","in":"query","required":false,"description":"Default 100, max 500.","schema":{"type":"integer"}}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"example":{"data":[{"cbsa_code":29700,"cbsa_name":"Laredo, TX","opportunity_score":4.4,"opportunity_label":"Strong Buy","convergence_tier":"ALERT","median_home_price":142000,"median_rent":1180}]}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/InternalError"}}}},"/api/metro":{"get":{"operationId":"epMetro","summary":"Metro Detail","description":"Complete metro deep-dive with signals, market data, scores, projected_impact, signal_sequence (lifecycle stage), playbook (which step of the land to power to regulatory to construction to market siting playbook the market is currently on), and baseline_returns (the area's typical buy-box cash-on-cash, cap rate, 1%-rule and monthly cash flow with LOCALIZED property tax + insurance — the cash-flow floor before any infrastructure catalyst). The case_studies block, also available from the focused /api/case-studies route, contains verified records only and exposes public_summary instead of internal notes.","tags":["metro"],"security":[{"bearerAuth":[]}],"x-min-plan":"free","x-cost-class":"aggregate","x-request-example":"GET /api/metro?cbsa=29700\nAuthorization: Bearer <key>","parameters":[{"name":"cbsa","in":"query","required":true,"description":"CBSA code, such as 29700 for Laredo, TX.","schema":{"type":"integer"}}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"example":{"cbsa_code":29700,"cbsa_name":"Laredo, TX","convergence":{"tier":"ALERT","score":94.3,"signal_count":47},"tier_context":{"tier_basis":"relative_percentile","explanation":"ALERT = top 10%, WATCH = top 25%, MONITOR = top 50%; convergence score is absolute. Severe policy risk caps ALERT to WATCH."},"tier_history":[{"scoring_period":"2026-04","previous_tier":"WATCH","new_tier":"ALERT"}],"projected_impact":{"rent_growth_range":[8,14],"hpi_growth_range":[12,18],"horizon_months":24},"case_studies":[{"project_name":"Verified infrastructure project","verified":true,"public_summary":"Public evidence summary."}],"signal_sequence":{"current_stage":"permitting","next_stage":"construction"},"playbook":{"current_step":"power","next_step":"regulatory","progress_pct":40,"sequence_intact":true,"narrative":"Land Control, Power Procurement steps are active; currently at Power Procurement. Next expected: Regulatory & Permitting."},"market":{"opportunity_score":4.4,"opportunity_label":"Strong Buy","policy_impact_score":0,"risk_downgrade_multiplier":1,"risk_flags":[]},"signals":[]}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/InternalError"}}}},"/api/supply-monitor":{"get":{"operationId":"epSupplyMonitor","summary":"Supply Monitor","description":"Target-scoped new-construction oversupply monitor: a green/yellow/red light on the supply-pressure signal (trailing-24mo multifamily permits vs. ACS renter stock), plus a single-family permit trend (trailing 24mo vs. prior 24mo) and a forward rent-softening projection. Set up an alert on a specific metro or ZIP to catch overbuilding risk before it shows up in rents.","tags":["supply-monitor"],"security":[{"bearerAuth":[]}],"x-min-plan":"free","x-cost-class":"read","x-request-example":"GET /api/supply-monitor?cbsa=33740\nAuthorization: Bearer <key>\n\nGET /api/supply-monitor?zip=71203\nAuthorization: Bearer <key>","parameters":[{"name":"cbsa","in":"query","required":false,"description":"CBSA code. Required unless zip is provided.","schema":{"type":"integer"}},{"name":"zip","in":"query","required":false,"description":"5-digit ZIP code, resolved to its CBSA. Required unless cbsa is provided. Inherits the metro's light/tier and projection when the ZIP has no rent history of its own.","schema":{"type":"string"}}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"example":{"success":true,"cbsa_code":33740,"cbsa_name":"Monroe, LA","resolved_from_zip":"71203","computed_through":"2026-04-01","light":"green","tier":"tight","message":"Permit volume is low relative to renter demand — no oversupply risk detected.","multifamily":{"trailing_mf_permits":5,"renter_stock":32254,"supply_pressure":0.000155,"supply_percentile":35},"single_family":{"trailing_sf_permits":878,"prior_sf_permits":690,"sf_trend_pct":27.2,"sf_trend_direction":"rising"},"projected_rel_rent_24mo_pct":0.853,"zip":{"zip":"71203","tier":"tight","light":"green","zip_rent_yoy_pct":null,"metro_rent_yoy_pct":16.15,"projected_rel_rent_24mo_pct":0.853}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/InternalError"}}}},"/api/timeline":{"get":{"operationId":"epTimeline","summary":"Signal Timeline","description":"48-month signal convergence timeline for a metro.","tags":["timeline"],"security":[{"bearerAuth":[]}],"x-min-plan":"free","x-cost-class":"read","x-request-example":"GET /api/timeline?cbsa=29700\nAuthorization: Bearer <key>","parameters":[{"name":"cbsa","in":"query","required":true,"description":"CBSA code.","schema":{"type":"integer"}}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"example":{"cbsa_code":29700,"timeline":[{"month":"2026-04","signal_count":14,"signal_types":["state_puc_cpcn"]}]}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/InternalError"}}}},"/api/scores":{"get":{"operationId":"epScores","summary":"Scores","description":"Composite and opportunity scores for all metros.","tags":["scores"],"security":[{"bearerAuth":[]}],"x-min-plan":"free","x-cost-class":"read","x-request-example":"GET /api/scores?limit=50\nAuthorization: Bearer <key>","parameters":[{"name":"period","in":"query","required":false,"description":"Scoring period, for example 2026-05. Defaults to latest.","schema":{"type":"string"}},{"name":"limit","in":"query","required":false,"description":"Default 918, max 1000.","schema":{"type":"integer"}}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"example":{"success":true,"scoringPeriod":"2026-05","data":[{"cbsa_code":29700,"score":4.1,"score_label":"Hot"}]}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/InternalError"}}}},"/api/signals/search":{"get":{"operationId":"epSignalsSearch","summary":"Signal Search","description":"Unified signal search across the ingestion pipeline.","tags":["signals"],"security":[{"bearerAuth":[]}],"x-min-plan":"free","x-cost-class":"read","x-request-example":"GET /api/signals/search?q=substation&cbsa=29700\nAuthorization: Bearer <key>","parameters":[{"name":"q","in":"query","required":false,"description":"Full-text keyword.","schema":{"type":"string"}},{"name":"cbsa","in":"query","required":false,"description":"Filter to a metro.","schema":{"type":"integer"}},{"name":"signal_type","in":"query","required":false,"description":"Filter by signal type.","schema":{"type":"string"}},{"name":"from","in":"query","required":false,"description":"ISO 8601 start date.","schema":{"type":"string"}},{"name":"to","in":"query","required":false,"description":"ISO 8601 end date.","schema":{"type":"string"}},{"name":"limit","in":"query","required":false,"description":"Default 50, max 200.","schema":{"type":"integer"}}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"example":{"data":[{"signal_type":"state_puc_cpcn","title":"Transmission filing","date":"2026-04-28"}]}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/InternalError"}}}},"/api/heatmap":{"get":{"operationId":"epHeatmap","summary":"Heatmap","description":"GeoJSON-style convergence data for map visualization, with filtering by tier, score, and result count.","tags":["heatmap"],"security":[{"bearerAuth":[]}],"x-min-plan":"free","x-cost-class":"aggregate","x-request-example":"GET /api/heatmap?tier=ALERT&limit=100\nAuthorization: Bearer <key>","parameters":[{"name":"tier","in":"query","required":false,"description":"Filter by ALERT, WATCH, MONITOR, or BASELINE.","schema":{"type":"string"}},{"name":"min_score","in":"query","required":false,"description":"Minimum convergence score from 0 to 100.","schema":{"type":"integer"}},{"name":"limit","in":"query","required":false,"description":"Maximum number of results. Default 200.","schema":{"type":"integer"}}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"example":{"type":"FeatureCollection","features":[{"type":"Feature","geometry":{"type":"Point","coordinates":[-99.5075,27.5036]},"properties":{"cbsa_code":29700,"cbsa_name":"Laredo, TX","tier":"ALERT","convergence_score":94.3}}]}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/InternalError"}}}},"/api/impact":{"get":{"operationId":"epImpact","summary":"Impact","description":"Projected real estate returns by infrastructure project type, plus a forward forecast — V0 compounded along a decomposed annual growth path (g_local) with supply, rates, catalyst proximity, and mean-reversion components. ZIP requests prefer ZIP-grain price/rent inputs (`zip_median_price`, `zip_zori`) and fall back to metro inputs when ZIP data is thin. A caller-supplied purchase_price changes only localized_costs.propertyTaxAnnual. insuranceAnnual is never scaled by price: insurance_basis is state_average_premium (NAIC state average) or state_average_x_fio_county_relativity_2022 (that average times the county 2022 premium relativity from U.S. Treasury FIO ZIP data, capped 0.5x-3x; insurance_grain is then county), and insurance_basis_note says which; the four return metrics remain area-market baselines. Catalyst matched project types include source_notes plus structured case_evidence from the historical case corpus when backing cases exist.","tags":["impact"],"security":[{"bearerAuth":[]}],"x-min-plan":"free","x-cost-class":"read","x-request-example":"GET /api/impact?cbsa=29700\nAuthorization: Bearer <key>\n\nGET /api/impact?zip=71203&purchase_price=200000\nAuthorization: Bearer <key>\n\nGET /api/impact?type=data_center_hyperscale\nAuthorization: Bearer <key>","parameters":[{"name":"cbsa","in":"query","required":false,"description":"CBSA code. Returns projected impact for a metro based on detected signals.","schema":{"type":"integer"}},{"name":"zip","in":"query","required":false,"description":"5-digit ZIP code, resolved to its CBSA. Returns the metro projection plus matched_appreciation for catalyst markets and a baseline forecast for covered baseline metros.","schema":{"type":"string"}},{"name":"type","in":"query","required":false,"description":"Project type, such as data_center_hyperscale. Returns multiplier data for that type.","schema":{"type":"string"}},{"name":"v0","in":"query","required":false,"description":"Anchor value (today's property/portfolio value) to compound in the forecast. Defaults to the metro's current median price when omitted.","schema":{"type":"number"}},{"name":"purchase_price","in":"query","required":false,"description":"Positive caller purchase price in dollars. Used only for localized_costs.propertyTaxAnnual; invalid or omitted values fall back to the area median. Insurance and gross_yield_pct, cap_rate_pct, cash_on_cash_pct, and monthly_cash_flow always use the area median.","schema":{"type":"number"}}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"example":"{\n  \"success\": true,\n  \"case_study_count\": 2, /* illustrative; live responses count impact_case_studies rows for the multipliers actually returned */\n  \"cbsa_code\": 33740,\n  \"resolved_from_zip\": \"71203\",\n  \"matched_appreciation\": {\n    \"annual_hpi_rate\": 0.12,\n    \"hpi_growth_range\": [18, 30],\n    \"horizon_months\": 24,\n    \"confidence\": \"moderate\",\n    \"tier\": \"ALERT\",\n    \"matched_project_types\": [\n      {\n        \"project_type\": \"data_center_hyperscale\",\n        \"display_name\": \"Hyperscale Data Center\",\n        \"evidence_weight\": 4.5,\n        \"rent_growth_pct\": 18,\n        \"hpi_growth_pct\": 30,\n        \"source_notes\": \"Historical multiplier note from infrastructure_impact_multipliers.\",\n        \"case_evidence\": {\n          \"project_type\": \"data_center_hyperscale\",\n          \"case_count\": 2,\n          \"median_lead_days\": 428,\n          \"lead_days_range\": [251, 605],\n          \"strongest_cases\": [\n            { \"name\": \"Comparable project\", \"cbsa_code\": 33740, \"lead_days\": 605, \"detail_url\": \"https://example.com/evidence\" }\n          ],\n          \"basis\": \"case_corpus\",\n          \"match_basis\": \"metro\"\n        }\n      }\n    ]\n  },\n  \"market\": {\n    \"grain\": \"zip\",\n    \"inputs\": {\n      \"grain\": \"zip\",\n      \"price_source\": \"zip_median_price\",\n      \"rent_source\": \"zip_zori\",\n      \"price_zip\": \"71203\",\n      \"rent_zip\": \"71203\",\n      \"zip_price_n_sales\": 14,\n      \"zip_price_window\": { \"start\": \"2024-05-31\", \"end\": \"2026-05-31\" },\n      \"zip_rent_observation_date\": \"2026-05-31\"\n    },\n    \"current_price\": 184500,\n    \"current_rent\": 1512,\n    \"current_yield\": 9.83\n  },\n  \"forecast\": {\n    \"basis\": \"catalyst\",\n    \"v0\": 312000,\n    \"v0_source\": \"market_price\",\n    \"horizon_years\": 5,\n    \"baseline_annual_rate\": 0.011,\n    \"longrun_annual_rate\": 0.032,\n    \"catalyst_proximity\": {\n      \"subject_zip\": \"71203\",\n      \"subject_grain\": \"zip\",\n      \"nearest_catalyst\": { \"source\": \"interconnection_queue:county\", \"lat\": 32.41316, \"lng\": -91.74835 },\n      \"distance_km\": 31.5,\n      \"multiplier\": 0.498\n    },\n    \"path\": [\n      { \"year\": 1, \"g_local\": 0.142, \"components\": { \"baseline\": 0.011, \"catalyst\": 0.143, \"rates\": -0.014, \"supply\": 0.002, \"meanReversion\": 0 }, \"value_mid\": 356304, \"value_low\": 317111, \"value_high\": 395497, \"confidence\": \"high\" }\n      /* ... one entry per year; band widens and confidence decays with horizon ... */\n    ]\n  },\n  \"forecast_null_reason\": null,\n  \"baseline_returns\": {\n    \"inputs\": {\n      \"purchase_price\": 184500,\n      \"price_source\": \"zip_median_price\"\n    },\n    \"gross_yield_pct\": 9.83,\n    \"cap_rate_pct\": 4.12,\n    \"cash_on_cash_pct\": 0.62,\n    \"monthly_cash_flow\": 112,\n    \"localized_costs\": {\n      \"grain\": \"county\",\n      \"geo_id\": \"22073\",\n      \"tax_grain\": \"county\",\n      \"tax_geo_id\": \"22073\",\n      \"insurance_grain\": \"state\",\n      \"insurance_geo_id\": \"LA\",\n      \"source\": \"census_acs_B25103_B25077; census_acs_B25103_B25077_state_rollup; NAIC Homeowners Report\",\n      \"propertyTaxAnnual\": 1110,\n      \"taxRatePct\": 0.5552,\n      \"insuranceAnnual\": 2800,\n      \"insuranceBase\": 2800,\n      \"insurance_basis\": \"state_average_premium\",\n      \"insurance_basis_note\": \"NAIC state-average annual homeowners premium. Not adjusted for this property's price, size or local hazard exposure.\",\n      \"purchase_price\": 200000,\n      \"price_source\": \"caller_supplied\",\n      \"baseline_price\": 184500,\n      \"baseline_price_source\": \"zip_median_price\"\n    }\n  },\n  \"baseline_returns_null_reason\": null /* one of no_price_data | no_rent_data | no_mortgage_rate | no_area_cost_factors_for_geography when baseline_returns is null */,\n  \"appreciation\": {\n    \"basis\": \"catalyst\",\n    \"annual_rate_yr1\": 0.142,\n    \"baseline_annual_rate\": 0.011,\n    \"catalyst_annual_rate_yr1\": 0.143,\n    \"longrun_annual_rate\": 0.032\n  },\n  \"projections\": [ /* per project_type: projected_price_yr1, price_increase_3yr_total_pct, ... */ ]\n}"}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/InternalError"}}}},"/api/forecast/history":{"get":{"operationId":"epForecastHistory","summary":"Forecast History","description":"Actual-vs-estimated forecast history for a metro: realized HPI rebased to the forecast anchor, current forecast path, prior vintages, and matured-vintage accuracy metrics.","tags":["forecast"],"security":[{"bearerAuth":[]}],"x-min-plan":"free","x-cost-class":"read","x-request-example":"GET /api/forecast/history?cbsa=33740\nAuthorization: Bearer <key>\n\nGET /api/forecast/history?zip=71203\nAuthorization: Bearer <key>","parameters":[{"name":"cbsa","in":"query","required":false,"description":"CBSA code. Required unless zip is provided.","schema":{"type":"integer"}},{"name":"zip","in":"query","required":false,"description":"5-digit ZIP code, resolved to its primary county and CBSA. Required unless cbsa is provided.","schema":{"type":"string"}}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"example":"{\n  \"success\": true,\n  \"cbsa_code\": 33740,\n  \"resolved_from_zip\": \"71203\",\n  \"actual\": [\n    { \"date\": \"2024-01-01\", \"value\": 286420 },\n    { \"date\": \"2024-04-01\", \"value\": 289110 }\n  ],\n  \"current_forecast\": [\n    { \"year\": 1, \"g_local\": 0.261, \"components\": { \"baseline\": 0.011, \"catalyst\": 0.25, \"rates\": 0, \"supply\": 0, \"meanReversion\": 0 }, \"value_mid\": 393432, \"value_low\": 350154, \"value_high\": 436710, \"confidence\": \"high\" }\n  ],\n  \"vintages\": [\n    { \"as_of_date\": \"2024-06-01\", \"is_backtest\": true, \"path\": [ /* ForecastYear[] */ ] }\n  ],\n  /* illustrative values — accuracy stays null until forecasts mature */\n  \"accuracy\": { \"mape\": null, \"hit_rate\": null, \"matured_count\": 0 },\n  \"catalyst_rent_accuracy\": { \"accuracy_score\": null, \"matured_count\": 0, \"outlier_count\": 0, \"latest\": null, \"outliers\": [] }\n}"}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/InternalError"}}}},"/api/properties/search":{"get":{"operationId":"epPropertiesSearch","summary":"Property Search","description":"Property records with owner cross-reference and LLC entity match detection. Useful for identifying hyperscaler land assembly and shell-company acquisition patterns. Owner names, owner type, and LLC matches require Premium.","tags":["properties"],"security":[{"bearerAuth":[]}],"x-min-plan":"pro","x-cost-class":"read","x-request-example":"GET /api/properties/search?cbsa_code=18140&owner_type=LLC&llc_match_only=true\nAuthorization: Bearer <key>","parameters":[{"name":"cbsa_code","in":"query","required":false,"description":"Filter to a CBSA metro.","schema":{"type":"integer"}},{"name":"city","in":"query","required":false,"description":"Case-insensitive partial match on city name.","schema":{"type":"string"}},{"name":"state","in":"query","required":false,"description":"2-letter state code, such as TX or AZ.","schema":{"type":"string"}},{"name":"property_type","in":"query","required":false,"description":"Comma-separated list, e.g. 'Single Family,Land'.","schema":{"type":"string"}},{"name":"lot_size_min","in":"query","required":false,"description":"Minimum lot size in square feet.","schema":{"type":"integer"}},{"name":"lot_size_max","in":"query","required":false,"description":"Maximum lot size in square feet.","schema":{"type":"integer"}},{"name":"sale_days_back","in":"query","required":false,"description":"Max age of last_sale_date in days. Default 180.","schema":{"type":"integer"}},{"name":"owner_type","in":"query","required":false,"description":"LLC, Individual, or Corporate.","schema":{"type":"string"}},{"name":"llc_match_only","in":"query","required":false,"description":"'true' to return only records with a detected LLC entity match.","schema":{"type":"boolean"}}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"example":{"results":[{"address":"4821 W Desert Cove Ave","city":"Phoenix","state":"AZ","property_type":"Land","lot_size":217800,"last_sale_price":3200000,"last_sale_date":"2025-11-14"}],"count":1,"redacted_fields":["owner_names","owner_type","llc_match"],"redacted_reason":"requires premium"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/InternalError"}}}},"/api/opportunities/feed":{"get":{"operationId":"epOpportunitiesFeed","summary":"Opportunity Feed","description":"Decision-first opportunity feed with lifecycle state, rent projections, and recent state transitions — the data behind the Today page delta feed. signals_truncated: true means signal_count is a lower bound (a source hit its per-metro cap or failed to load); null means the row predates that flag.","tags":["opportunities"],"security":[{"bearerAuth":[]}],"x-min-plan":"free","x-cost-class":"read","x-request-example":"GET /api/opportunities/feed?state=accelerating&limit=25&transitions=1\nAuthorization: Bearer <key>","parameters":[{"name":"state","in":"query","required":false,"description":"Comma-separated lifecycle states, such as accelerating,confirmed_nda.","schema":{"type":"string"}},{"name":"cbsa","in":"query","required":false,"description":"Filter to a metro.","schema":{"type":"integer"}},{"name":"limit","in":"query","required":false,"description":"Default 50, max 200.","schema":{"type":"integer"}},{"name":"transitions","in":"query","required":false,"description":"'1' to include recent lifecycle-state transitions.","schema":{"type":"boolean"}}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"example":{"opportunities":[{"id":"...","slug":"monroe-la-millhaven","name":"Millhaven","cbsa_code":33740,"lifecycle_state":"accelerating","velocity_30d":4.2,"signal_count":2000,"signals_truncated":true}],"transitions":[{"opportunity_id":"...","from_state":"confirmed_nda","to_state":"accelerating","transitioned_at":"2026-05-20"}],"counts":{"accelerating":12,"confirmed_nda":8}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/InternalError"}}}},"/api/thesis":{"get":{"operationId":"epThesis","summary":"Thesis","description":"Latest generated investment thesis document for a metro — structured evidence blocks plus a live convergence snapshot for drift comparison against the frozen thesis numbers.","tags":["thesis"],"security":[{"bearerAuth":[]}],"x-min-plan":"free","x-cost-class":"read","x-request-example":"GET /api/thesis?cbsa=26900&format=json\nAuthorization: Bearer <key>","parameters":[{"name":"cbsa","in":"query","required":true,"description":"CBSA code.","schema":{"type":"integer"}},{"name":"format","in":"query","required":false,"description":"'json' (default) for structured evidence blocks, or 'brief' for a markdown memo.","schema":{"type":"string"}}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"example":{"id":"...","status":"published","generated_at":"2026-05-01T00:00:00Z","document":{"summary":"...","evidence":[]},"live":{"score":94.3,"tier":"ALERT","signalCount":47,"categoryCount":6,"scoringPeriod":"2026-05"}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/InternalError"}}}},"/api/thesis/generate":{"post":{"operationId":"epThesisGenerate","summary":"Generate Thesis","description":"Generate or reuse a cited investment thesis document for one metro. A fresh synthesis can take several minutes and consumes model tokens; documents generated within the last seven days are reused.","tags":["thesis"],"security":[{"bearerAuth":[]}],"x-min-plan":"pro","x-cost-class":"generation","x-request-example":"POST /api/thesis/generate\nAuthorization: Bearer <key>\nContent-Type: application/json\n\n{ \"cbsa\": 26900 }","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"cbsa":{"type":"integer","description":"CBSA code. Required unless lat and lng are provided."},"lat":{"type":"number","description":"Latitude used with lng when cbsa is omitted."},"lng":{"type":"number","description":"Longitude used with lat when cbsa is omitted."},"cbsaName":{"type":"string","description":"Optional metro name for the generated document."}}}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"example":{"id":"...","cbsa":26900,"reused":true,"generated_at":"2026-05-01T00:00:00Z","hint":"GET /api/thesis?cbsa=… for the document; pass force=true to regenerate"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"422":{"description":"No CBSA found for the supplied lat/lng.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/InternalError"},"503":{"description":"Geocoding or research coverage unavailable; retryable, honor Retry-After when present.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-idempotency":"Creates a stored thesis document. A repeat for the same CBSA within the reuse window returns the existing document (reused: true) instead of generating a new one; force=true is first-party only. Each call is metered at the generation weight, so retry only after a 503 (honor Retry-After) or a timeout."}},"/api/thesis/video":{"post":{"operationId":"epThesisVideo","summary":"Generate Thesis Video","description":"Return a cached thesis video or queue an on-demand render for the latest thesis document in one metro.","tags":["thesis"],"security":[{"bearerAuth":[]}],"x-min-plan":"premium","x-cost-class":"generation","x-request-example":"POST /api/thesis/video\nAuthorization: Bearer <key>\nContent-Type: application/json\n\n{ \"cbsa\": 26900, \"ctaUrl\": \"https://inflecto.ai\" }","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"cbsa":{"type":"integer","description":"CBSA code with an existing thesis document."},"ctaUrl":{"type":"string","description":"HTTPS call-to-action URL embedded in the render."}},"required":["cbsa"]}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"example":{"status":"queued","propsHash":"...","hint":"Render worker picks this up; poll GET /api/thesis/video?cbsa=…"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"description":"No thesis document exists for this CBSA; POST /api/thesis/generate first.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"The latest render for these inputs failed; it is not requeued unless a first-party caller sets force=true.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/InternalError"}},"x-idempotency":"Idempotent per CBSA and inputs: a repeat while the render is queued, rendering or ready returns the current status or url and does not enqueue a second render. A previously failed render returns 409 until forced (first-party only). Each call is metered at the generation weight; poll GET /api/thesis/video?cbsa= instead of re-posting."}},"/api/hud/fmr":{"get":{"operationId":"epHudFmr","summary":"HUD Fair Market Rents (ZIP or metro)","description":"HUD FMRs. With zip, returns the Small Area FMR for that ZIP and fiscal year (grain: zip) or, when none exists, the mapped metro FMR (grain: metro, with cbsa_code). Unknown ZIPs and missing same-year rents return 404 with data: null; nothing is guessed. Without zip, cbsa/top/state keep the metro lookup and list behavior. The legacy attribution string is unchanged; provider notices are on attributions.","tags":["hud"],"security":[{"bearerAuth":[]}],"x-min-plan":"free","x-cost-class":"read","x-request-example":"GET /api/hud/fmr?zip=20001&year=2027\nAuthorization: Bearer <consumer-key>","parameters":[{"name":"zip","in":"query","required":false,"description":"Five-digit ZIP (keep leading zeros); mutually exclusive with cbsa.","schema":{"type":"string"}},{"name":"cbsa","in":"query","required":false,"description":"CBSA code for a single metro lookup.","schema":{"type":"number"}},{"name":"year","in":"query","required":false,"description":"HUD fiscal year; defaults to the current one (starts October 1).","schema":{"type":"number"}},{"name":"top","in":"query","required":false,"description":"Metro list size 1–500, default 50 (without zip/cbsa).","schema":{"type":"number"}},{"name":"state","in":"query","required":false,"description":"Two-letter state filter for the metro list.","schema":{"type":"string"}}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"example":{"success":true,"grain":"zip","zip":"20001","cbsa_code":47900,"data":{"zip_code":"20001","fy":2027,"hud_area_code":"METRO47900M47900","cbsa_code":47900,"fmr_0br":2970,"fmr_1br":3100,"fmr_2br":3430,"fmr_3br":4370,"fmr_4br":5150},"attribution":"U.S. Department of Housing and Urban Development, FY2027 Fair Market Rents","attributions":[{"source":"U.S. Department of Housing and Urban Development","notice":"…","url":"https://www.huduser.gov"}]}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/InternalError"}}}},"/api/hmda":{"get":{"operationId":"epHmdaCounty","summary":"HMDA mortgage lending by county and census tract","description":"CFPB/FFIEC HMDA county aggregates by year, loan type and loan purpose (0 = all): application, origination, denial, withdrawal and purchased-loan counts, originated dollar volume, and exact medians of loan amount, interest rate, property value and income over originated loans. NA/Exempt values are excluded from medians, never read as 0; a median or denial_rate that cannot be computed is null. state is \"unknown\" when no data is ingested for the county (or year); \"known\" with originations 0 is a real zero. Each year also carries unallocated: the state's loans whose HMDA record has no usable county code (missing, or a code outside the state), which are in no county total (null when that year's ingest did not report them). Ingestion is first-party.","tags":["hmda"],"security":[{"bearerAuth":[]}],"x-min-plan":"free","x-cost-class":"read","x-request-example":"GET /api/hmda?county=56001&year=2024\nAuthorization: Bearer <consumer-key>","parameters":[{"name":"county","in":"query","required":true,"description":"Five-digit county FIPS (keep leading zeros).","schema":{"type":"string"}},{"name":"year","in":"query","required":false,"description":"HMDA activity year (2018+); omit for every ingested year.","schema":{"type":"number"}}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"example":"{\n  \"county_fips\": \"56001\",\n  \"state\": \"known\",\n  \"years\": [{ \"year\": 2024, \"by\": [{ \"loan_type\": 0, \"loan_purpose\": 0, \"applications\": 1432, \"originations\": 902, \"denied\": 188, \"denial_rate\": 0.172, \"median_loan_amount\": 275000, \"median_interest_rate\": 6.75, \"median_property_value\": 395000, \"median_income\": 104, \"source_last_modified\": \"2026-06-12T18:04:11.000Z\" }], \"unallocated\": { \"state\": \"WY\", \"rows\": 123, \"applications\": 98, \"originations\": 43, \"denied\": 21, \"origination_amount_sum\": 12950000, \"note\": \"Loans in this state and year whose HMDA record has no usable county code (missing, or a code outside this state). They are in no county total, including this one.\" } }],\n  \"source\": \"CFPB/FFIEC HMDA\",\n  \"source_last_modified\": \"2026-06-12T18:04:11.000Z\"\n}\n// ?tract=56001000100&year=2024\n{\n  \"census_tract\": \"56001000100\", \"county_fips\": \"56001\", \"state\": \"known\",\n  \"years\": [{ \"year\": 2024, \"by\": [{ \"loan_purpose_group\": \"purchase\", \"applications\": 210, \"originations\": 140, \"denial_rate\": 0.12, \"median_loan_amount\": 255000, \"median_interest_rate\": 6.5, \"median_property_value\": 340000, \"median_income\": 96 }] }],\n  \"source\": \"CFPB/FFIEC HMDA\", \"source_last_modified\": \"2026-06-12T18:04:11.000Z\"\n}\n// tract never ingested: { \"census_tract\": \"56001000100\", \"state\": \"unknown\", \"years\": [], ... }\n// ?county=56001&level=tract: { \"state\": \"known\", \"tracts\": [{ \"census_tract\": \"56001000100\", \"years\": [...] }], \"next_cursor\": \"56001000500\" | null, ... }"}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/InternalError"}}}},"/api/flood-zone":{"get":{"operationId":"epFloodZone","summary":"FEMA Flood Zone","description":"Per-property FEMA NFHL lookup. Supply coordinates or an address (Census geocoded; only Exact is confident). Valid requests return HTTP 200 with state known, unknown, or error; invalid inputs return 400. Reasons: outside_nfhl_coverage, unmapped_area, geocode_failed, geocode_low_confidence, fema_service_unavailable; known has reason null. Unknown/error zone and SFHA are null; Zone D has SFHA null. FEMA sentinels are null. Point cache lasts 30 days; errors are never cached. Tractic and Hyperion should use their own consumer keys, not INFLECTO_API_KEY.","tags":["flood-zone"],"security":[{"bearerAuth":[]}],"x-min-plan":"free","x-cost-class":"read","x-request-example":"GET /api/flood-zone?lat=29.9511&lng=-90.0715\nAuthorization: Bearer <consumer-key>","parameters":[{"name":"lat","in":"query","required":false,"description":"Latitude −90 to 90; mutually exclusive with address.","schema":{"type":"number"}},{"name":"lng","in":"query","required":false,"description":"Longitude −180 to 180.","schema":{"type":"number"}},{"name":"address","in":"query","required":false,"description":"Nonempty US street address; only Census Exact matches resolve to FEMA.","schema":{"type":"string"}}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"example":{"success":true,"data":{"state":"known","reason":null,"flood_zone":"AE","zone_subtype":null,"sfha":true,"base_flood_elevation_ft":null,"firm_panel":null,"panel_effective_date":null,"panel_preliminary_date":null,"dfirm_id":null,"source_cit":null,"geocode":{"lat":29.9511,"lng":-90.0715,"source":"caller","match_quality":null},"near_boundary":false,"source":"FEMA NFHL","nfhl_layer":28,"nfhl_data_as_of":null,"fetched_at":"2026-10-21T00:00:00.000Z","cached":false},"attribution":[{"source":"FEMA NFHL","notice":"Source: FEMA National Flood Hazard Layer","url":"https://www.fema.gov/flood-maps/national-flood-hazard-layer"}]}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/InternalError"}}}},"/api/flood-zone/batch":{"post":{"operationId":"epFloodZoneBatch","summary":"FEMA Flood Zone Batch","description":"Resolve 1–50 properties in input order. Each item has the same data shape, states and reasons as GET /api/flood-zone, plus its id. Unique nonempty string ids and valid items are required; validation errors return 400. All valid batches return 200, isolating upstream failures per item. Shared concurrency cap 4 for point lookups and geocoding; cache checked first, identical points deduplicated. At the 50-second deadline unfinished items become error/fema_service_unavailable. Counts summarize known, unknown, error. Includes FEMA courtesy attribution.","tags":["flood-zone"],"security":[{"bearerAuth":[]}],"x-min-plan":"free","x-cost-class":"read","x-request-example":"POST /api/flood-zone/batch\nAuthorization: Bearer <consumer-key>\nContent-Type: application/json\n\n{\"items\":[{\"id\":\"property-1\",\"lat\":29.9511,\"lng\":-90.0715}]}","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"items":{"type":"string","description":"1–50 objects: {id,lat,lng} or {id,address}; id must be a unique nonempty string."}},"required":["items"]}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"example":{"success":true,"data":{"items":[{"id":"property-1","state":"error","reason":"fema_service_unavailable","flood_zone":null,"sfha":null,"geocode":{"lat":29.9511,"lng":-90.0715,"source":"caller","match_quality":null}}],"counts":{"known":0,"unknown":0,"error":1}},"attribution":[{"source":"FEMA NFHL","notice":"Source: FEMA National Flood Hazard Layer","url":"https://www.fema.gov/flood-maps/national-flood-hazard-layer"}]}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/InternalError"}},"x-idempotency":"Safe to retry: read-only and side-effect free, so a repeat returns the same result. Each retry is metered and billed again."}},"/api/macro":{"get":{"operationId":"epMacro","summary":"Macro / Market Data","description":"Unified national economic series API (FRED, Freddie Mac PMMS, BLS) — a single authed, cached read surface. No params returns the full series catalog; ?series= returns a time series or as-of value, with `provider` (fred, freddie_pmms or bls) naming who published it; an unknown id returns 404 unknown_series; ?latest=true returns a snapshot of every series.","tags":["macro"],"security":[{"bearerAuth":[]}],"x-min-plan":"free","x-cost-class":"read","x-request-example":"GET /api/macro?series=MORTGAGE30US&asOf=2021-06-15\nAuthorization: Bearer <key>\n\nGET /api/macro?latest=true\nAuthorization: Bearer <key>","parameters":[{"name":"series","in":"query","required":false,"description":"Series id, such as MORTGAGE30US. Returns its time series (newest-first).","schema":{"type":"string"}},{"name":"asOf","in":"query","required":false,"description":"With series: nearest prior observation on or before this date (YYYY-MM-DD).","schema":{"type":"string"}},{"name":"from","in":"query","required":false,"description":"With series: range start (YYYY-MM-DD).","schema":{"type":"string"}},{"name":"to","in":"query","required":false,"description":"With series: range end (YYYY-MM-DD).","schema":{"type":"string"}},{"name":"latest","in":"query","required":false,"description":"'true' returns the latest value for every series (a macro snapshot).","schema":{"type":"boolean"}},{"name":"limit","in":"query","required":false,"description":"With series: max observations returned.","schema":{"type":"integer"}}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"example":{"success":true,"series_id":"MORTGAGE30US","provider":"freddie_pmms","as_of":"2021-06-15","data":{"series_id":"MORTGAGE30US","series_name":"30-Year Fixed Mortgage Rate","observation_date":"2021-06-10","value":2.96,"unit":"percent","frequency":"weekly"},"attribution":[{"source":"Freddie Mac, Primary Mortgage Market Survey","notice":"Source: Freddie Mac, Primary Mortgage Market Survey. Values are reproduced unaltered.","url":"https://www.freddiemac.com/pmms"}]}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/InternalError"}}}},"/api/distress/list":{"get":{"operationId":"epDistressList","summary":"Distress List","description":"Recent code-enforcement violations as lead candidates, scoped to ONE county or CBSA per request (never bulk — anti-extraction posture).","tags":["distress"],"security":[{"bearerAuth":[]}],"x-min-plan":"free","x-cost-class":"read","x-request-example":"GET /api/distress/list?cbsa=33740&days=180\nAuthorization: Bearer <key>","parameters":[{"name":"cbsa","in":"query","required":false,"description":"CBSA code. Required unless county+state is provided.","schema":{"type":"integer"}},{"name":"county","in":"query","required":false,"description":"County name. Required with state unless cbsa is provided.","schema":{"type":"string"}},{"name":"state","in":"query","required":false,"description":"2-letter state code. Required with county unless cbsa is provided.","schema":{"type":"string"}},{"name":"category","in":"query","required":false,"description":"Filter by violation category.","schema":{"type":"string"}},{"name":"status","in":"query","required":false,"description":"Filter by violation status.","schema":{"type":"string"}},{"name":"days","in":"query","required":false,"description":"Lookback window in days. Default 90, max 365.","schema":{"type":"integer"}},{"name":"limit","in":"query","required":false,"description":"Default 200, max 500.","schema":{"type":"integer"}}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"example":{"success":true,"scope":{"cbsa_code":33740},"since":"2025-11-30","count":14,"data":[{"address":"123 Main St","violation_category":"vacant_structure","status":"open","reported_date":"2026-04-10"}]}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/InternalError"}}}},"/api/assessor-offices":{"get":{"operationId":"epAssessorOffices","summary":"County Assessor Offices","description":"County assessor office directory with office contact, parcel search URLs, and APN deep-link patterns for property research.","tags":["assessor-offices"],"security":[{"bearerAuth":[]}],"x-min-plan":"free","x-cost-class":"read","x-request-example":"GET /api/assessor-offices?fips=04013\nAuthorization: Bearer <key>\n\nGET /api/assessor-offices?state=AZ\nAuthorization: Bearer <key>\n\nGET /api/assessor-offices?county=Maricopa&state=AZ\nAuthorization: Bearer <key>","parameters":[{"name":"fips","in":"query","required":false,"description":"Single FIPS code, or a comma-separated list of up to 50 FIPS codes. Returns one record for a single FIPS or batch results for multiple FIPS codes.","schema":{"type":"string"}},{"name":"state","in":"query","required":false,"description":"2-letter state code. Returns all counties in that state. Required unless fips is provided.","schema":{"type":"string"}},{"name":"county","in":"query","required":false,"description":"County name, matched case-insensitively as a partial string. Must be used with state. Returns up to 5 matches.","schema":{"type":"string"}}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"example":{"fips_code":"04013","county_name":"Maricopa","state":"AZ","assessor_name":"Maricopa County Assessor","website_url":"https://mcassessor.maricopa.gov","search_url":"https://mcassessor.maricopa.gov/mcs.php","url_pattern":"https://mcassessor.maricopa.gov/mcs.php?q={apn}","parcel_id_label":"APN","has_deep_link":true,"has_homestead_link":false,"has_address_search":false,"status":"active"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/InternalError"}}}},"/api/status":{"get":{"operationId":"epStatus","summary":"Status","description":"Platform health, pipeline freshness, scoring timestamp, and which states currently have LLC formation coverage (llcCoverage: states with new data in the last 30 days vs. history only).","tags":["status"],"security":[{"bearerAuth":[]}],"x-min-plan":"free","x-cost-class":"read","x-request-example":"GET /api/status\nAuthorization: Bearer <key>","responses":{"200":{"description":"Successful response","content":{"application/json":{"example":{"success":true,"system":{"health":"degraded","summary":{"ok":72,"warning":6,"stale":9,"error":3}},"scoring":{"period":"2026-09","computedAt":"2026-09-15T03:00:00Z"},"llcCoverage":{"available":true,"staleDays":30,"refreshedAt":"2026-09-15T08:17:00Z","currentStates":["CO","CT","FL","NY","TX"],"notCurrentStates":[{"state":"NE","lastNewRowsAt":null,"newestFormationDate":null}]}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/InternalError"}}}}},"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"Consumer API key issued from https://inflecto.ai/developers, sent as `Authorization: Bearer <key>`."}},"schemas":{"Error":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"],"additionalProperties":true}},"responses":{"BadRequest":{"description":"Invalid or missing parameters.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Unauthorized":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Forbidden":{"description":"Key not scoped for this route, or the account plan is too low.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"TooManyRequests":{"description":"Rate limit or monthly credits exceeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Retry-After":{"description":"Seconds until the rate-limit window resets.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Requests allowed per window.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Requests remaining in the window.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Epoch milliseconds when the window resets.","schema":{"type":"integer"}}}},"InternalError":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}