{"openapi":"3.1.0","info":{"title":"Exorde Intel API","description":"Exorde Intel API — social-intelligence data for crypto, geopolitics, disinformation, and brand signals. Tiered access (watch / see / know), per-topic scoping, and watchlist-based personalization. See https://docs.exorde.io for guides.","version":"1.2.5"},"paths":{"/v1/health":{"get":{"tags":["System"],"summary":"Liveness probe","operationId":"get_health_v1_health_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HealthResponse"}}}},"404":{"description":"Resource not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limit exceeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Backend unavailable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"security":[]}},"/v1/version":{"get":{"tags":["System"],"summary":"API version metadata","operationId":"get_version_v1_version_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/VersionResponse"}}}},"404":{"description":"Resource not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limit exceeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Backend unavailable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"security":[]}},"/v1/status":{"get":{"tags":["System"],"summary":"Operational status + per-stream / per-topic data freshness","operationId":"get_status_v1_status_get","parameters":[{"name":"topic","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"If set, scope topics[] to just this topic. Does not affect global stream checks.","title":"Topic"},"description":"If set, scope topics[] to just this topic. Does not affect global stream checks."}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}},"404":{"description":"Resource not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limit exceeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Backend unavailable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"security":[]}},"/v1/topics":{"get":{"tags":["System"],"summary":"Curated topic catalogue","operationId":"get_topics_v1_topics_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TopicsResponse"}}}},"404":{"description":"Resource not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limit exceeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Backend unavailable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"security":[]}},"/v1/usage":{"get":{"tags":["System"],"summary":"Monthly usage counters for the authenticated client","operationId":"get_usage_route_v1_usage_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UsageResponse"}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Tier or topic access denied.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Resource not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limit exceeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Backend unavailable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/keys/trial":{"post":{"tags":["Auth & Keys"],"summary":"Issue a trial API key","operationId":"issue_trial_key_v1_keys_trial_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TrialKeyRequest"}}},"required":true},"responses":{"201":{"description":"New trial key issued","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TrialKeyResponse"}}}},"200":{"description":"Existing still-valid trial key returned (idempotent replay)"},"422":{"description":"Invalid email"},"429":{"description":"Too many trial requests from this address"},"503":{"description":"Key issuance backend unavailable"},"404":{"description":"Resource not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"security":[]}},"/v1/keys/current":{"get":{"tags":["Auth & Keys"],"summary":"Inspect the currently-authenticated API key","operationId":"get_current_key_v1_keys_current_get","responses":{"200":{"description":"Key metadata","content":{"application/json":{"schema":{"$ref":"#/components/schemas/KeyResponse"}}}},"401":{"description":"Missing or invalid API key"},"404":{"description":"Key not found (revoked externally)"},"403":{"description":"Tier or topic access denied.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limit exceeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Backend unavailable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"delete":{"tags":["Auth & Keys"],"summary":"Revoke the caller's API key","operationId":"revoke_current_key_v1_keys_current_delete","responses":{"200":{"description":"Key revoked (or already inactive — idempotent)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RevokeKeyResponse"}}}},"401":{"description":"Missing or invalid API key"},"503":{"description":"Key issuance backend unavailable"},"403":{"description":"Tier or topic access denied.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Resource not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limit exceeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/keys/rotate":{"post":{"tags":["Auth & Keys"],"summary":"Rotate the caller's API key","operationId":"rotate_current_key_v1_keys_rotate_post","responses":{"200":{"description":"Key rotated — old key deactivated, new key returned","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RotateKeyResponse"}}}},"401":{"description":"Missing or invalid API key"},"409":{"description":"Current key is inactive or expired; rotate not allowed"},"503":{"description":"Key issuance backend unavailable"},"403":{"description":"Tier or topic access denied.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Resource not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limit exceeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/me":{"get":{"tags":["Me"],"summary":"Identity + entitlements for the authenticated key","operationId":"get_me_v1_me_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MeResponse"}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Tier or topic access denied.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Resource not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limit exceeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Backend unavailable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/topics/{topic}/alerts":{"get":{"tags":["Alerts"],"summary":"Get Alerts","description":"Query recent validated alerts for a topic.","operationId":"get_alerts_v1_topics__topic__alerts_get","parameters":[{"name":"topic","in":"path","required":true,"schema":{"type":"string","title":"Topic"}},{"name":"hours","in":"query","required":false,"schema":{"type":"integer","maximum":720,"minimum":1,"default":24,"title":"Hours"}},{"name":"signal_type","in":"query","required":false,"schema":{"type":"string","default":"all","title":"Signal Type"}},{"name":"keyword","in":"query","required":false,"schema":{"type":"string","default":"all","title":"Keyword"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":200,"minimum":1,"default":50,"title":"Limit"}},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","minimum":0,"default":0,"title":"Offset"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AlertsResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Tier or topic access denied.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Resource not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limit exceeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Backend unavailable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/topics/{topic}/trending":{"get":{"tags":["Trending"],"summary":"Get Trending","description":"Trending keywords, entities, domains, and languages for a topic.\n\nComparison model:\n- keywords: current time window vs previous time window (volume_signals)\n- entities: latest valid snapshot vs previous valid snapshot\n  (cluster_summaries FINAL, filtered to LATEST_FRAME_INDEX)\n- top_domains: latest valid snapshot, arrayJoin(top_domains)\n- top_languages: latest valid snapshot, summed language_breakdown weights","operationId":"get_trending_v1_topics__topic__trending_get","parameters":[{"name":"topic","in":"path","required":true,"schema":{"type":"string","title":"Topic"}},{"name":"hours","in":"query","required":false,"schema":{"type":"integer","maximum":168,"minimum":1,"default":24,"title":"Hours"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"default":20,"title":"Limit"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","title":"Response Get Trending V1 Topics  Topic  Trending Get"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Tier or topic access denied.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Resource not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limit exceeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Backend unavailable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/topics/{topic}/volume":{"get":{"tags":["Volume"],"summary":"Get Volume","description":"Bucketed volume time series for a topic.\n\nTier caps (from config.TIER_MAX_HOURS_VOLUME):\n- watch: short window\n- see:   medium window\n- know:  extended window\n\nTest mode:\n- caps hours to MAX_TEST_MODE_HOURS\n- returns short fixed sample data","operationId":"get_volume_v1_topics__topic__volume_get","parameters":[{"name":"topic","in":"path","required":true,"schema":{"type":"string","title":"Topic"}},{"name":"hours","in":"query","required":false,"schema":{"type":"integer","maximum":720,"minimum":1,"default":24,"title":"Hours"}},{"name":"bucket_mins","in":"query","required":false,"schema":{"type":"integer","maximum":1440,"minimum":1,"default":60,"title":"Bucket Mins"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","title":"Response Get Volume V1 Topics  Topic  Volume Get"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Tier or topic access denied.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Resource not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limit exceeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Backend unavailable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/topics/{topic}/volume/keywords":{"get":{"tags":["Volume"],"summary":"Get Volume Keywords","description":"Top keywords by signal volume within the selected time window.\n\nKeyword-only. The live volume_signals schema does not contain an\nentities column; any entity-level breakdown must come from\ncluster_summaries via /trending or /entities routes, not here.","operationId":"get_volume_keywords_v1_topics__topic__volume_keywords_get","parameters":[{"name":"topic","in":"path","required":true,"schema":{"type":"string","title":"Topic"}},{"name":"hours","in":"query","required":false,"schema":{"type":"integer","maximum":720,"minimum":1,"default":24,"title":"Hours"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"default":20,"title":"Limit"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","title":"Response Get Volume Keywords V1 Topics  Topic  Volume Keywords Get"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Tier or topic access denied.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Resource not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limit exceeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Backend unavailable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/topics/{topic}/clusters":{"get":{"tags":["Clusters"],"summary":"Get Clusters","operationId":"get_clusters_v1_topics__topic__clusters_get","parameters":[{"name":"topic","in":"path","required":true,"schema":{"type":"string","title":"Topic"}},{"name":"frame_index","in":"query","required":false,"schema":{"type":"integer","minimum":0,"default":3,"title":"Frame Index"}},{"name":"lifecycle_event","in":"query","required":false,"schema":{"type":"string","default":"all","title":"Lifecycle Event"}},{"name":"theme","in":"query","required":false,"schema":{"type":"string","default":"all","title":"Theme"}},{"name":"min_posts","in":"query","required":false,"schema":{"type":"integer","minimum":0,"default":0,"title":"Min Posts"}},{"name":"sort","in":"query","required":false,"schema":{"$ref":"#/components/schemas/ClusterSort","default":"post_count"}},{"name":"order","in":"query","required":false,"schema":{"$ref":"#/components/schemas/SortOrder","default":"desc"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":500,"minimum":1,"default":50,"title":"Limit"}},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","minimum":0,"default":0,"title":"Offset"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ClusterListResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Tier or topic access denied.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Resource not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limit exceeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Backend unavailable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/topics/{topic}/clusters/lifecycle":{"get":{"tags":["Clusters"],"summary":"Get Lifecycle","operationId":"get_lifecycle_v1_topics__topic__clusters_lifecycle_get","parameters":[{"name":"topic","in":"path","required":true,"schema":{"type":"string","title":"Topic"}},{"name":"frame_index","in":"query","required":false,"schema":{"type":"integer","minimum":0,"default":3,"title":"Frame Index"}},{"name":"cluster_id","in":"query","required":false,"schema":{"anyOf":[{"type":"integer","minimum":0},{"type":"null"}],"title":"Cluster Id"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":200,"minimum":1,"default":30,"title":"Limit"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/ClusterLifecycleSummaryResponse"},{"$ref":"#/components/schemas/ClusterLifecycleHistoryResponse"}],"title":"Response Get Lifecycle V1 Topics  Topic  Clusters Lifecycle Get"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Tier or topic access denied.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Resource not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limit exceeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Backend unavailable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/topics/{topic}/clusters/{cluster_id}":{"get":{"tags":["Clusters"],"summary":"Get Cluster Detail","operationId":"get_cluster_detail_v1_topics__topic__clusters__cluster_id__get","parameters":[{"name":"topic","in":"path","required":true,"schema":{"type":"string","title":"Topic"}},{"name":"cluster_id","in":"path","required":true,"schema":{"type":"integer","description":"Integer cluster ID.","title":"Cluster Id"},"description":"Integer cluster ID."},{"name":"frame_index","in":"query","required":false,"schema":{"type":"integer","minimum":0,"default":3,"title":"Frame Index"}},{"name":"posts_limit","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":0,"default":20,"title":"Posts Limit"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ClusterDetailResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Tier or topic access denied.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Resource not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limit exceeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Backend unavailable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/topics/{topic}/entities":{"get":{"tags":["Entities"],"summary":"List Entities","operationId":"list_entities_v1_topics__topic__entities_get","parameters":[{"name":"topic","in":"path","required":true,"schema":{"type":"string","title":"Topic"}},{"name":"frame_index","in":"query","required":false,"schema":{"type":"integer","minimum":0,"default":3,"title":"Frame Index"}},{"name":"min_mentions","in":"query","required":false,"schema":{"type":"integer","minimum":1,"default":2,"title":"Min Mentions"}},{"name":"entity_type","in":"query","required":false,"schema":{"$ref":"#/components/schemas/EntityTypeFilter","default":"all"}},{"name":"sort","in":"query","required":false,"schema":{"$ref":"#/components/schemas/EntitySort","default":"mentions"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":200,"minimum":1,"default":50,"title":"Limit"}},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","minimum":0,"default":0,"title":"Offset"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EntityListResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Tier or topic access denied.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Resource not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limit exceeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Backend unavailable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/topics/{topic}/entities/cooccurrence":{"get":{"tags":["Entities"],"summary":"Entity Cooccurrence","operationId":"entity_cooccurrence_v1_topics__topic__entities_cooccurrence_get","parameters":[{"name":"topic","in":"path","required":true,"schema":{"type":"string","title":"Topic"}},{"name":"frame_index","in":"query","required":false,"schema":{"type":"integer","minimum":0,"default":3,"title":"Frame Index"}},{"name":"min_weight","in":"query","required":false,"schema":{"type":"integer","minimum":1,"default":2,"title":"Min Weight"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":200,"minimum":1,"default":50,"title":"Limit"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EntityCooccurrenceResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Tier or topic access denied.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Resource not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limit exceeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Backend unavailable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/topics/{topic}/entities/{entity_name}/timeline":{"get":{"tags":["Entities"],"summary":"Entity Timeline","operationId":"entity_timeline_v1_topics__topic__entities__entity_name__timeline_get","parameters":[{"name":"topic","in":"path","required":true,"schema":{"type":"string","title":"Topic"}},{"name":"entity_name","in":"path","required":true,"schema":{"type":"string","description":"URL-encoded entity name.","title":"Entity Name"},"description":"URL-encoded entity name."},{"name":"days","in":"query","required":false,"schema":{"type":"integer","maximum":365,"minimum":1,"default":7,"title":"Days"}},{"name":"frame_index","in":"query","required":false,"schema":{"type":"integer","minimum":0,"default":3,"title":"Frame Index"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EntityTimelineResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Tier or topic access denied.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Resource not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limit exceeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Backend unavailable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/topics/{topic}/narrative":{"get":{"tags":["Narratives"],"summary":"Get Narrative","description":"Latest narrative snapshot with derived highlights.\n\nDefense in depth:\n- auth middleware already enforced auth, feature, and topic gates\n- router rechecks them explicitly with the dotted feature key","operationId":"get_narrative_v1_topics__topic__narrative_get","parameters":[{"name":"topic","in":"path","required":true,"schema":{"type":"string","title":"Topic"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","title":"Response Get Narrative V1 Topics  Topic  Narrative Get"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Tier or topic access denied.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Resource not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limit exceeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Backend unavailable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/topics/{topic}/narratives":{"get":{"tags":["Narratives"],"summary":"Get Narrative History","description":"Narrative history over a bounded number of days.\n\nTier caps come from config.TIER_MAX_DAYS_NARRATIVES. In test mode,\nreturn latest-only history and omit the structured block to match the\nintended demo degradation model.","operationId":"get_narrative_history_v1_topics__topic__narratives_get","parameters":[{"name":"topic","in":"path","required":true,"schema":{"type":"string","title":"Topic"}},{"name":"days","in":"query","required":false,"schema":{"type":"integer","maximum":365,"minimum":1,"default":14,"title":"Days"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"array","items":{"type":"object"},"title":"Response Get Narrative History V1 Topics  Topic  Narratives Get"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Tier or topic access denied.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Resource not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limit exceeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Backend unavailable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/topics/{topic}/search":{"get":{"tags":["Search"],"summary":"Semantic Search","description":"Semantic search over the topic FAISS index with ClickHouse enrichment.","operationId":"semantic_search_v1_topics__topic__search_get","parameters":[{"name":"topic","in":"path","required":true,"schema":{"type":"string","title":"Topic"}},{"name":"q","in":"query","required":false,"schema":{"type":"string","minLength":0,"maxLength":500,"description":"Search query text.","default":"","title":"Q"},"description":"Search query text."},{"name":"vector","in":"query","required":false,"schema":{"type":"string","description":"JSON-encoded or comma-separated 384-D float vector.","default":"","title":"Vector"},"description":"JSON-encoded or comma-separated 384-D float vector."},{"name":"top_k","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"default":20,"title":"Top K"}},{"name":"threshold","in":"query","required":false,"schema":{"type":"number","maximum":1.0,"minimum":0.0,"default":0.25,"title":"Threshold"}},{"name":"lifecycle","in":"query","required":false,"schema":{"type":"string","default":"all","title":"Lifecycle"}},{"name":"theme","in":"query","required":false,"schema":{"type":"string","default":"all","title":"Theme"}},{"name":"min_posts","in":"query","required":false,"schema":{"type":"integer","minimum":0,"default":0,"title":"Min Posts"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","title":"Response Semantic Search V1 Topics  Topic  Search Get"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Tier or topic access denied.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Resource not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limit exceeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Backend unavailable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/topics/{topic}/platforms":{"get":{"tags":["Platforms"],"summary":"Get Platforms","description":"Aggregate domain stats from embedding_snapshots for the latest snapshot.","operationId":"get_platforms_v1_topics__topic__platforms_get","parameters":[{"name":"topic","in":"path","required":true,"schema":{"type":"string","title":"Topic"}},{"name":"frame_index","in":"query","required":false,"schema":{"type":"integer","minimum":0,"default":3,"title":"Frame Index"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"default":20,"title":"Limit"}},{"name":"sort","in":"query","required":false,"schema":{"type":"string","default":"post_count","title":"Sort"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","title":"Response Get Platforms V1 Topics  Topic  Platforms Get"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Tier or topic access denied.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Resource not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limit exceeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Backend unavailable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/topics/{topic}/reports/latest":{"get":{"tags":["Reports"],"summary":"Get Latest Report","description":"Latest weekly executive report.","operationId":"get_latest_report_v1_topics__topic__reports_latest_get","parameters":[{"name":"topic","in":"path","required":true,"schema":{"type":"string","title":"Topic"}},{"name":"format","in":"query","required":false,"schema":{"type":"string","description":"json, pdf, csv","default":"json","title":"Format"},"description":"json, pdf, csv"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"title":"Response Get Latest Report V1 Topics  Topic  Reports Latest Get"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Tier or topic access denied.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Resource not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limit exceeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Backend unavailable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/topics/{topic}/reports":{"get":{"tags":["Reports"],"summary":"Get Reports","description":"Report archive — paginated list of weekly reports.","operationId":"get_reports_v1_topics__topic__reports_get","parameters":[{"name":"topic","in":"path","required":true,"schema":{"type":"string","title":"Topic"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":52,"minimum":1,"default":10,"title":"Limit"}},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","minimum":0,"default":0,"title":"Offset"}},{"name":"format","in":"query","required":false,"schema":{"type":"string","description":"json, pdf, csv","default":"json","title":"Format"},"description":"json, pdf, csv"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"title":"Response Get Reports V1 Topics  Topic  Reports Get"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Tier or topic access denied.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Resource not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limit exceeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Backend unavailable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/watchlists":{"get":{"tags":["Watchlists"],"summary":"List watchlists","operationId":"list_watchlists_v1_watchlists_get","parameters":[{"name":"limit","in":"query","required":false,"schema":{"type":"integer","default":50,"title":"Limit"}},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","default":0,"title":"Offset"}},{"name":"include_inactive","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Include Inactive"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","title":"Response List Watchlists V1 Watchlists Get"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Tier or topic access denied.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Resource not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limit exceeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Backend unavailable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"post":{"tags":["Watchlists"],"summary":"Create a watchlist","operationId":"create_watchlist_v1_watchlists_post","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WatchlistCreate"}}}},"responses":{"201":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","title":"Response Create Watchlist V1 Watchlists Post"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Tier or topic access denied.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Resource not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limit exceeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Backend unavailable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/watchlists/{watchlist_id}":{"get":{"tags":["Watchlists"],"summary":"Get a watchlist","operationId":"get_watchlist_v1_watchlists__watchlist_id__get","parameters":[{"name":"watchlist_id","in":"path","required":true,"schema":{"type":"string","title":"Watchlist Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","title":"Response Get Watchlist V1 Watchlists  Watchlist Id  Get"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Tier or topic access denied.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Resource not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limit exceeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Backend unavailable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"patch":{"tags":["Watchlists"],"summary":"Update a watchlist","operationId":"patch_watchlist_v1_watchlists__watchlist_id__patch","parameters":[{"name":"watchlist_id","in":"path","required":true,"schema":{"type":"string","title":"Watchlist Id"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WatchlistPatch"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","title":"Response Patch Watchlist V1 Watchlists  Watchlist Id  Patch"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Tier or topic access denied.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Resource not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limit exceeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Backend unavailable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"delete":{"tags":["Watchlists"],"summary":"Delete a watchlist (soft)","operationId":"delete_watchlist_v1_watchlists__watchlist_id__delete","parameters":[{"name":"watchlist_id","in":"path","required":true,"schema":{"type":"string","title":"Watchlist Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","title":"Response Delete Watchlist V1 Watchlists  Watchlist Id  Delete"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Tier or topic access denied.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Resource not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limit exceeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Backend unavailable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/watchlists/{watchlist_id}/trending":{"get":{"tags":["Watchlists"],"summary":"Watchlist trending keywords","operationId":"watchlist_trending_v1_watchlists__watchlist_id__trending_get","parameters":[{"name":"watchlist_id","in":"path","required":true,"schema":{"type":"string","title":"Watchlist Id"}},{"name":"hours","in":"query","required":false,"schema":{"type":"integer","maximum":168,"minimum":1,"default":168,"title":"Hours"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"default":20,"title":"Limit"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","title":"Response Watchlist Trending V1 Watchlists  Watchlist Id  Trending Get"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Tier or topic access denied.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Resource not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limit exceeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Backend unavailable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/watchlists/{watchlist_id}/volume":{"get":{"tags":["Watchlists"],"summary":"Watchlist volume time series","operationId":"watchlist_volume_v1_watchlists__watchlist_id__volume_get","parameters":[{"name":"watchlist_id","in":"path","required":true,"schema":{"type":"string","title":"Watchlist Id"}},{"name":"hours","in":"query","required":false,"schema":{"type":"integer","maximum":168,"minimum":1,"default":168,"title":"Hours"}},{"name":"bucket_minutes","in":"query","required":false,"schema":{"type":"integer","maximum":1440,"minimum":15,"default":60,"title":"Bucket Minutes"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","title":"Response Watchlist Volume V1 Watchlists  Watchlist Id  Volume Get"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Tier or topic access denied.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Resource not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limit exceeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Backend unavailable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/watchlists/{watchlist_id}/volume/keywords":{"get":{"tags":["Watchlists"],"summary":"Watchlist per-term volume","operationId":"watchlist_volume_keywords_v1_watchlists__watchlist_id__volume_keywords_get","parameters":[{"name":"watchlist_id","in":"path","required":true,"schema":{"type":"string","title":"Watchlist Id"}},{"name":"hours","in":"query","required":false,"schema":{"type":"integer","maximum":168,"minimum":1,"default":168,"title":"Hours"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","title":"Response Watchlist Volume Keywords V1 Watchlists  Watchlist Id  Volume Keywords Get"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Tier or topic access denied.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Resource not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limit exceeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Backend unavailable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/watchlists/{watchlist_id}/entities":{"get":{"tags":["Watchlists"],"summary":"Watchlist entities","operationId":"watchlist_entities_v1_watchlists__watchlist_id__entities_get","parameters":[{"name":"watchlist_id","in":"path","required":true,"schema":{"type":"string","title":"Watchlist Id"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":200,"minimum":1,"default":50,"title":"Limit"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","title":"Response Watchlist Entities V1 Watchlists  Watchlist Id  Entities Get"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Tier or topic access denied.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Resource not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limit exceeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Backend unavailable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/watchlists/{watchlist_id}/platforms":{"get":{"tags":["Watchlists"],"summary":"Watchlist top domains","operationId":"watchlist_platforms_v1_watchlists__watchlist_id__platforms_get","parameters":[{"name":"watchlist_id","in":"path","required":true,"schema":{"type":"string","title":"Watchlist Id"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":200,"minimum":1,"default":50,"title":"Limit"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","title":"Response Watchlist Platforms V1 Watchlists  Watchlist Id  Platforms Get"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Tier or topic access denied.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Resource not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limit exceeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Backend unavailable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/watchlists/{watchlist_id}/narrative":{"get":{"tags":["Watchlists"],"summary":"Watchlist narrative","operationId":"watchlist_narrative_v1_watchlists__watchlist_id__narrative_get","parameters":[{"name":"watchlist_id","in":"path","required":true,"schema":{"type":"string","title":"Watchlist Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","title":"Response Watchlist Narrative V1 Watchlists  Watchlist Id  Narrative Get"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Tier or topic access denied.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Resource not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limit exceeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Backend unavailable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/watchlists/{watchlist_id}/clusters":{"get":{"tags":["Watchlists"],"summary":"Watchlist matched clusters","operationId":"watchlist_clusters_v1_watchlists__watchlist_id__clusters_get","parameters":[{"name":"watchlist_id","in":"path","required":true,"schema":{"type":"string","title":"Watchlist Id"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":200,"minimum":1,"default":50,"title":"Limit"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","title":"Response Watchlist Clusters V1 Watchlists  Watchlist Id  Clusters Get"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Tier or topic access denied.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Resource not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limit exceeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Backend unavailable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/watchlists/{watchlist_id}/posts":{"get":{"tags":["Watchlists"],"summary":"Watchlist evidence clusters","operationId":"watchlist_posts_v1_watchlists__watchlist_id__posts_get","parameters":[{"name":"watchlist_id","in":"path","required":true,"schema":{"type":"string","title":"Watchlist Id"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"default":25,"title":"Limit"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","title":"Response Watchlist Posts V1 Watchlists  Watchlist Id  Posts Get"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Tier or topic access denied.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Resource not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limit exceeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Backend unavailable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/watchlists/{watchlist_id}/alerts":{"get":{"tags":["Watchlists"],"summary":"Watchlist alerts","operationId":"watchlist_alerts_v1_watchlists__watchlist_id__alerts_get","parameters":[{"name":"watchlist_id","in":"path","required":true,"schema":{"type":"string","title":"Watchlist Id"}},{"name":"hours","in":"query","required":false,"schema":{"type":"integer","maximum":168,"minimum":1,"default":168,"title":"Hours"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"default":25,"title":"Limit"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","title":"Response Watchlist Alerts V1 Watchlists  Watchlist Id  Alerts Get"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Tier or topic access denied.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Resource not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limit exceeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Backend unavailable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/subscriptions":{"get":{"tags":["Subscriptions"],"summary":"List Subscriptions","operationId":"list_subscriptions_v1_subscriptions_get","parameters":[{"name":"topic","in":"query","required":false,"schema":{"type":"string","default":"all","title":"Topic"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubscriptionListResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Tier or topic access denied.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Resource not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limit exceeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Backend unavailable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"post":{"tags":["Subscriptions"],"summary":"Create Subscription","operationId":"create_subscription_v1_subscriptions_post","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubscriptionCreate"}}}},"responses":{"201":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubscriptionOut"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Tier or topic access denied.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Resource not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limit exceeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Backend unavailable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/subscriptions/{subscription_id}":{"delete":{"tags":["Subscriptions"],"summary":"Delete Subscription","operationId":"delete_subscription_v1_subscriptions__subscription_id__delete","parameters":[{"name":"subscription_id","in":"path","required":true,"schema":{"type":"string","title":"Subscription Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":{"type":"string"},"title":"Response Delete Subscription V1 Subscriptions  Subscription Id  Delete"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Tier or topic access denied.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Resource not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limit exceeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Backend unavailable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/topics/{topic}/clusters/{cluster_id}/posts":{"get":{"tags":["Clusters"],"summary":"Evidence posts for a cluster (keyword-matched)","operationId":"get_cluster_posts_v1_topics__topic__clusters__cluster_id__posts_get","parameters":[{"name":"topic","in":"path","required":true,"schema":{"type":"string","title":"Topic"}},{"name":"cluster_id","in":"path","required":true,"schema":{"type":"string","title":"Cluster Id"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":200,"minimum":1,"default":20,"title":"Limit"}},{"name":"hours","in":"query","required":false,"schema":{"type":"integer","maximum":168,"minimum":1,"default":24,"title":"Hours"}},{"name":"language","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":16},{"type":"null"}],"title":"Language"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PostsResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Tier or topic access denied.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Resource not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limit exceeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Backend unavailable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/topics/{topic}/entities/{entity}/posts":{"get":{"tags":["Clusters"],"summary":"Evidence posts for an entity (keyword-matched)","operationId":"get_entity_posts_v1_topics__topic__entities__entity__posts_get","parameters":[{"name":"topic","in":"path","required":true,"schema":{"type":"string","title":"Topic"}},{"name":"entity","in":"path","required":true,"schema":{"type":"string","title":"Entity"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":200,"minimum":1,"default":20,"title":"Limit"}},{"name":"hours","in":"query","required":false,"schema":{"type":"integer","maximum":168,"minimum":1,"default":24,"title":"Hours"}},{"name":"language","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":16},{"type":"null"}],"title":"Language"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PostsResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Tier or topic access denied.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Resource not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limit exceeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Backend unavailable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/topics/{topic}/narratives/{narrative_id}/posts":{"get":{"tags":["Clusters"],"summary":"Evidence posts for a narrative snapshot (keyword-matched)","operationId":"get_narrative_posts_v1_topics__topic__narratives__narrative_id__posts_get","parameters":[{"name":"topic","in":"path","required":true,"schema":{"type":"string","title":"Topic"}},{"name":"narrative_id","in":"path","required":true,"schema":{"type":"string","title":"Narrative Id"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":200,"minimum":1,"default":20,"title":"Limit"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PostsResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Tier or topic access denied.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Resource not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limit exceeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Backend unavailable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}},"components":{"schemas":{"AlertHashes":{"properties":{"md5":{"items":{"type":"string"},"type":"array","title":"Md5"},"sha1":{"items":{"type":"string"},"type":"array","title":"Sha1"},"sha256":{"items":{"type":"string"},"type":"array","title":"Sha256"}},"type":"object","title":"AlertHashes"},"AlertIOCs":{"properties":{"urls":{"items":{"type":"string"},"type":"array","title":"Urls"},"ips":{"items":{"type":"string"},"type":"array","title":"Ips"},"hashes":{"$ref":"#/components/schemas/AlertHashes"},"cves":{"items":{"type":"string"},"type":"array","title":"Cves"},"crypto_wallets":{"items":{"type":"string"},"type":"array","title":"Crypto Wallets"},"emails":{"items":{"type":"string"},"type":"array","title":"Emails"},"domains":{"items":{"type":"string"},"type":"array","title":"Domains"}},"type":"object","title":"AlertIOCs"},"AlertItem":{"properties":{"alert_id":{"type":"string","title":"Alert Id"},"detected_at":{"type":"string","title":"Detected At"},"topic":{"type":"string","title":"Topic"},"signal_type":{"type":"string","title":"Signal Type"},"source":{"type":"string","title":"Source"},"keyword":{"type":"string","title":"Keyword"},"confidence":{"type":"number","title":"Confidence"},"severity":{"$ref":"#/components/schemas/AlertSeverity"},"spread":{"$ref":"#/components/schemas/AlertSpread"},"llm_validated":{"type":"boolean","title":"Llm Validated"},"description":{"type":"string","title":"Description"},"sample_posts":{"items":{"$ref":"#/components/schemas/AlertSamplePost"},"type":"array","title":"Sample Posts"},"iocs":{"$ref":"#/components/schemas/AlertIOCs"},"matched_cluster":{"anyOf":[{"$ref":"#/components/schemas/MatchedCluster"},{"type":"null"}]}},"type":"object","required":["alert_id","detected_at","topic","signal_type","source","keyword","confidence","severity","spread","llm_validated","description"],"title":"AlertItem"},"AlertSamplePost":{"properties":{"preview":{"type":"string","title":"Preview"},"domain":{"type":"string","title":"Domain"},"language":{"type":"string","title":"Language"}},"type":"object","required":["preview","domain","language"],"title":"AlertSamplePost"},"AlertSeverity":{"properties":{"deviation_sigma":{"type":"number","title":"Deviation Sigma"},"current_value":{"type":"number","title":"Current Value"},"baseline_value":{"type":"number","title":"Baseline Value"}},"type":"object","required":["deviation_sigma","current_value","baseline_value"],"title":"AlertSeverity"},"AlertSpread":{"properties":{"domain_count":{"type":"integer","title":"Domain Count"},"language_count":{"type":"integer","title":"Language Count"}},"type":"object","required":["domain_count","language_count"],"title":"AlertSpread"},"AlertsResponse":{"properties":{"alerts":{"items":{"$ref":"#/components/schemas/AlertItem"},"type":"array","title":"Alerts"},"count":{"type":"integer","title":"Count"},"total":{"type":"integer","title":"Total"}},"type":"object","required":["count","total"],"title":"AlertsResponse"},"ClusterDetailItem":{"properties":{"cluster_id":{"type":"integer","title":"Cluster Id"},"title":{"type":"string","title":"Title"},"title_source":{"type":"string","title":"Title Source"},"summary":{"type":"string","title":"Summary"},"post_count":{"type":"integer","title":"Post Count"},"keywords":{"items":{"type":"string"},"type":"array","title":"Keywords"},"entities":{"items":{"$ref":"#/components/schemas/ClusterEntity"},"type":"array","title":"Entities"},"sentiment":{"type":"number","title":"Sentiment"},"dominant_emotion":{"type":"string","title":"Dominant Emotion"},"lifecycle_event":{"type":"string","title":"Lifecycle Event"},"parent_cluster_id":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Parent Cluster Id"},"theme":{"type":"string","title":"Theme"},"language_breakdown":{"additionalProperties":{"type":"number"},"type":"object","title":"Language Breakdown"},"coordination_indicators":{"anyOf":[{"$ref":"#/components/schemas/CoordinationIndicators"},{"type":"null"}]},"iocs":{"anyOf":[{"$ref":"#/components/schemas/IndicatorCollection"},{"type":"null"}]},"sample_posts":{"items":{"$ref":"#/components/schemas/ClusterSamplePost"},"type":"array","title":"Sample Posts"}},"type":"object","required":["cluster_id","title","title_source","summary","post_count","sentiment","dominant_emotion","lifecycle_event","theme"],"title":"ClusterDetailItem"},"ClusterDetailResponse":{"properties":{"cluster":{"$ref":"#/components/schemas/ClusterDetailItem"},"posts_count":{"type":"integer","title":"Posts Count"},"snapshot_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Snapshot Id"},"frame_index":{"type":"integer","title":"Frame Index"}},"type":"object","required":["cluster","posts_count","frame_index"],"title":"ClusterDetailResponse"},"ClusterEntity":{"properties":{"name":{"type":"string","title":"Name"},"type":{"type":"string","title":"Type"}},"type":"object","required":["name","type"],"title":"ClusterEntity"},"ClusterItem":{"properties":{"cluster_id":{"type":"integer","title":"Cluster Id"},"title":{"type":"string","title":"Title"},"title_source":{"type":"string","title":"Title Source"},"summary":{"type":"string","title":"Summary"},"post_count":{"type":"integer","title":"Post Count"},"keywords":{"items":{"type":"string"},"type":"array","title":"Keywords"},"entities":{"items":{"$ref":"#/components/schemas/ClusterEntity"},"type":"array","title":"Entities"},"sentiment":{"type":"number","title":"Sentiment"},"dominant_emotion":{"type":"string","title":"Dominant Emotion"},"lifecycle_event":{"type":"string","title":"Lifecycle Event"},"parent_cluster_id":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Parent Cluster Id"},"theme":{"type":"string","title":"Theme"},"language_breakdown":{"additionalProperties":{"type":"number"},"type":"object","title":"Language Breakdown"},"coordination_indicators":{"anyOf":[{"$ref":"#/components/schemas/CoordinationIndicators"},{"type":"null"}]},"iocs":{"anyOf":[{"$ref":"#/components/schemas/IndicatorCollection"},{"type":"null"}]}},"type":"object","required":["cluster_id","title","title_source","summary","post_count","sentiment","dominant_emotion","lifecycle_event","theme"],"title":"ClusterItem"},"ClusterLifecycleHistoryItem":{"properties":{"snapshot_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Snapshot Id"},"frame_index":{"type":"integer","title":"Frame Index"},"post_count":{"type":"integer","title":"Post Count"},"avg_sentiment":{"type":"number","title":"Avg Sentiment"},"lifecycle_event":{"type":"string","title":"Lifecycle Event"},"parent_cluster_id":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Parent Cluster Id"}},"type":"object","required":["frame_index","post_count","avg_sentiment","lifecycle_event"],"title":"ClusterLifecycleHistoryItem"},"ClusterLifecycleHistoryResponse":{"properties":{"cluster_id":{"type":"integer","title":"Cluster Id"},"topic":{"type":"string","title":"Topic"},"history":{"items":{"$ref":"#/components/schemas/ClusterLifecycleHistoryItem"},"type":"array","title":"History"},"frame_index":{"type":"integer","title":"Frame Index"}},"type":"object","required":["cluster_id","topic","frame_index"],"title":"ClusterLifecycleHistoryResponse"},"ClusterLifecycleSummaryItem":{"properties":{"lifecycle_event":{"type":"string","title":"Lifecycle Event"},"cluster_count":{"type":"integer","title":"Cluster Count"},"total_posts":{"type":"integer","title":"Total Posts"},"avg_sentiment":{"type":"number","title":"Avg Sentiment"}},"type":"object","required":["lifecycle_event","cluster_count","total_posts","avg_sentiment"],"title":"ClusterLifecycleSummaryItem"},"ClusterLifecycleSummaryResponse":{"properties":{"lifecycle":{"items":{"$ref":"#/components/schemas/ClusterLifecycleSummaryItem"},"type":"array","title":"Lifecycle"},"snapshot_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Snapshot Id"},"frame_index":{"type":"integer","title":"Frame Index"}},"type":"object","required":["frame_index"],"title":"ClusterLifecycleSummaryResponse"},"ClusterListResponse":{"properties":{"clusters":{"items":{"$ref":"#/components/schemas/ClusterItem"},"type":"array","title":"Clusters"},"count":{"type":"integer","title":"Count"},"total":{"type":"integer","title":"Total"},"snapshot_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Snapshot Id"},"frame_index":{"type":"integer","title":"Frame Index"}},"type":"object","required":["count","total","frame_index"],"title":"ClusterListResponse"},"ClusterSamplePost":{"properties":{"external_id":{"type":"string","title":"External Id"},"domain":{"type":"string","title":"Domain"},"language":{"type":"string","title":"Language"},"sentiment":{"type":"number","title":"Sentiment"},"dominant_emotion":{"type":"string","title":"Dominant Emotion"},"classification":{"type":"string","title":"Classification"},"content_preview":{"type":"string","title":"Content Preview"},"top_keywords":{"items":{"type":"string"},"type":"array","title":"Top Keywords"}},"type":"object","required":["external_id","domain","language","sentiment","dominant_emotion","classification","content_preview"],"title":"ClusterSamplePost"},"ClusterSort":{"type":"string","enum":["post_count","sentiment","cluster_id"],"title":"ClusterSort"},"CoordinationIndicators":{"properties":{"temporal_concentration":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Temporal Concentration"},"domain_concentration":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Domain Concentration"},"language_uniformity":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Language Uniformity"},"cadence_regularity":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Cadence Regularity"},"overall_score":{"type":"number","title":"Overall Score","default":0.0},"assessment":{"type":"string","title":"Assessment"},"unavailable_metrics":{"items":{"type":"string"},"type":"array","title":"Unavailable Metrics"}},"type":"object","required":["assessment"],"title":"CoordinationIndicators"},"EntityCooccurrenceEdge":{"properties":{"source":{"type":"string","title":"Source"},"target":{"type":"string","title":"Target"},"weight":{"type":"integer","title":"Weight"}},"type":"object","required":["source","target","weight"],"title":"EntityCooccurrenceEdge"},"EntityCooccurrenceNode":{"properties":{"name":{"type":"string","title":"Name"},"type":{"type":"string","title":"Type"},"mentions":{"type":"integer","title":"Mentions"},"total_posts":{"type":"integer","title":"Total Posts"}},"type":"object","required":["name","type","mentions","total_posts"],"title":"EntityCooccurrenceNode"},"EntityCooccurrenceResponse":{"properties":{"nodes":{"items":{"$ref":"#/components/schemas/EntityCooccurrenceNode"},"type":"array","title":"Nodes"},"edges":{"items":{"$ref":"#/components/schemas/EntityCooccurrenceEdge"},"type":"array","title":"Edges"},"node_count":{"type":"integer","title":"Node Count"},"edge_count":{"type":"integer","title":"Edge Count"},"snapshot_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Snapshot Id"},"frame_index":{"type":"integer","title":"Frame Index"}},"type":"object","required":["node_count","edge_count","frame_index"],"title":"EntityCooccurrenceResponse"},"EntityListResponse":{"properties":{"entities":{"items":{"$ref":"#/components/schemas/EntitySummaryItem"},"type":"array","title":"Entities"},"count":{"type":"integer","title":"Count"},"total":{"type":"integer","title":"Total"},"snapshot_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Snapshot Id"},"frame_index":{"type":"integer","title":"Frame Index"}},"type":"object","required":["count","total","frame_index"],"title":"EntityListResponse"},"EntitySort":{"type":"string","enum":["mentions","posts","sentiment","name"],"title":"EntitySort"},"EntitySummaryItem":{"properties":{"name":{"type":"string","title":"Name"},"type":{"type":"string","title":"Type"},"mentions":{"type":"integer","title":"Mentions"},"total_posts":{"type":"integer","title":"Total Posts"},"avg_sentiment":{"type":"number","title":"Avg Sentiment"},"dominant_theme":{"type":"string","title":"Dominant Theme"},"dominant_lifecycle_event":{"type":"string","title":"Dominant Lifecycle Event"},"cluster_ids":{"items":{"type":"integer"},"type":"array","title":"Cluster Ids"}},"type":"object","required":["name","type","mentions","total_posts","avg_sentiment","dominant_theme","dominant_lifecycle_event"],"title":"EntitySummaryItem"},"EntityTimelinePoint":{"properties":{"snapshot_id":{"type":"string","title":"Snapshot Id"},"mentions":{"type":"integer","title":"Mentions"},"total_posts":{"type":"integer","title":"Total Posts"},"avg_sentiment":{"type":"number","title":"Avg Sentiment"},"dominant_theme":{"type":"string","title":"Dominant Theme"},"dominant_lifecycle_event":{"type":"string","title":"Dominant Lifecycle Event"},"cluster_ids":{"items":{"type":"integer"},"type":"array","title":"Cluster Ids"}},"type":"object","required":["snapshot_id","mentions","total_posts","avg_sentiment","dominant_theme","dominant_lifecycle_event"],"title":"EntityTimelinePoint"},"EntityTimelineResponse":{"properties":{"entity_name":{"type":"string","title":"Entity Name"},"topic":{"type":"string","title":"Topic"},"timeline":{"items":{"$ref":"#/components/schemas/EntityTimelinePoint"},"type":"array","title":"Timeline"},"data_points":{"type":"integer","title":"Data Points"},"days":{"type":"integer","title":"Days"},"frame_index":{"type":"integer","title":"Frame Index"}},"type":"object","required":["entity_name","topic","data_points","days","frame_index"],"title":"EntityTimelineResponse"},"EntityTypeFilter":{"type":"string","enum":["all","PERSON","ORG","LOCATION","GPE","PRODUCT","EVENT","OTHER"],"title":"EntityTypeFilter"},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"HashIndicators":{"properties":{"md5":{"items":{"type":"string"},"type":"array","title":"Md5"},"sha1":{"items":{"type":"string"},"type":"array","title":"Sha1"},"sha256":{"items":{"type":"string"},"type":"array","title":"Sha256"}},"type":"object","title":"HashIndicators"},"HealthResponse":{"properties":{"status":{"type":"string","title":"Status","default":"ok"},"version":{"type":"string","title":"Version","default":"1.2.5"}},"type":"object","title":"HealthResponse"},"IndicatorCollection":{"properties":{"urls":{"items":{"type":"string"},"type":"array","title":"Urls"},"ips":{"items":{"type":"string"},"type":"array","title":"Ips"},"hashes":{"$ref":"#/components/schemas/HashIndicators"},"cves":{"items":{"type":"string"},"type":"array","title":"Cves"},"crypto_wallets":{"items":{"type":"string"},"type":"array","title":"Crypto Wallets"},"emails":{"items":{"type":"string"},"type":"array","title":"Emails"},"domains":{"items":{"type":"string"},"type":"array","title":"Domains"}},"type":"object","title":"IndicatorCollection"},"KeyResponse":{"properties":{"api_key":{"type":"string","title":"Api Key"},"client_id":{"type":"string","title":"Client Id"},"tier":{"type":"string","title":"Tier"},"topics":{"items":{"type":"string"},"type":"array","title":"Topics"},"webhook_limit":{"type":"integer","title":"Webhook Limit"},"rate_limit_rpm":{"type":"integer","title":"Rate Limit Rpm"},"active":{"type":"boolean","title":"Active"},"created_at":{"type":"string","format":"date-time","title":"Created At"},"expires_at":{"type":"string","format":"date-time","title":"Expires At"}},"type":"object","required":["api_key","client_id","tier","topics","webhook_limit","rate_limit_rpm","active","created_at","expires_at"],"title":"KeyResponse"},"MatchedCluster":{"properties":{"cluster_id":{"type":"integer","title":"Cluster Id"},"cluster_title":{"type":"string","title":"Cluster Title"},"narrative_context":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Narrative Context"}},"type":"object","required":["cluster_id","cluster_title"],"title":"MatchedCluster"},"MeKey":{"properties":{"key_id":{"type":"string","title":"Key Id"},"key_prefix":{"type":"string","title":"Key Prefix"},"tier":{"type":"string","title":"Tier"},"is_test_key":{"type":"boolean","title":"Is Test Key"},"is_trial":{"type":"boolean","title":"Is Trial"},"trial_expires_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Trial Expires At"}},"type":"object","required":["key_id","key_prefix","tier","is_test_key","is_trial","trial_expires_at"],"title":"MeKey"},"MeLimits":{"properties":{"rate_limit_per_minute":{"type":"integer","title":"Rate Limit Per Minute"},"rate_burst":{"type":"integer","title":"Rate Burst"},"watchlists_max":{"type":"integer","title":"Watchlists Max"},"watchlists_used":{"type":"integer","title":"Watchlists Used"},"watchlist_terms_max":{"type":"integer","title":"Watchlist Terms Max"},"subscriptions_max":{"type":"integer","title":"Subscriptions Max"},"subscriptions_used":{"type":"integer","title":"Subscriptions Used"}},"type":"object","required":["rate_limit_per_minute","rate_burst","watchlists_max","watchlists_used","watchlist_terms_max","subscriptions_max","subscriptions_used"],"title":"MeLimits"},"MeResponse":{"properties":{"client_id":{"type":"string","title":"Client Id"},"key":{"$ref":"#/components/schemas/MeKey"},"topics":{"items":{"type":"string"},"type":"array","title":"Topics"},"features":{"items":{"type":"string"},"type":"array","title":"Features"},"limits":{"$ref":"#/components/schemas/MeLimits"},"server_time":{"type":"string","title":"Server Time"},"api_version":{"type":"string","title":"Api Version"}},"type":"object","required":["client_id","key","topics","features","limits","server_time","api_version"],"title":"MeResponse"},"PostEvidence":{"properties":{"post_id":{"type":"string","title":"Post Id"},"cluster_id":{"type":"string","title":"Cluster Id"},"created_at":{"type":"string","title":"Created At"},"source_url":{"type":"string","title":"Source Url"},"source_domain":{"type":"string","title":"Source Domain"},"language":{"type":"string","title":"Language"},"source_type":{"type":"string","title":"Source Type"},"sentiment":{"type":"number","title":"Sentiment"},"content_snippet":{"type":"string","title":"Content Snippet"},"entities":{"items":{"type":"string"},"type":"array","title":"Entities"}},"type":"object","required":["post_id","cluster_id","created_at","source_url","source_domain","language","source_type","sentiment","content_snippet","entities"],"title":"PostEvidence"},"PostsResponse":{"properties":{"topic":{"type":"string","title":"Topic"},"scope_type":{"type":"string","title":"Scope Type"},"scope_value":{"type":"string","title":"Scope Value"},"count":{"type":"integer","title":"Count"},"posts":{"items":{"$ref":"#/components/schemas/PostEvidence"},"type":"array","title":"Posts"},"window":{"additionalProperties":{"type":"string"},"type":"object","title":"Window"},"truncated":{"type":"boolean","title":"Truncated","default":false},"match_mode":{"type":"string","title":"Match Mode","default":"keyword"}},"type":"object","required":["topic","scope_type","scope_value","count","posts","window"],"title":"PostsResponse"},"RevokeKeyResponse":{"properties":{"api_key":{"type":"string","title":"Api Key"},"revoked":{"type":"boolean","title":"Revoked"},"already_inactive":{"type":"boolean","title":"Already Inactive"}},"type":"object","required":["api_key","revoked","already_inactive"],"title":"RevokeKeyResponse"},"RotateKeyResponse":{"properties":{"old_api_key":{"type":"string","title":"Old Api Key","description":"The key that was just deactivated"},"new_api_key":{"type":"string","title":"New Api Key","description":"New key — start using immediately"},"client_id":{"type":"string","title":"Client Id"},"tier":{"type":"string","title":"Tier"},"topics":{"items":{"type":"string"},"type":"array","title":"Topics"},"webhook_limit":{"type":"integer","title":"Webhook Limit"},"rate_limit_rpm":{"type":"integer","title":"Rate Limit Rpm"},"expires_at":{"type":"string","format":"date-time","title":"Expires At"}},"type":"object","required":["old_api_key","new_api_key","client_id","tier","topics","webhook_limit","rate_limit_rpm","expires_at"],"title":"RotateKeyResponse"},"SortOrder":{"type":"string","enum":["asc","desc"],"title":"SortOrder"},"SubscriptionCreate":{"properties":{"topic":{"type":"string","title":"Topic","default":"global"},"subscription_type":{"type":"string","title":"Subscription Type"},"target":{"type":"string","maxLength":500,"minLength":1,"title":"Target"},"signals":{"items":{"type":"string"},"type":"array","title":"Signals"},"sensitivity":{"type":"string","title":"Sensitivity","default":"medium"},"min_domain_diversity":{"type":"integer","maximum":50.0,"minimum":1.0,"title":"Min Domain Diversity","default":3},"webhook_url":{"type":"string","title":"Webhook Url","default":""}},"type":"object","required":["subscription_type","target"],"title":"SubscriptionCreate"},"SubscriptionListResponse":{"properties":{"subscriptions":{"items":{"$ref":"#/components/schemas/SubscriptionOut"},"type":"array","title":"Subscriptions"},"count":{"type":"integer","title":"Count"}},"type":"object","required":["subscriptions","count"],"title":"SubscriptionListResponse"},"SubscriptionOut":{"properties":{"subscription_id":{"type":"string","title":"Subscription Id"},"client_id":{"type":"string","title":"Client Id"},"topic":{"type":"string","title":"Topic"},"subscription_type":{"type":"string","title":"Subscription Type"},"target":{"type":"string","title":"Target"},"signals":{"items":{"type":"string"},"type":"array","title":"Signals"},"sensitivity":{"type":"string","title":"Sensitivity"},"min_domain_diversity":{"type":"integer","title":"Min Domain Diversity"},"webhook_url":{"type":"string","title":"Webhook Url"},"active":{"type":"integer","title":"Active"},"created_at":{"type":"string","title":"Created At"}},"type":"object","required":["subscription_id","client_id","topic","subscription_type","target","signals","sensitivity","min_domain_diversity","webhook_url","active","created_at"],"title":"SubscriptionOut"},"TopicEntry":{"properties":{"topic":{"type":"string","title":"Topic"},"is_default":{"type":"boolean","title":"Is Default","default":false}},"type":"object","required":["topic"],"title":"TopicEntry"},"TopicsResponse":{"properties":{"topics":{"items":{"$ref":"#/components/schemas/TopicEntry"},"type":"array","title":"Topics"},"count":{"type":"integer","title":"Count"},"default_topic":{"type":"string","title":"Default Topic","default":"global"}},"type":"object","required":["topics","count"],"title":"TopicsResponse"},"TrialKeyRequest":{"properties":{"email":{"type":"string","maxLength":320,"minLength":3,"title":"Email","description":"Email address to associate with the trial key"}},"type":"object","required":["email"],"title":"TrialKeyRequest"},"TrialKeyResponse":{"properties":{"api_key":{"type":"string","title":"Api Key"},"client_id":{"type":"string","title":"Client Id"},"tier":{"type":"string","title":"Tier"},"topics":{"items":{"type":"string"},"type":"array","title":"Topics"},"webhook_limit":{"type":"integer","title":"Webhook Limit"},"rate_limit_rpm":{"type":"integer","title":"Rate Limit Rpm"},"active":{"type":"boolean","title":"Active"},"created_at":{"type":"string","format":"date-time","title":"Created At"},"expires_at":{"type":"string","format":"date-time","title":"Expires At"},"reused":{"type":"boolean","title":"Reused","description":"True if an existing still-valid trial key was returned instead of issued","default":false}},"type":"object","required":["api_key","client_id","tier","topics","webhook_limit","rate_limit_rpm","active","created_at","expires_at"],"title":"TrialKeyResponse"},"UsageResponse":{"properties":{"api_calls":{"type":"integer","title":"Api Calls"},"period":{"type":"string","title":"Period"},"tier":{"type":"string","title":"Tier"},"client_id":{"type":"string","title":"Client Id"}},"type":"object","required":["api_calls","period","tier","client_id"],"title":"UsageResponse"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"},"VersionResponse":{"properties":{"name":{"type":"string","title":"Name","default":"Exorde Intel API"},"version":{"type":"string","title":"Version","default":"1.2.5"},"uptime_seconds":{"type":"integer","title":"Uptime Seconds","default":0}},"type":"object","title":"VersionResponse"},"WatchlistCreate":{"properties":{"name":{"type":"string","title":"Name","description":"Human-friendly name (≤64 chars)."},"base_topic":{"type":"string","title":"Base Topic","description":"Curated topic this watchlist narrows (default 'global').","default":"global"},"terms":{"items":{"$ref":"#/components/schemas/WatchlistTerm"},"type":"array","title":"Terms","description":"Match terms. At least one required."}},"type":"object","required":["name"],"title":"WatchlistCreate"},"WatchlistPatch":{"properties":{"name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Name"},"base_topic":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Base Topic"},"terms":{"anyOf":[{"items":{"$ref":"#/components/schemas/WatchlistTerm"},"type":"array"},{"type":"null"}],"title":"Terms"},"active":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Active"}},"type":"object","title":"WatchlistPatch"},"WatchlistTerm":{"properties":{"type":{"type":"string","title":"Type","description":"keyword|phrase|entity|domain"},"value":{"type":"string","title":"Value","description":"The term value (≤128 chars, stripped)."}},"type":"object","required":["type","value"],"title":"WatchlistTerm"},"ErrorResponse":{"type":"object","required":["error","message"],"properties":{"error":{"type":"string","example":"tier_denied"},"message":{"type":"string","example":"This endpoint requires See tier or higher."},"field":{"type":"string","nullable":true},"details":{"type":"object","additionalProperties":true,"nullable":true}},"title":"ErrorResponse"}},"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"X-API-Key","description":"Tier-prefixed key. Issued prefixes: exd_watch_, exd_see_, exd_know_, exd_trial_, exd_test_. Mint a trial via POST /v1/keys/trial."}}},"tags":[{"name":"System","description":"Health, version, status, topic catalog, usage."},{"name":"Auth & Keys","description":"Trial key issuance."},{"name":"Me","description":"Authenticated identity and entitlements."},{"name":"Alerts","description":"Validated alert events per topic."},{"name":"Trending","description":"Rising keywords, entities, domains, languages."},{"name":"Volume","description":"Bucketed time-series and keyword volume."},{"name":"Clusters","description":"Story clusters, lifecycle, and evidence posts."},{"name":"Entities","description":"Entities, co-occurrence, timeline, and evidence posts."},{"name":"Narratives","description":"Topic narratives, history, and evidence posts."},{"name":"Search","description":"Semantic search over topic FAISS indexes."},{"name":"Platforms","description":"Domain and platform breakdowns per topic."},{"name":"Reports","description":"Weekly executive reports (Know tier)."},{"name":"Watchlists","description":"Watchlist CRUD, analytics, and alerts."},{"name":"Subscriptions","description":"Alert delivery subscriptions."}],"servers":[{"url":"https://intel-v1.exorde.io","description":"Production"}],"security":[{"ApiKeyAuth":[]}]}