{"openapi":"3.1.0","info":{"title":"EventHorizon IQ API","version":"1.0.0","description":"Cross-asset regime intelligence API. 49+ sensors, TIQ-ML scoring, signal drops, structural dislocation detection, and agent proposals. Sentiment is downstream. Structure leads.","contact":{"name":"EHIQ Support","email":"dr.eric.jackson@gmail.com","url":"https://eventhorizoniq.com"},"termsOfService":"https://eventhorizoniq.com/terms"},"servers":[{"url":"https://eventhorizoniq.com","description":"Production"}],"security":[{},{"apiKey":[]}],"paths":{"/api/health":{"get":{"operationId":"getHealth","summary":"Health check","description":"Returns system health status and sensor freshness counts. No authentication required.","tags":["System"],"security":[],"responses":{"200":{"description":"System healthy","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HealthResponse"}}}},"503":{"description":"System unhealthy","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HealthResponse"}}}}}}},"/api/sensors":{"get":{"operationId":"listSensors","summary":"List sensors with sparkline data","description":"Returns all free-tier sensors with 7-day sparkline history. No authentication required. Authenticated users see the same list; individual sensor detail and history endpoints expose paid-tier sensors.","tags":["Sensors"],"security":[],"responses":{"200":{"description":"Sensor list with sparklines","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SensorListResponse"}}}},"500":{"description":"Server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/sensors/{id}":{"get":{"operationId":"getSensor","summary":"Get sensor detail","description":"Returns full detail for a single sensor including methodology, interpretation, outcomes, sources, and latest reading. Free-tier sensors are accessible without a key. Paid-tier sensors require authentication. Some metadata fields are stripped for free-tier access.","tags":["Sensors"],"parameters":[{"name":"id","in":"path","required":true,"description":"Sensor ID (e.g., `btc-cycle-composite`, `funding-rate-stress`)","schema":{"type":"string"}}],"responses":{"200":{"description":"Sensor detail","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SensorDetailResponse"}}}},"403":{"description":"Paid access required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpgradeRequired"}}}},"404":{"description":"Sensor not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitError"}}}},"500":{"description":"Server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/sensors/{id}/history":{"get":{"operationId":"getSensorHistory","summary":"Get sensor reading history","description":"Returns historical readings for a sensor. Row limits are tier-gated: free=200, retail=1000, institutional=10000. Authenticated users receive `confidence` and `metadata` fields on each reading; free-tier users do not.","tags":["Sensors"],"parameters":[{"name":"id","in":"path","required":true,"description":"Sensor ID","schema":{"type":"string"}},{"name":"limit","in":"query","required":false,"description":"Number of readings to return (capped by tier max)","schema":{"type":"integer","default":200,"minimum":1,"maximum":10000}},{"name":"offset","in":"query","required":false,"description":"Pagination offset","schema":{"type":"integer","default":0,"minimum":0}}],"responses":{"200":{"description":"Sensor history","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SensorHistoryResponse"}}}},"403":{"description":"Paid access required for paid-tier sensors","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpgradeRequired"}}}},"404":{"description":"Sensor not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitError"}}}},"500":{"description":"Server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/tiq-ml":{"get":{"operationId":"listTiqMlScores","summary":"Latest TIQ-ML scores","description":"Returns the latest TIQ-ML scores across all tickers. Free tier receives direction + conviction only. Retail receives full scoring. Institutional receives full scoring plus `top_features` array.","tags":["TIQ-ML"],"parameters":[{"name":"ticker","in":"query","required":false,"description":"Filter to a specific ticker","schema":{"type":"string"}}],"responses":{"200":{"description":"TIQ-ML scores","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TiqMlListResponse"}}}},"500":{"description":"Server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/tiq-ml/{ticker}":{"get":{"operationId":"getTiqMlByTicker","summary":"TIQ-ML detail for a ticker","description":"Returns TIQ-ML score history for a specific ticker. Free tier limited to 200 rows; retail up to 1000. Same tier-gated field visibility as the list endpoint.","tags":["TIQ-ML"],"parameters":[{"name":"ticker","in":"path","required":true,"description":"Ticker symbol (e.g., `UPST`, `MARA`)","schema":{"type":"string"}},{"name":"limit","in":"query","required":false,"description":"Number of scores to return","schema":{"type":"integer","default":50,"minimum":1,"maximum":1000}}],"responses":{"200":{"description":"TIQ-ML scores for ticker","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TiqMlTickerResponse"}}}},"404":{"description":"No scores found for ticker","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/signal-drops":{"get":{"operationId":"listSignalDrops","summary":"Active signal drop fires","description":"Returns currently active signal drop fires. Free tier receives ticker + direction + severity. Retail receives full scoring and timing fields. Institutional receives evidence arrays and comparable data.","tags":["Signal Drops"],"parameters":[{"name":"ticker","in":"query","required":false,"description":"Filter to a specific ticker","schema":{"type":"string"}}],"responses":{"200":{"description":"Active signal drops","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SignalDropListResponse"}}}},"500":{"description":"Server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/proposals":{"get":{"operationId":"listProposals","summary":"Agent proposals","description":"Returns all agent proposals (sensor proposals, governance adjustments) with statistics. No authentication required.","tags":["Agents"],"security":[],"responses":{"200":{"description":"Proposals list","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProposalListResponse"}}}},"500":{"description":"Server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/dislocation":{"get":{"operationId":"listDislocations","summary":"Active dislocation scores","description":"Returns all active structural dislocation events with direction (STRUCTURAL_BUY or STRUCTURAL_SELL), severity, and component scores.","tags":["Dislocation"],"security":[],"responses":{"200":{"description":"Active dislocations","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DislocationListResponse"}}}},"500":{"description":"Server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/dislocation/{ticker}":{"get":{"operationId":"getDislocationByTicker","summary":"Dislocation detail for a ticker","description":"Returns the latest dislocation score with 5-component breakdown, full scoring history, and historical analog matches with forward returns.","tags":["Dislocation"],"parameters":[{"name":"ticker","in":"path","required":true,"description":"Ticker symbol","schema":{"type":"string"}}],"responses":{"200":{"description":"Dislocation detail with history and analogs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DislocationTickerResponse"}}}},"404":{"description":"No data for ticker","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/dislocation/batch":{"post":{"operationId":"batchDislocation","summary":"Bulk dislocation lookup","description":"Fetch dislocation scores for up to 50 tickers in a single request. Requires authentication (paid tier only). Each ticker returns the same detail as the individual endpoint.","tags":["Dislocation"],"security":[{"apiKey":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BatchDislocationRequest"}}}},"responses":{"200":{"description":"Batch dislocation results","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BatchDislocationResponse"}}}},"400":{"description":"Invalid request body","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Authentication required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpgradeRequired"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitError"}}}},"500":{"description":"Server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/interpretation":{"get":{"operationId":"getInterpretation","summary":"Latest regime interpretation","description":"Returns the latest AI-generated regime interpretation synthesized from all active sensors. Includes headline, summary, narrative type, confidence level, and sensor counts.","tags":["Interpretation"],"security":[],"responses":{"200":{"description":"Current regime interpretation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InterpretationResponse"}}}},"500":{"description":"Server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/auth/unlock":{"post":{"operationId":"authUnlock","summary":"Validate API key","description":"Validates an API key and sets an httpOnly session cookie for subsequent browser-based requests. Returns the key's tier and associated email.","tags":["Auth"],"security":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["apiKey"],"properties":{"apiKey":{"type":"string","description":"Your EHIQ API key"}}}}}},"responses":{"200":{"description":"Key validated","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","const":true},"tier":{"type":"string","enum":["retail","institutional"]},"email":{"type":"string","format":"email"}}}}}},"400":{"description":"API key required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Invalid or expired API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/auth/lock":{"post":{"operationId":"authLock","summary":"Clear session","description":"Clears the session cookie, effectively logging the user out.","tags":["Auth"],"security":[],"responses":{"200":{"description":"Session cleared","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","const":true}}}}}}}}},"/api/stripe/checkout":{"post":{"operationId":"createCheckout","summary":"Create Stripe checkout session","description":"Creates a Stripe checkout session for the $249/mo retail subscription. If the email already has a Stripe customer, redirects to billing portal instead.","tags":["Billing"],"security":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["email"],"properties":{"email":{"type":"string","format":"email","description":"Customer email"}}}}}},"responses":{"200":{"description":"Checkout URL","content":{"application/json":{"schema":{"type":"object","properties":{"url":{"type":"string","format":"uri","description":"Redirect URL for Stripe checkout or billing portal"}}}}}},"400":{"description":"Email required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Stripe not configured","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/stripe/portal":{"post":{"operationId":"billingPortal","summary":"Billing portal redirect","description":"Creates a Stripe billing portal session for subscription management. Requires API key authentication with a linked Stripe customer.","tags":["Billing"],"security":[{"apiKey":[]}],"responses":{"200":{"description":"Portal URL","content":{"application/json":{"schema":{"type":"object","properties":{"url":{"type":"string","format":"uri"}}}}}},"400":{"description":"No Stripe subscription linked","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/stripe/status":{"post":{"operationId":"subscriptionStatus","summary":"Subscription status","description":"Check whether an email has an active subscription. Returns tier and key prefix if subscribed.","tags":["Billing"],"security":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"email":{"type":"string","format":"email"}}}}}},"responses":{"200":{"description":"Subscription status","content":{"application/json":{"schema":{"type":"object","properties":{"subscribed":{"type":"boolean"},"tier":{"type":"string","enum":["retail","institutional"]},"keyPrefix":{"type":"string","description":"First 12 chars of API key (only when subscribed)"}},"required":["subscribed"]}}}}}}},"/api/alerts/subscribe":{"post":{"operationId":"alertSubscribe","summary":"Subscribe to email alerts","description":"Subscribe to sensor state-change alerts. A confirmation email is sent; the subscription is inactive until confirmed.","tags":["Alerts"],"security":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AlertSubscribeRequest"}}}},"responses":{"200":{"description":"Subscribed (pending confirmation)","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","const":true},"message":{"type":"string"}}}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many signups","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/alerts/confirm":{"get":{"operationId":"alertConfirm","summary":"Confirm email subscription","description":"Confirms an alert subscription via the token sent in the confirmation email. Redirects to a confirmation page on success.","tags":["Alerts"],"security":[],"parameters":[{"name":"token","in":"query","required":true,"description":"64-character hex confirmation token","schema":{"type":"string","pattern":"^[a-f0-9]{64}$"}}],"responses":{"302":{"description":"Redirect to confirmed page"},"400":{"description":"Missing or invalid token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Invalid or expired token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/alerts/unsubscribe":{"get":{"operationId":"alertUnsubscribe","summary":"Unsubscribe from alerts","description":"Unsubscribes an email from alerts via the token. Redirects to an unsubscribed page on success.","tags":["Alerts"],"security":[],"parameters":[{"name":"token","in":"query","required":true,"description":"64-character hex confirmation token from the original subscription","schema":{"type":"string","pattern":"^[a-f0-9]{64}$"}}],"responses":{"302":{"description":"Redirect to unsubscribed page"},"400":{"description":"Missing or invalid token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Invalid token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}},"components":{"securitySchemes":{"apiKey":{"type":"apiKey","in":"header","name":"x-ehiq-key","description":"API key for authenticated access. Free tier (no key): 60 req/min, limited fields. Retail ($249/mo): 600 req/min, all sensors, full fields. Institutional (custom): 6000 req/min, ML features, evidence arrays."}},"schemas":{"Error":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}}},"UpgradeRequired":{"type":"object","required":["error"],"properties":{"error":{"type":"string"},"upgrade":{"type":"string","format":"uri","const":"https://eventhorizoniq.com/pricing"}}},"RateLimitError":{"type":"object","required":["error","retry_after"],"properties":{"error":{"type":"string","const":"Rate limit exceeded"},"retry_after":{"type":"integer","description":"Seconds until rate limit resets"}}},"HealthResponse":{"type":"object","required":["status","db_connected","timestamp"],"properties":{"status":{"type":"string","enum":["ok","degraded","error"]},"db_connected":{"type":"boolean"},"sensors":{"type":"object","description":"Sensor freshness counts","properties":{"total":{"type":"integer"},"fresh":{"type":"integer","description":"Updated within expected cadence"},"stale":{"type":"integer","description":"Overdue but not dead"},"dead":{"type":"integer","description":"No reading in >24h"}}},"error":{"type":"string","description":"Error message (only when status=error)"},"timestamp":{"type":"string","format":"date-time"}}},"SparklineReading":{"type":"object","required":["state","recorded_at"],"properties":{"state":{"type":"string","description":"Sensor state (e.g., ELEVATED, NORMAL, STRESS)"},"value":{"type":"number","nullable":true,"description":"Numeric value if applicable"},"recorded_at":{"type":"string","format":"date-time"}}},"SensorSummary":{"type":"object","required":["sensor_id","name","category","current_state"],"properties":{"sensor_id":{"type":"string","description":"Unique sensor identifier (e.g., `btc-cycle-composite`)"},"name":{"type":"string"},"description":{"type":"string","nullable":true},"category":{"type":"string","description":"Sensor category (e.g., `crypto`, `macro`, `equity`, `composite`)"},"confidence":{"type":"number","nullable":true,"description":"Confidence score 0-1"},"current_state":{"type":"string"},"last_state_change":{"type":"string","format":"date-time","nullable":true},"updated_at":{"type":"string","format":"date-time","nullable":true},"notes":{"type":"string","nullable":true},"sparkline":{"type":"array","items":{"$ref":"#/components/schemas/SparklineReading"},"description":"Last 7 days of readings"}}},"SensorListResponse":{"type":"object","required":["version","read_only","as_of","sensors"],"properties":{"version":{"type":"string","const":"v1"},"read_only":{"type":"boolean","const":true},"as_of":{"type":"string","format":"date-time"},"sensors":{"type":"array","items":{"$ref":"#/components/schemas/SensorSummary"}}}},"LatestReading":{"type":"object","required":["state","recorded_at"],"properties":{"state":{"type":"string"},"value":{"type":"number","nullable":true},"metadata":{"type":"object","nullable":true,"description":"Structured metadata (some fields stripped for free-tier access on certain sensors)","additionalProperties":true},"recorded_at":{"type":"string","format":"date-time"}}},"SensorDetailResponse":{"type":"object","required":["sensor_id","name","category","current_state"],"properties":{"sensor_id":{"type":"string"},"name":{"type":"string"},"description":{"type":"string","nullable":true},"category":{"type":"string"},"confidence":{"type":"number","nullable":true},"current_state":{"type":"string"},"last_state_change":{"type":"string","format":"date-time","nullable":true},"state_definition":{"type":"object","nullable":true,"description":"Mapping of state names to their definitions","additionalProperties":{"type":"string"}},"interpretation":{"type":"string","nullable":true,"description":"Human-readable interpretation of current state"},"methodology":{"type":"string","nullable":true,"description":"How the sensor is calculated"},"outcomes":{"type":"string","nullable":true,"description":"Historical outcome data"},"sources":{"type":"string","nullable":true,"description":"Data sources"},"notes":{"type":"string","nullable":true},"latest_reading":{"nullable":true,"oneOf":[{"$ref":"#/components/schemas/LatestReading"},{"type":"null"}]}}},"HistoryReading":{"type":"object","required":["state","recorded_at"],"properties":{"state":{"type":"string"},"value":{"type":"number","nullable":true},"confidence":{"type":"number","nullable":true,"description":"Only present for authenticated users"},"metadata":{"type":"object","nullable":true,"description":"Only present for authenticated users","additionalProperties":true},"recorded_at":{"type":"string","format":"date-time"}}},"SensorHistoryResponse":{"type":"object","required":["sensor_id","sensor_name","tier","total_returned","limit","max_limit","offset","readings"],"properties":{"sensor_id":{"type":"string"},"sensor_name":{"type":"string"},"tier":{"type":"string","enum":["free","retail","institutional"],"description":"Resolved tier for this request"},"total_returned":{"type":"integer"},"limit":{"type":"integer"},"max_limit":{"type":"integer","description":"Maximum rows allowed for your tier (200/1000/10000)"},"offset":{"type":"integer"},"readings":{"type":"array","items":{"$ref":"#/components/schemas/HistoryReading"}}}},"TiqMlScoreFree":{"type":"object","required":["ticker","quarter","horizon","combined_direction","combined_conviction"],"description":"Free-tier TIQ-ML score (direction + conviction only)","properties":{"ticker":{"type":"string"},"quarter":{"type":"string","description":"e.g., Q3_FY2025"},"horizon":{"type":"string","description":"e.g., 90d, 180d, 360d"},"combined_direction":{"type":"string","enum":["LONG","SHORT","NEUTRAL"]},"combined_conviction":{"type":"string","enum":["HIGH","MEDIUM","LOW"]},"ml_confidence":{"type":"number","nullable":true,"description":"ML model confidence 0-1"},"scored_at":{"type":"string","format":"date-time","nullable":true}}},"TiqMlScoreRetail":{"type":"object","required":["ticker","quarter","horizon","combined_direction","combined_conviction"],"description":"Retail-tier TIQ-ML score (full scoring)","properties":{"ticker":{"type":"string"},"quarter":{"type":"string"},"horizon":{"type":"string"},"direction_prob":{"type":"number","nullable":true,"description":"ML probability of positive direction"},"combined_score":{"type":"number","nullable":true,"description":"Blended TIPS + ML score"},"combined_direction":{"type":"string","enum":["LONG","SHORT","NEUTRAL"]},"combined_conviction":{"type":"string","enum":["HIGH","MEDIUM","LOW"]},"tips_score":{"type":"number","nullable":true,"description":"Tonality IQ Pattern Score"},"tips_direction":{"type":"string","nullable":true},"ml_confidence":{"type":"number","nullable":true},"ml_gated":{"type":"boolean","nullable":true,"description":"Whether ML confidence passed the gate threshold"},"macro_headwind":{"type":"boolean","nullable":true,"description":"Macro regime headwind flag"},"conflict_flags":{"type":"string","nullable":true,"description":"Comma-separated conflict indicators"},"regime_state":{"type":"string","nullable":true,"description":"Current macro regime state"},"vix_at_signal":{"type":"number","nullable":true},"yield_curve":{"type":"number","nullable":true},"scored_at":{"type":"string","format":"date-time","nullable":true}}},"TiqMlScoreInstitutional":{"description":"Institutional-tier TIQ-ML score (full scoring + top features)","allOf":[{"$ref":"#/components/schemas/TiqMlScoreRetail"},{"type":"object","properties":{"top_features":{"type":"array","nullable":true,"items":{"type":"object","properties":{"feature":{"type":"string"},"value":{"type":"number"},"importance":{"type":"number"}}},"description":"Top ML feature importances driving the score"}}}]},"TiqMlListResponse":{"type":"object","required":["version","read_only","as_of","governance","count","scores"],"properties":{"version":{"type":"string","const":"v1"},"read_only":{"type":"boolean","const":true},"as_of":{"type":"string","format":"date-time"},"governance":{"type":"string","const":"ML modulates conviction, never overrides TIPS direction."},"count":{"type":"integer"},"scores":{"type":"array","items":{"oneOf":[{"$ref":"#/components/schemas/TiqMlScoreFree"},{"$ref":"#/components/schemas/TiqMlScoreRetail"},{"$ref":"#/components/schemas/TiqMlScoreInstitutional"}]},"description":"Fields present depend on your tier"},"upgrade":{"type":"string","format":"uri","description":"Present only for unauthenticated requests"}}},"TiqMlTickerResponse":{"type":"object","required":["version","read_only","as_of","governance","ticker","count","scores"],"properties":{"version":{"type":"string","const":"v1"},"read_only":{"type":"boolean","const":true},"as_of":{"type":"string","format":"date-time"},"governance":{"type":"string"},"ticker":{"type":"string"},"count":{"type":"integer"},"scores":{"type":"array","items":{"oneOf":[{"$ref":"#/components/schemas/TiqMlScoreFree"},{"$ref":"#/components/schemas/TiqMlScoreRetail"},{"$ref":"#/components/schemas/TiqMlScoreInstitutional"}]}},"upgrade":{"type":"string","format":"uri"}}},"SignalDropFree":{"type":"object","required":["ticker","signal_type","direction","severity"],"description":"Free-tier signal drop (ticker + direction + severity only)","properties":{"ticker":{"type":"string"},"signal_type":{"type":"string"},"direction":{"type":"string","enum":["LONG","SHORT"]},"severity":{"type":"string","enum":["HIGH","MEDIUM","LOW"]},"first_seen":{"type":"string","format":"date-time","nullable":true}}},"SignalDropRetail":{"type":"object","required":["fire_key","ticker","signal_type","direction","severity"],"description":"Retail-tier signal drop (full scoring + timing)","properties":{"fire_key":{"type":"string","description":"Unique fire identifier"},"ticker":{"type":"string"},"quarter":{"type":"string","nullable":true},"signal_type":{"type":"string"},"direction":{"type":"string","enum":["LONG","SHORT"]},"severity":{"type":"string","enum":["HIGH","MEDIUM","LOW"]},"tips_score":{"type":"number","nullable":true},"conviction":{"type":"string","nullable":true},"iv_rank":{"type":"number","nullable":true,"description":"Implied volatility rank"},"days_to_earnings":{"type":"integer","nullable":true},"earnings_flag":{"type":"string","nullable":true},"trade_deferred":{"type":"boolean","nullable":true},"arc_type":{"type":"string","nullable":true,"description":"Matched calibrated arc type"},"avg_outcome":{"type":"number","nullable":true,"description":"Average historical outcome for this arc"},"cases":{"type":"integer","nullable":true,"description":"Number of historical cases"},"template":{"type":"string","nullable":true},"first_seen":{"type":"string","format":"date-time","nullable":true}}},"SignalDropInstitutional":{"description":"Institutional-tier signal drop (full scoring + evidence + comparables)","allOf":[{"$ref":"#/components/schemas/SignalDropRetail"},{"type":"object","properties":{"patterns_involved":{"type":"array","nullable":true,"items":{"type":"string"},"description":"Pattern IDs that triggered this fire"},"evidence":{"type":"array","nullable":true,"items":{"type":"object","additionalProperties":true},"description":"Raw evidence supporting the signal"},"comparable":{"type":"array","nullable":true,"items":{"type":"object","additionalProperties":true},"description":"Historical comparable cases"}}}]},"SignalDropStats":{"type":"object","description":"Aggregate statistics for active signal drops","properties":{"total_active":{"type":"integer"},"long_count":{"type":"integer"},"short_count":{"type":"integer"}}},"SignalDropListResponse":{"type":"object","required":["version","read_only","as_of","governance","count","fires"],"properties":{"version":{"type":"string","const":"v1"},"read_only":{"type":"boolean","const":true},"as_of":{"type":"string","format":"date-time"},"governance":{"type":"string","const":"Intelligence proposes. Governance decides."},"stats":{"$ref":"#/components/schemas/SignalDropStats"},"count":{"type":"integer"},"fires":{"type":"array","items":{"oneOf":[{"$ref":"#/components/schemas/SignalDropFree"},{"$ref":"#/components/schemas/SignalDropRetail"},{"$ref":"#/components/schemas/SignalDropInstitutional"}]},"description":"Fields present depend on your tier"},"upgrade":{"type":"string","format":"uri"}}},"ProposalListResponse":{"type":"object","required":["version","total","proposals"],"properties":{"version":{"type":"string","const":"v1"},"total":{"type":"integer"},"stats":{"type":"object","description":"Proposal statistics by status","properties":{"pending":{"type":"integer"},"approved":{"type":"integer"},"rejected":{"type":"integer"},"implemented":{"type":"integer"}}},"proposals":{"type":"array","items":{"$ref":"#/components/schemas/Proposal"}}}},"Proposal":{"type":"object","properties":{"id":{"type":"integer"},"proposalType":{"type":"string","description":"e.g., NEW_SENSOR, ADJUSTMENT, CURATION"},"sensorId":{"type":"string","nullable":true},"title":{"type":"string"},"rationale":{"type":"string"},"status":{"type":"string","enum":["PENDING","APPROVED","REJECTED","IMPLEMENTED"]},"adjustScore":{"type":"number","nullable":true,"description":"ADJUST score 0-1 (auto-implement >= 0.8)"},"judgeScores":{"type":"object","nullable":true,"additionalProperties":true},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}},"DislocationEvent":{"type":"object","required":["ticker","score","direction"],"properties":{"ticker":{"type":"string"},"score":{"type":"number","description":"Composite dislocation score 0-100"},"direction":{"type":"string","enum":["STRUCTURAL_BUY","STRUCTURAL_SELL"]},"severity":{"type":"string","enum":["EXTREME","HIGH","MODERATE","LOW"]},"tiq_composite":{"type":"number","nullable":true,"description":"TIQ composite sentiment index"},"tiq_trend":{"type":"string","nullable":true,"description":"TIQ trend direction"},"summary":{"type":"string","nullable":true},"scored_at":{"type":"string","format":"date-time","nullable":true}}},"DislocationListResponse":{"type":"object","required":["total","structural_buys","structural_sells","events"],"properties":{"total":{"type":"integer"},"structural_buys":{"type":"integer"},"structural_sells":{"type":"integer"},"events":{"type":"array","items":{"$ref":"#/components/schemas/DislocationEvent"}}}},"DislocationComponents":{"type":"object","description":"5-component dislocation breakdown","properties":{"tiq_csi":{"type":"number","nullable":true,"description":"TIQ-CSI component weight"},"macro_regime":{"type":"number","nullable":true,"description":"Macro regime component weight"},"valuation":{"type":"number","nullable":true,"description":"Valuation component weight"},"insider":{"type":"number","nullable":true,"description":"Insider activity component weight"},"sector":{"type":"number","nullable":true,"description":"Sector relative component weight"}}},"DislocationLatest":{"type":"object","required":["score","direction"],"properties":{"score":{"type":"number"},"direction":{"type":"string","enum":["STRUCTURAL_BUY","STRUCTURAL_SELL"]},"severity":{"type":"string"},"components":{"$ref":"#/components/schemas/DislocationComponents"},"tiq_composite":{"type":"number","nullable":true},"tiq_trend":{"type":"string","nullable":true},"summary":{"type":"string","nullable":true},"scored_at":{"type":"string","format":"date-time","nullable":true}}},"DislocationHistoryEntry":{"type":"object","required":["score","direction"],"properties":{"score":{"type":"number"},"direction":{"type":"string","enum":["STRUCTURAL_BUY","STRUCTURAL_SELL"]},"severity":{"type":"string"},"scored_at":{"type":"string","format":"date-time","nullable":true}}},"DislocationAnalog":{"type":"object","properties":{"analog_ticker":{"type":"string"},"similarity":{"type":"number","description":"Cosine similarity 0-1"},"quarter":{"type":"string","nullable":true},"forward_return_30d":{"type":"number","nullable":true},"forward_return_90d":{"type":"number","nullable":true},"forward_return_180d":{"type":"number","nullable":true}}},"DislocationTickerResponse":{"type":"object","required":["ticker","latest","history","analogs"],"properties":{"ticker":{"type":"string"},"latest":{"$ref":"#/components/schemas/DislocationLatest"},"history":{"type":"array","items":{"$ref":"#/components/schemas/DislocationHistoryEntry"}},"analogs":{"type":"array","items":{"$ref":"#/components/schemas/DislocationAnalog"}}}},"BatchDislocationRequest":{"type":"object","required":["tickers"],"properties":{"tickers":{"type":"array","items":{"type":"string"},"minItems":1,"maxItems":50,"description":"Array of ticker symbols (max 50)","examples":[["ORCL","MARA","UPST"]]}}},"BatchDislocationResult":{"type":"object","nullable":true,"description":"Dislocation data for a single ticker, or null if no data exists","properties":{"latest":{"$ref":"#/components/schemas/DislocationLatest"},"history":{"type":"array","items":{"$ref":"#/components/schemas/DislocationHistoryEntry"}},"analogs":{"type":"array","items":{"$ref":"#/components/schemas/DislocationAnalog"}}}},"BatchDislocationResponse":{"type":"object","required":["version","as_of","requested","found","missing","results"],"properties":{"version":{"type":"string","const":"v1"},"as_of":{"type":"string","format":"date-time"},"requested":{"type":"integer","description":"Number of unique tickers requested"},"found":{"type":"integer","description":"Number of tickers with data"},"missing":{"type":"array","items":{"type":"string"},"description":"Tickers with no dislocation data"},"results":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/BatchDislocationResult"},"description":"Map of ticker to dislocation data (null for tickers with no data)"}}},"InterpretationResponse":{"type":"object","required":["headline","summary","narrative_type","confidence"],"properties":{"headline":{"type":"string","description":"One-line regime headline"},"summary":{"type":"string","description":"Multi-sentence regime interpretation"},"narrative_type":{"type":"string","enum":["REGIME_SHIFT","TREND_CONTINUATION","CONTRADICTION","INFLECTION","HONEST_ADMISSION"],"description":"Classification of the current narrative"},"confidence":{"type":"string","enum":["HIGH","MEDIUM","LOW"]},"total_sensors":{"type":"integer","description":"Total sensors evaluated"},"elevated_count":{"type":"integer","description":"Number of sensors in elevated state"}}},"AlertSubscribeRequest":{"type":"object","required":["email"],"properties":{"email":{"type":"string","format":"email","maxLength":254},"telegram_id":{"type":"string","nullable":true,"description":"Telegram username (@handle) or numeric ID","pattern":"^(@[a-zA-Z0-9_]{5,32}|\\d{5,15})$"},"x_handle":{"type":"string","nullable":true,"description":"X/Twitter handle (e.g., @username)","pattern":"^@[a-zA-Z0-9_]{1,15}$"},"sensors":{"type":"array","items":{"type":"string","maxLength":100},"maxItems":50,"description":"Sensor IDs to subscribe to. Empty array or omitted = all sensors."}}}}},"tags":[{"name":"Sensors","description":"Real-time sensor readings and history (49+ sensors)"},{"name":"TIQ-ML","description":"Tonality IQ machine learning scores (LogReg 8-feature, AUC 0.816)"},{"name":"Signal Drops","description":"Active signal drop fire events with arc matching"},{"name":"Dislocation","description":"Structural dislocation intelligence (cross-domain contradiction detection)"},{"name":"Interpretation","description":"AI-generated regime interpretation"},{"name":"Agents","description":"Autonomous agent proposals (SensorProposer, SensorJudge, GovernanceAuditor)"},{"name":"Auth","description":"API key validation and session management"},{"name":"Billing","description":"Stripe subscription management"},{"name":"Alerts","description":"Email alert subscriptions for sensor state changes"},{"name":"System","description":"Health and status endpoints"}]}