{ "openapi": "3.1.0", "info": { "title": "AudioAlpha API", "version": "1.0.0", "description": "Market sentiment and narrative intelligence derived from podcast analysis.\n\n**Getting Started:**\n1. Generate your API key at https://audioalpha.io/account\n2. Include the key in requests as: Authorization: Bearer YOUR_API_KEY\n\n**MCP (Claude Integration):**\nConnect to Claude Desktop by adding to your config:\n```json\n\"mcpServers\": {\n \"audioalpha\": {\n \"command\": \"npx\",\n \"args\": [\"mcp-remote\", \"https://www.audioalpha.io/api/mcp?apiKey=YOUR_KEY\"]\n }\n}\n```", "contact": { "url": "https://audioalpha.io", "email": "team@audioalpha.io" } }, "servers": [ { "url": "https://www.audioalpha.io/api/v1", "description": "Production" } ], "security": [ { "bearerAuth": [] } ], "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "description": "API key generated from https://audioalpha.io/account" } }, "schemas": { "Error": { "type": "object", "properties": { "error": { "type": "string" } } }, "MarketSnapshot": { "type": "object", "properties": { "snapshot_date": { "type": "string", "description": "Date of the snapshot", "example": "2025-03-14", "format": "date" }, "status": { "type": "string", "description": "Generation status of the parent daily snapshot. \"completed\" once the snapshot has finished generating (the normal case); \"writing\" while it is being (re)generated, typically during the 00:00–00:01 UTC build window. Always present in the response.", "example": "completed" }, "version_num": { "type": "integer", "description": "Revision number of this snapshot. 1 = first generation, higher = later revision. Only present when version_info=true.", "example": 1 }, "version_label": { "type": "string", "description": "Human-readable label for this version (e.g. \"eod_utc\", \"backfill\", \"revised\"). Only present when version_info=true.", "example": "eod_utc" }, "regime": { "type": "string", "description": "Current market regime", "example": "bullish accumulation" }, "regime_justification": { "type": "string", "description": "Explanation of the regime classification" }, "market_sentiment_mean": { "type": "number", "description": "α-sentiment mean across all episodes (0-10 scale, higher = more bullish)", "example": 6.2 }, "market_sentiment_median": { "type": "number", "description": "α-sentiment median across all episodes (0-10 scale)", "example": 6.1 }, "market_sentiment_std": { "type": "number", "description": "Standard deviation of α-sentiment scores", "example": 1.3 }, "sentiment_open": { "type": "number", "description": "α-sentiment of first podcast of the day (0-10 scale)", "example": 5.8 }, "sentiment_high": { "type": "number", "description": "Highest α-sentiment of last podcast of the day (0-10 scale)", "example": 7.2 }, "sentiment_low": { "type": "number", "description": "Lowest α-sentiment of the day (0-10 scale)", "example": 5.1 }, "sentiment_close": { "type": "number", "description": "α-sentiment at market close (0-10 scale)", "example": 6.5 }, "sentiment_delta_1d": { "type": "number", "description": "Change in α-sentiment vs yesterday (-10 to +10)", "example": -0.3 }, "sentiment_delta_7d": { "type": "number", "description": "Change in α-sentiment vs 7 days ago (-10 to +10)", "example": 1.2 }, "episode_count": { "type": "integer", "description": "Number of podcast episodes analyzed", "example": 24 }, "consensus_score": { "type": "number", "description": "Agreement among podcast hosts (0-1, higher = more agreement)", "example": 0.78 }, "sentiment_zscore": { "type": "number", "description": "α-sentiment standard deviations from historical mean (-3 to +3)", "example": 1.2 }, "sentiment_strength_index": { "type": "number", "description": "Strength of the α-sentiment signal", "example": 0.65 }, "headline": { "type": "string", "description": "Headline summarizing the day" }, "daily_narrative_summary": { "type": "string", "description": "Narrative summary of the day's discussions" }, "market_psychology_summary": { "type": "string", "description": "Analysis of market psychology from podcast content" }, "delta_narrative": { "type": "string", "description": "Explanation of recent market changes" }, "key_tensions": { "type": "array", "description": "Key market tensions identified in podcast discussions", "items": { "type": "object" } }, "surprise_mentions": { "type": "array", "description": "Unexpected or surprising topics that emerged", "items": { "type": "object" } }, "wordcloud": { "type": "object", "description": "Word frequency data for visualization" } } }, "Theme": { "type": "object", "properties": { "theme_snap_id": { "type": "string", "description": "Unique theme snapshot identifier" }, "status": { "type": "string", "description": "Generation status of the parent daily snapshot. \"completed\" once the snapshot has finished generating (the normal case); \"writing\" while it is being (re)generated, typically during the 00:00–00:01 UTC build window. Always present in the response.", "example": "completed" }, "version_num": { "type": "integer", "description": "Revision number of the parent snapshot. Only present when version_info=true.", "example": 1 }, "version_label": { "type": "string", "description": "Version label of the parent snapshot (e.g. \"eod_utc\", \"backfill\"). Only present when version_info=true.", "example": "eod_utc" }, "title": { "type": "string", "description": "Theme title", "example": "Bitcoin ETF Inflows Accelerating" }, "summary": { "type": "string", "description": "Summary of the theme" }, "pod_coverage": { "type": "integer", "description": "Number of podcasts discussing this theme", "example": 8 }, "fragility_score": { "type": "number", "description": "How fragile/unstable the narrative is (0-1)", "example": 0.35 }, "novelty_score": { "type": "number", "description": "How new or surprising the theme is (0-1)", "example": 0.72 }, "persistency_score": { "type": "number", "description": "How persistent the theme has been over time (0-1)", "example": 0.85 }, "counterfactual_narrative": { "type": "string", "description": "What the opposite narrative would look like" } } }, "Signal": { "type": "object", "properties": { "ticker": { "type": "string", "description": "Asset ticker symbol — crypto tickers are suffixed with \"-USD\" (e.g. SOL-USD)", "example": "SOL-USD" }, "status": { "type": "string", "description": "Generation status of the parent daily snapshot. \"completed\" once the snapshot has finished generating (the normal case); \"writing\" while it is being (re)generated, typically during the 00:00–00:01 UTC build window. Always present in the response.", "example": "completed" }, "version_num": { "type": "integer", "description": "Revision number of the parent snapshot. Only present when version_info=true.", "example": 1 }, "version_label": { "type": "string", "description": "Version label of the parent snapshot (e.g. \"eod_utc\", \"backfill\"). Only present when version_info=true.", "example": "eod_utc" }, "signal_type": { "type": "string", "description": "Type of signal (bullish/bearish/neutral)", "example": "bullish" }, "horizon": { "type": "string", "description": "Time horizon for the signal", "example": "short-term" }, "scenario": { "type": "string", "description": "Description of the expected scenario" }, "trigger": { "type": "string", "description": "Conditions that would trigger this scenario" }, "narrative_basis": { "type": "string", "description": "The narrative reasoning behind the signal" }, "confidence": { "type": "number", "description": "Confidence level of the signal (0-1)", "example": 0.75 }, "invalidating_condition": { "type": "string", "description": "Conditions that would invalidate this signal" } } }, "Quote": { "type": "object", "properties": { "quote": { "type": "string", "description": "The extracted quote text" }, "status": { "type": "string", "description": "Generation status of the parent daily snapshot. \"completed\" once the snapshot has finished generating (the normal case); \"writing\" while it is being (re)generated, typically during the 00:00–00:01 UTC build window. Always present in the response.", "example": "completed" }, "version_num": { "type": "integer", "description": "Revision number of the parent snapshot. Only present when version_info=true.", "example": 1 }, "version_label": { "type": "string", "description": "Version label of the parent snapshot (e.g. \"eod_utc\", \"backfill\"). Only present when version_info=true.", "example": "eod_utc" }, "speaker": { "type": "string", "description": "Name of the speaker", "example": "Laura Shin" }, "sentiment_score": { "type": "number", "description": "α-sentiment score of the quote (0-10 scale)", "example": 7.5 }, "sentiment_category": { "type": "string", "description": "α-sentiment category (bearish/neutral/bullish)", "example": "bullish" }, "ticker": { "type": "string", "description": "Asset ticker the quote refers to (if applicable) — crypto tickers are suffixed with \"-USD\" (e.g. ETH-USD)", "example": "ETH-USD" }, "episode_id": { "type": "string", "description": "ID of the episode containing this quote", "example": "152cICc54xb" } } }, "Episode": { "type": "object", "properties": { "episode_id": { "type": "string", "description": "Unique episode identifier", "example": "152cICc54xb" }, "display_title": { "type": "string", "description": "Episode title", "example": "Bitcoin's Next Move: Expert Analysis" }, "subtitle": { "type": "string", "description": "Episode subtitle", "example": "Some more info on episode" }, "published_utc_date": { "type": "string", "description": "Publication date in UTC", "example": "2025-03-14", "format": "date" }, "duration_seconds": { "type": "integer", "description": "Episode duration in seconds", "example": 3600 }, "crypto_sentiment_score": { "type": "number", "description": "α-sentiment score for the episode (0-10 scale)", "example": 7.1 }, "market_sentiment_category": { "type": "string", "description": "α-sentiment category (bearish/neutral/bullish)", "example": "bullish" }, "trad_sentiment_score": { "type": "number", "description": "Sentiment about traditional financial markets, not crypto (0-10 scale)", "example": 5.5 }, "transcript_summary": { "type": "string", "description": "Summary of the episode transcript" }, "mp3_url": { "type": "string", "description": "URL to the episode mp3", "example": "https://podcast.example.com/episode/123.mp3", "format": "uri" }, "episode_artwork": { "type": "string", "description": "URL to episode artwork image", "format": "uri" } } }, "EpisodeFull": { "type": "object", "properties": { "episode_id": { "type": "string", "description": "Unique episode identifier", "example": "152cICc54xb" }, "display_title": { "type": "string", "description": "Episode title", "example": "Bitcoin's Next Move: Expert Analysis" }, "subtitle": { "type": "string", "description": "Episode subtitle", "example": "Some more info on episode" }, "published_utc_date": { "type": "string", "description": "Publication date in UTC", "example": "2025-03-14", "format": "date" }, "duration_seconds": { "type": "integer", "description": "Episode duration in seconds", "example": 3600 }, "crypto_sentiment_score": { "type": "number", "description": "α-sentiment score for the episode (0-10 scale)", "example": 7.1 }, "market_sentiment_category": { "type": "string", "description": "α-sentiment category (bearish/neutral/bullish)", "example": "bullish" }, "trad_sentiment_score": { "type": "number", "description": "Sentiment about traditional financial markets, not crypto (0-10 scale)", "example": 5.5 }, "transcript_summary": { "type": "string", "description": "Summary of the episode transcript" }, "mp3_url": { "type": "string", "description": "URL to the episode mp3", "example": "https://podcast.example.com/episode/123.mp3", "format": "uri" }, "episode_artwork": { "type": "string", "description": "URL to episode artwork image", "format": "uri" }, "quotes": { "type": "array", "description": "Extracted quotes from the episode with speaker and α-sentiment", "example": [ { "quote": "Bitcoin is...", "speaker": "Sid Powell", "sentiment_score": 8, "sentiment_category": "positive", "ticker": "BTC-USD" } ] }, "asset_mentions": { "type": "array", "description": "Assets mentioned in the episode with α-sentiment scores", "example": [ { "ticker": "USDC-USD", "sentiment_score": 7.5, "mention_count": 3 } ] } } }, "AssetSnapshot": { "type": "object", "properties": { "ticker": { "type": "string", "description": "Asset ticker symbol — crypto tickers are suffixed with \"-USD\" (e.g. BTC-USD)", "example": "BTC-USD" }, "status": { "type": "string", "description": "Generation status of the parent daily snapshot. \"completed\" once the snapshot has finished generating (the normal case); \"writing\" while it is being (re)generated, typically during the 00:00–00:01 UTC build window. Always present in the response.", "example": "completed" }, "version_num": { "type": "integer", "description": "Revision number of the parent snapshot. Only present when version_info=true.", "example": 1 }, "version_label": { "type": "string", "description": "Version label of the parent snapshot (e.g. \"eod_utc\", \"backfill\"). Only present when version_info=true.", "example": "eod_utc" }, "alpha_index": { "type": "number", "description": "Composite narrative strength score (0-1) combining sentiment level, historical deviation, host consensus, and coverage reach", "example": 0.72 }, "alpha_pulse": { "type": "number", "description": "Composite narrative momentum score (0-1) measuring how rapidly the podcast narrative is accelerating", "example": 0.58 }, "episode_count": { "type": "integer", "description": "Number of episodes mentioning this asset", "example": 12 }, "attention_share": { "type": "number", "description": "Proportion of mentions this asset received (0-1)", "example": 0.35 }, "days_since_last_mention": { "type": "integer", "description": "Days since asset was last mentioned", "example": 0 }, "sentiment_mean": { "type": "number", "description": "α-sentiment mean for this asset (0-10 scale)", "example": 6.8 }, "sentiment_median": { "type": "number", "description": "α-sentiment median for this asset (0-10 scale)", "example": 6.5 }, "sentiment_std": { "type": "number", "description": "Standard deviation of α-sentiment scores", "example": 1.1 }, "sentiment_open": { "type": "number", "description": "α-sentiment of first podcast of the day (0-10 scale)", "example": 6 }, "sentiment_high": { "type": "number", "description": "Highest α-sentiment of the day (0-10 scale)", "example": 7.5 }, "sentiment_low": { "type": "number", "description": "Lowest α-sentiment of the day (0-10 scale)", "example": 5.2 }, "sentiment_close": { "type": "number", "description": "α-sentiment of last podcast of the day (0-10 scale)", "example": 7 }, "sentiment_delta_1d": { "type": "number", "description": "Change in α-sentiment vs yesterday (-10 to +10)", "example": 0.5 }, "sentiment_delta_7d": { "type": "number", "description": "Change in α-sentiment vs 7 days ago (-10 to +10)", "example": 1.8 }, "bull_ratio": { "type": "number", "description": "Proportion of bullish mentions (0-1)", "example": 0.65 }, "bear_ratio": { "type": "number", "description": "Proportion of bearish mentions (0-1)", "example": 0.15 }, "neutral_ratio": { "type": "number", "description": "Proportion of neutral mentions (0-1)", "example": 0.2 }, "consensus_score": { "type": "number", "description": "Agreement among hosts about this asset (0-1)", "example": 0.82 }, "surprise_score": { "type": "number", "description": "How surprising the narrative is vs historical (0-1)", "example": 0.35 }, "novelty_score": { "type": "number", "description": "How new or surprising the narrative is (0-1)", "example": 0.42 }, "sentiment_momentum": { "type": "number", "description": "Trend direction and strength of α-sentiment", "example": 0.15 }, "narrative_intensity": { "type": "number", "description": "Intensity of discussion about this asset", "example": 0.72 }, "narrative_intensity_norm": { "type": "number", "description": "Normalized narrative intensity (0-1)", "example": 0.68 }, "summary": { "type": "string", "description": "Summary of discussions about this asset" }, "spider_chart_url": { "type": "string", "description": "AudioAlpha spider chart URL, showing daily insight into the asset: α-sentiment, consensus, novelty, attention, and narrative intensity", "example": "https://quickchart.io/chart?c=...", "format": "uri" } } }, "Podcast": { "type": "object", "properties": { "podcast_id": { "type": "string", "description": "Unique podcast identifier", "example": "1123922160" }, "podcast_name": { "type": "string", "description": "Podcast name", "example": "Unchained" }, "artist_name": { "type": "string", "description": "Podcast host/artist name", "example": "Laura Shin" }, "language": { "type": "string", "description": "Podcast language code", "example": "en" }, "podcast_artwork": { "type": "string", "description": "URL to podcast artwork", "format": "uri" }, "podcast_link": { "type": "string", "description": "URL to original podcast page", "format": "uri" }, "x_handle": { "type": "string", "description": "x.com handle without @", "example": "scottmelker" } } }, "Transcript": { "type": "object", "properties": { "episode_id": { "type": "string", "description": "Unique episode identifier", "example": "3e48knEtPKI" }, "display_title": { "type": "string", "description": "Episode title", "example": "Is the DeFi Mullet Strategy the Best Way to Bring Finance Onchain?" }, "speaker_transcript": { "type": "array", "description": "Array of transcript segments: [speaker_id, start_time, end_time, text]", "example": [ [ "SPEAKER_00", 0.031, 53.921, "Welcome to Unchained, your no-hype resource for all things crypto..." ] ] }, "speaker_map": { "type": "object", "description": "Mapping of speaker IDs to speaker names", "example": { "SPEAKER_00": "Laura Shin", "SPEAKER_01": "Sid Powell", "SPEAKER_02": "Paul Frambeau" } } } }, "LeaderboardEntry": { "type": "object", "properties": { "ticker": { "type": "string", "description": "Asset ticker symbol — crypto tickers are suffixed with \"-USD\" (e.g. BTC-USD)", "example": "BTC-USD" }, "status": { "type": "string", "description": "Generation status of the parent daily snapshot. \"completed\" once the snapshot has finished generating (the normal case); \"writing\" while it is being (re)generated, typically during the 00:00–00:01 UTC build window. Always present in the response.", "example": "completed" }, "version_num": { "type": "integer", "description": "Revision number of the parent snapshot. Only present when version_info=true.", "example": 1 }, "version_label": { "type": "string", "description": "Version label of the parent snapshot (e.g. \"eod_utc\", \"backfill\"). Only present when version_info=true.", "example": "eod_utc" }, "alpha_index": { "type": "number", "description": "Composite narrative strength score (0-1) combining sentiment level, historical deviation, host consensus, and coverage reach", "example": 0.72 }, "alpha_pulse": { "type": "number", "description": "Composite narrative momentum score (0-1) measuring how rapidly the podcast narrative is accelerating", "example": 0.58 }, "episode_count": { "type": "integer", "description": "Number of episodes mentioning this asset", "example": 12 }, "attention_share": { "type": "number", "description": "Proportion of mentions this asset received (0-1)", "example": 0.35 }, "days_since_last_mention": { "type": "integer", "description": "Days since asset was last mentioned", "example": 0 }, "sentiment_mean": { "type": "number", "description": "α-sentiment mean for this asset (0-10 scale)", "example": 6.8 }, "sentiment_median": { "type": "number", "description": "α-sentiment median for this asset (0-10 scale)", "example": 6.5 }, "sentiment_std": { "type": "number", "description": "Standard deviation of α-sentiment scores", "example": 1.1 }, "sentiment_open": { "type": "number", "description": "α-sentiment of first podcast of the day (0-10 scale)", "example": 6 }, "sentiment_high": { "type": "number", "description": "Highest α-sentiment of the day (0-10 scale)", "example": 7.5 }, "sentiment_low": { "type": "number", "description": "Lowest α-sentiment of the day (0-10 scale)", "example": 5.2 }, "sentiment_close": { "type": "number", "description": "α-sentiment of last podcast of the day (0-10 scale)", "example": 7 }, "sentiment_delta_1d": { "type": "number", "description": "Change in α-sentiment vs yesterday (-10 to +10)", "example": 0.5 }, "sentiment_delta_7d": { "type": "number", "description": "Change in α-sentiment vs 7 days ago (-10 to +10)", "example": 1.8 }, "bull_ratio": { "type": "number", "description": "Proportion of bullish mentions (0-1)", "example": 0.65 }, "bear_ratio": { "type": "number", "description": "Proportion of bearish mentions (0-1)", "example": 0.15 }, "neutral_ratio": { "type": "number", "description": "Proportion of neutral mentions (0-1)", "example": 0.2 }, "consensus_score": { "type": "number", "description": "Agreement among hosts about this asset (0-1)", "example": 0.82 }, "surprise_score": { "type": "number", "description": "How surprising the narrative is vs historical (0-1)", "example": 0.35 }, "novelty_score": { "type": "number", "description": "How new or surprising the narrative is (0-1)", "example": 0.42 }, "sentiment_momentum": { "type": "number", "description": "Trend direction and strength of α-sentiment", "example": 0.15 }, "narrative_intensity": { "type": "number", "description": "Intensity of discussion about this asset", "example": 0.72 }, "narrative_intensity_norm": { "type": "number", "description": "Normalized narrative intensity (0-1)", "example": 0.68 }, "summary": { "type": "string", "description": "Summary of discussions about this asset" }, "category": { "type": "string", "description": "Leaderboard category (top_alpha_index, top_alpha_pulse, top_riser, top_dropper, most_mentioned, most_surprising)", "example": "top_riser" }, "value": { "type": "number", "description": "Primary metric value for this category", "example": 0.6 } } }, "LeaderboardHighlights": { "type": "object", "properties": { "top_alpha_index": { "allOf": [ { "$ref": "#/components/schemas/LeaderboardEntry" } ], "description": "Asset with highest surprise score", "example": { "ticker": "BTC-USD", "alpha_index": 0.88, "alpha_pulse": 0.75, "episode_count": 6, "attention_share": 0.12, "days_since_last_mention": 0, "sentiment_mean": 6.8, "sentiment_median": 6.7, "sentiment_std": 0.8, "sentiment_open": 6, "sentiment_high": 7.5, "sentiment_low": 6, "sentiment_close": 7.2, "sentiment_delta_1d": 0.2, "sentiment_delta_7d": 0.8, "bull_ratio": 0.62, "bear_ratio": 0.18, "neutral_ratio": 0.2, "consensus_score": 0.72, "surprise_score": 0.82, "novelty_score": 0.55, "sentiment_momentum": 0.12, "narrative_intensity": 0.58, "narrative_intensity_norm": 0.55, "summary": "BTC solid positive sentiment with strong narrative intensity...", "category": "top_alpha_index", "value": 0.82 } }, "top_alpha_pulse": { "allOf": [ { "$ref": "#/components/schemas/LeaderboardEntry" } ], "description": "Asset with highest surprise score", "example": { "ticker": "LINK-USD", "alpha_index": 0.68, "alpha_pulse": 0.95, "episode_count": 6, "attention_share": 0.12, "days_since_last_mention": 0, "sentiment_mean": 6.8, "sentiment_median": 6.7, "sentiment_std": 0.8, "sentiment_open": 6, "sentiment_high": 7.5, "sentiment_low": 6, "sentiment_close": 7.2, "sentiment_delta_1d": 0.2, "sentiment_delta_7d": 0.8, "bull_ratio": 0.62, "bear_ratio": 0.18, "neutral_ratio": 0.2, "consensus_score": 0.72, "surprise_score": 0.82, "novelty_score": 0.55, "sentiment_momentum": 0.12, "narrative_intensity": 0.58, "narrative_intensity_norm": 0.55, "summary": "LINK stealing a lot of narrative...", "category": "top_alpha_pulse", "value": 0.82 } }, "top_riser": { "allOf": [ { "$ref": "#/components/schemas/LeaderboardEntry" } ], "description": "Asset with highest positive sentiment change", "example": { "ticker": "SOL-USD", "alpha_index": 0.78, "alpha_pulse": 0.72, "episode_count": 8, "attention_share": 0.15, "days_since_last_mention": 0, "sentiment_mean": 7.2, "sentiment_median": 7, "sentiment_std": 0.9, "sentiment_open": 6.5, "sentiment_high": 8, "sentiment_low": 6.2, "sentiment_close": 7.5, "sentiment_delta_1d": 0.6, "sentiment_delta_7d": 1.2, "bull_ratio": 0.72, "bear_ratio": 0.12, "neutral_ratio": 0.16, "consensus_score": 0.78, "surprise_score": 0.35, "novelty_score": 0.42, "sentiment_momentum": 0.18, "narrative_intensity": 0.65, "narrative_intensity_norm": 0.62, "summary": "SOL showing strong momentum...", "category": "top_riser", "value": 0.6 } }, "top_dropper": { "allOf": [ { "$ref": "#/components/schemas/LeaderboardEntry" } ], "description": "Asset with largest negative sentiment change", "example": { "ticker": "DOGE-USD", "alpha_index": 0.42, "alpha_pulse": 0.28, "episode_count": 4, "attention_share": 0.08, "days_since_last_mention": 0, "sentiment_mean": 4.1, "sentiment_median": 4, "sentiment_std": 1.2, "sentiment_open": 5, "sentiment_high": 5.2, "sentiment_low": 3.5, "sentiment_close": 3.8, "sentiment_delta_1d": -0.8, "sentiment_delta_7d": -1.5, "bull_ratio": 0.25, "bear_ratio": 0.55, "neutral_ratio": 0.2, "consensus_score": 0.65, "surprise_score": 0.45, "novelty_score": 0.32, "sentiment_momentum": -0.22, "narrative_intensity": 0.48, "narrative_intensity_norm": 0.45, "summary": "DOGE facing headwinds...", "category": "top_dropper", "value": -0.8 } }, "most_mentioned": { "allOf": [ { "$ref": "#/components/schemas/LeaderboardEntry" } ], "description": "Asset with highest attention share", "example": { "ticker": "BTC-USD", "alpha_index": 0.85, "alpha_pulse": 0.52, "episode_count": 18, "attention_share": 0.35, "days_since_last_mention": 0, "sentiment_mean": 6.5, "sentiment_median": 6.4, "sentiment_std": 1, "sentiment_open": 6.2, "sentiment_high": 7, "sentiment_low": 5.8, "sentiment_close": 6.6, "sentiment_delta_1d": 0.1, "sentiment_delta_7d": 0.4, "bull_ratio": 0.58, "bear_ratio": 0.22, "neutral_ratio": 0.2, "consensus_score": 0.82, "surprise_score": 0.22, "novelty_score": 0.28, "sentiment_momentum": 0.05, "narrative_intensity": 0.85, "narrative_intensity_norm": 0.82, "summary": "BTC dominates discussion...", "category": "most_mentioned", "value": 0.35 } }, "most_surprising": { "allOf": [ { "$ref": "#/components/schemas/LeaderboardEntry" } ], "description": "Asset with highest surprise score", "example": { "ticker": "LINK-USD", "alpha_index": 0.68, "alpha_pulse": 0.75, "episode_count": 6, "attention_share": 0.12, "days_since_last_mention": 0, "sentiment_mean": 6.8, "sentiment_median": 6.7, "sentiment_std": 0.8, "sentiment_open": 6, "sentiment_high": 7.5, "sentiment_low": 6, "sentiment_close": 7.2, "sentiment_delta_1d": 0.2, "sentiment_delta_7d": 0.8, "bull_ratio": 0.62, "bear_ratio": 0.18, "neutral_ratio": 0.2, "consensus_score": 0.72, "surprise_score": 0.82, "novelty_score": 0.55, "sentiment_momentum": 0.12, "narrative_intensity": 0.58, "narrative_intensity_norm": 0.55, "summary": "LINK surprising the market...", "category": "most_surprising", "value": 0.82 } } } }, "FeedSignal": { "type": "object", "properties": { "ticker": { "type": "string", "description": "Asset ticker symbol — crypto tickers are suffixed with \"-USD\" (e.g. ETH-USD)", "example": "ETH-USD" }, "signal_type": { "type": "string", "description": "Type of signal (accumulation, volatility_risk, momentum_breakout, liquidity_crisis)", "example": "volatility_risk" }, "horizon": { "type": "string", "description": "Time horizon (24h, 7d, 30d)", "example": "24h" }, "scenario": { "type": "string", "description": "Description of the expected scenario" }, "trigger": { "type": "string", "description": "Conditions that would trigger this scenario" }, "confidence": { "type": "number", "description": "Confidence level of the signal (0-1)", "example": 0.85 }, "invalidating_condition": { "type": "string", "description": "Conditions that would invalidate this signal" } } }, "FeedQuote": { "type": "object", "properties": { "rank": { "type": "integer", "description": "Relevance rank of the quote", "example": 1 }, "selection_reason": { "type": "string", "description": "Why this quote was selected for the feed" }, "quotes": { "allOf": [ { "$ref": "#/components/schemas/Quote" } ], "description": "The quote object with speaker, text, and sentiment", "example": { "quote": "Bitcoin has quietly rallied to $74,000...", "ticker": "BTC-USD", "speaker": "Nico", "episode_id": "lcfIvTX1FlC", "sentiment_score": 9, "sentiment_category": "positive" } } } }, "FeedAssetSnapshot": { "type": "object", "properties": { "ticker": { "type": "string", "description": "Asset ticker symbol — crypto tickers are suffixed with \"-USD\" (e.g. ETH-USD)", "example": "ETH-USD" }, "status": { "type": "string", "description": "Generation status of the parent daily snapshot. \"completed\" once the snapshot has finished generating (the normal case); \"writing\" while it is being (re)generated, typically during the 00:00–00:01 UTC build window. Always present in the response.", "example": "completed" }, "episode_count": { "type": "integer", "description": "Number of episodes mentioning this asset", "example": 16 }, "attention_share": { "type": "number", "description": "Proportion of mentions (0-1)", "example": 0.47 }, "sentiment_mean": { "type": "number", "description": "α-sentiment mean (0-10 scale)", "example": 6.4 }, "sentiment_delta_1d": { "type": "number", "description": "Change vs yesterday (-10 to +10)", "example": -0.6 }, "sentiment_delta_7d": { "type": "number", "description": "Change vs 7 days ago", "example": 0 }, "bull_ratio": { "type": "number", "description": "Proportion of bullish mentions (0-1)", "example": 0.5 }, "bear_ratio": { "type": "number", "description": "Proportion of bearish mentions (0-1)", "example": 0.0625 }, "neutral_ratio": { "type": "number", "description": "Proportion of neutral mentions (0-1)", "example": 0.4375 }, "consensus_score": { "type": "number", "description": "Host agreement (0-1)", "example": 0.26 }, "sentiment_momentum": { "type": "number", "description": "Trend direction and strength", "example": -0.44 }, "narrative_intensity_norm": { "type": "number", "description": "Normalized narrative intensity (0-1)", "example": 1 }, "summary": { "type": "string", "description": "AI-generated summary of discussions about this asset" } } }, "FeedAssetEntry": { "type": "object", "properties": { "ticker": { "type": "string", "description": "Asset ticker symbol — crypto tickers are suffixed with \"-USD\" (e.g. ETH-USD)", "example": "ETH-USD" }, "snapshot": { "allOf": [ { "$ref": "#/components/schemas/FeedAssetSnapshot" } ], "description": "Daily snapshot data for the asset (null if no mentions)", "example": { "ticker": "ETH-USD", "episode_count": 16, "attention_share": 0.47, "sentiment_mean": 6.4, "sentiment_delta_1d": -0.6, "sentiment_delta_7d": 0, "bull_ratio": 0.5, "bear_ratio": 0.0625, "neutral_ratio": 0.4375, "consensus_score": 0.26, "sentiment_momentum": -0.44, "narrative_intensity_norm": 1, "summary": "Ether is framed as a core alt to buy..." } }, "signals": { "type": "array", "description": "Trading signals for this asset", "example": [ { "ticker": "ETH-USD", "signal_type": "liquidity_crisis", "horizon": "24h", "scenario": "Immediate liquidity squeeze...", "trigger": "Continued on-chain movement...", "confidence": 0.85, "invalidating_condition": "Full recovery of traced funds..." } ], "items": { "$ref": "#/components/schemas/FeedSignal" } }, "quotes": { "type": "array", "description": "Relevant quotes about this asset", "example": [ { "rank": 1, "selection_reason": "Market hook highlighting stealth rally", "quotes": { "quote": "Bitcoin has quietly rallied to $74,000...", "ticker": "BTC-USD", "speaker": "Nico", "episode_id": "lcfIvTX1FlC", "sentiment_score": 9, "sentiment_category": "positive" } } ], "items": { "$ref": "#/components/schemas/FeedQuote" } } } }, "FeedPodcastEntry": { "type": "object", "properties": { "podcast_id": { "type": "string", "description": "Unique podcast identifier", "example": "1414384043" }, "podcast_name": { "type": "string", "description": "Podcast name", "example": "CoinDesk Podcast Network" }, "episodes": { "type": "array", "description": "Recent episodes from this podcast", "example": [ { "episode_id": "aJPaLpxH1Y9", "episode_title": "FTX to Repay Creditors Another $2.2B This Month", "published_utc_date": "2026-03-19", "crypto_sentiment_score": 3, "market_sentiment_category": "negative" } ], "items": { "$ref": "#/components/schemas/Episode" } } } }, "PersonalizedFeed": { "type": "object", "properties": { "snapshot_date": { "type": "string", "description": "Date of the feed snapshot", "example": "2026-03-18", "format": "date" }, "status": { "type": "string", "description": "Generation status of the parent daily snapshot. \"completed\" once the snapshot has finished generating (the normal case); \"writing\" while it is being (re)generated, typically during the 00:00–00:01 UTC build window. Always present in the response.", "example": "completed" }, "assets": { "type": "array", "description": "Array of favorited assets with their daily snapshots, signals, and quotes", "example": [ { "ticker": "BTC-USD", "snapshot": { "ticker": "BTC-USD", "episode_count": 31, "attention_share": 0.91, "sentiment_mean": 6.8, "sentiment_delta_1d": -0.6, "sentiment_delta_7d": 0.2, "bull_ratio": 0.61, "bear_ratio": 0.16, "neutral_ratio": 0.23, "consensus_score": 0.11, "sentiment_momentum": -0.23, "narrative_intensity_norm": 1, "summary": "Bitcoin quietly rallied to ~$74k on heavy podcast coverage..." }, "signals": [ { "ticker": "BTC-USD", "signal_type": "accumulation", "horizon": "30d", "scenario": "Sustained institutional accumulation...", "trigger": "Continued on-book accumulation...", "confidence": 0.85, "invalidating_condition": "Observable large ETF outflows..." } ], "quotes": [ { "rank": 1, "selection_reason": "Concise market hook", "quotes": { "quote": "Bitcoin has quietly rallied to $74,000...", "ticker": "BTC-USD", "speaker": "Nico", "episode_id": "lcfIvTX1FlC", "sentiment_score": 9, "sentiment_category": "positive" } } ] }, { "ticker": "ETH-USD", "snapshot": { "ticker": "ETH-USD", "episode_count": 16, "attention_share": 0.47, "sentiment_mean": 6.4, "sentiment_delta_1d": -0.6, "sentiment_delta_7d": 0, "bull_ratio": 0.5, "bear_ratio": 0.06, "neutral_ratio": 0.44, "consensus_score": 0.26, "sentiment_momentum": -0.44, "narrative_intensity_norm": 1, "summary": "Ether is framed as a core alt to buy..." }, "signals": [], "quotes": [] } ], "items": { "$ref": "#/components/schemas/FeedAssetEntry" } }, "podcasts": { "type": "array", "description": "Array of favorited podcast with their latest episodes", "example": [ { "podcast_id": "1414384043", "podcast_name": "CoinDesk Podcast Network", "episodes": [ { "episode_id": "aJPaLpxH1Y9", "episode_title": "FTX to Repay Creditors Another $2.2B This Month | CoinDesk Daily", "published_utc_date": "2026-03-19", "crypto_sentiment_score": 3, "market_sentiment_category": "negative", "transcript_summary": "The FTX Recovery Trust will distribute about $2.2 billion to creditors by the end of the month, with...", "podcast_id": "1414384043", "podcasts": [ { "podcast_name": "CoinDesk Podcast Network" } ] } ] } ], "items": { "$ref": "#/components/schemas/FeedPodcastEntry" } } } } }, "parameters": { "date": { "name": "date", "in": "query", "required": false, "schema": { "type": "string", "format": "date" }, "description": "Date in YYYY-MM-DD format. Omit for latest." }, "ticker": { "name": "ticker", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Asset ticker symbol. IMPORTANT: all crypto tickers MUST be suffixed with \"-USD\" — e.g. BTC-USD, ETH-USD, SOL-USD. Bare symbols like \"BTC\" will not match and will return an empty / 404 response." }, "podcast_id": { "name": "podcast_id", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Podcast ID from search_podcasts" }, "episode_id": { "name": "episode_id", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Episode ID" }, "q": { "name": "q", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Podcast name search query e.g. unchained, bankless, chopping block" }, "limit": { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "default": 5, "maximum": 20 }, "description": "Number of episodes to return (max 20, default 5)" }, "episodes_lookback": { "name": "episodes_lookback", "in": "query", "required": false, "schema": { "type": "integer", "default": 3, "maximum": 10 }, "description": "Number of recent episodes per followed podcast (max 10, default 3)" }, "category": { "name": "category", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Leaderboard category: alpha_index, alpha_pulse, risers, droppers, mentioned, or surprising. Omit for highlights (top 1 from each)." }, "days": { "name": "days", "in": "query", "required": false, "schema": { "type": "integer", "default": 30, "maximum": 1000 }, "description": "Number of historical days to return, counting back from the anchor date. Tier-capped: free=7, alpha=365, pro=730, enterprise=1000. Requests above the cap are silently capped." }, "snapshot_type": { "name": "snapshot_type", "in": "query", "required": false, "schema": { "type": "string", "default": "crypto", "enum": [ "crypto", "tradfi" ] }, "description": "Asset universe to draw the snapshot from. Currently only \"crypto\" is available; \"tradfi\" is reserved for a future release. Defaults to \"crypto\"." }, "version_number": { "name": "version_number", "in": "query", "required": false, "schema": { "type": "integer", "default": -1, "minimum": -1 }, "description": "Which revision of the snapshot to return. Each snapshot date can be re-generated multiple times (version 1, 2, 3, …). Use -1 (the default) to always get the latest authoritative version (is_latest = true). If you request a specific version that does not exist for the given date + snapshot_type, the latest version is returned instead." }, "version_info": { "name": "version_info", "in": "query", "required": false, "schema": { "type": "boolean", "default": false }, "description": "When true, include version metadata in the response: both version_num (the revision number) and version_label (a human-readable label like \"eod_utc\" for the initial end-of-day build, or \"revised\" when a later-indexed podcast triggered a regeneration). When false (the default), neither field is included. Note: the snapshot generation \"status\" field is ALWAYS returned regardless of this flag." } }, "responses": { "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Not available on your plan", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "tags": [ { "name": "Market", "description": "Market-wide sentiment and narrative data" }, { "name": "Ticker", "description": "Asset-level sentiment and signals" }, { "name": "Podcast", "description": "Podcast discovery and episode listing" }, { "name": "Episode", "description": "Individual episode data" }, { "name": "Personal", "description": "Personalised feed based on favorites" } ], "paths": { "/market/snapshot": { "get": { "tags": [ "Market" ], "summary": "Get daily market snapshot", "description": "Get the overall crypto market daily snapshot (daily narrative insight report) for a given date. Returns daily headline, delta narrative, regime + justification, α-sentiment OHLC scores (0-10 scale), α-sentiment z-scores (-3 to +3), narrative summary, narrative intesity score, market psychology, consensus score, key tensions, surprise mentions (ticker + why + impact score), episode volume score, and wordcloud.", "parameters": [ { "$ref": "#/components/parameters/date" }, { "$ref": "#/components/parameters/snapshot_type" }, { "$ref": "#/components/parameters/version_number" }, { "$ref": "#/components/parameters/version_info" } ], "responses": { "200": { "description": "Get daily market snapshot", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MarketSnapshot" } } } }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "404": { "$ref": "#/components/responses/404" }, "429": { "$ref": "#/components/responses/429" } } } }, "/market/themes": { "get": { "tags": [ "Market" ], "summary": "Get market themes", "description": "Get narrative themes dominating the crypto podcast space on a given date. Each theme includes title, summary, podcast coverage count, fragility score, novelty score and counterfactual narrative.", "parameters": [ { "$ref": "#/components/parameters/date" }, { "$ref": "#/components/parameters/snapshot_type" }, { "$ref": "#/components/parameters/version_number" }, { "$ref": "#/components/parameters/version_info" } ], "responses": { "200": { "description": "Get market themes", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Theme" } }, "snapshot_date": { "type": "string", "format": "date" } } } } } }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "404": { "$ref": "#/components/responses/404" }, "429": { "$ref": "#/components/responses/429" } } } }, "/market/signals": { "get": { "tags": [ "Market" ], "summary": "Get daily market scenario signals", "description": "Get scenario strategic signals across all assets for a given date. Each signal includes signal type, horizon, scenario description, trigger conditions, confidence score and invalidating conditions. (Not financial advice.)", "parameters": [ { "$ref": "#/components/parameters/date" }, { "$ref": "#/components/parameters/snapshot_type" }, { "$ref": "#/components/parameters/version_number" }, { "$ref": "#/components/parameters/version_info" } ], "responses": { "200": { "description": "Get daily market scenario signals", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Signal" } }, "snapshot_date": { "type": "string", "format": "date" } } } } } }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "404": { "$ref": "#/components/responses/404" }, "429": { "$ref": "#/components/responses/429" } } } }, "/market/quotes/featured": { "get": { "tags": [ "Market" ], "summary": "Get featured quotes", "description": "Get the top featured quotes from crypto podcasts for a given date, ranked by relevance score.", "parameters": [ { "$ref": "#/components/parameters/date" }, { "$ref": "#/components/parameters/snapshot_type" }, { "$ref": "#/components/parameters/version_number" }, { "$ref": "#/components/parameters/version_info" } ], "responses": { "200": { "description": "Get featured quotes", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Quote" } }, "snapshot_date": { "type": "string", "format": "date" } } } } } }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "404": { "$ref": "#/components/responses/404" }, "429": { "$ref": "#/components/responses/429" } } } }, "/market/episodes": { "get": { "tags": [ "Market" ], "summary": "Get market episodes", "description": "Get all crypto podcast episodes published on a given date, including podcast name, α-sentiment score (0-10 scale), and transcript summary.", "parameters": [ { "$ref": "#/components/parameters/date" } ], "responses": { "200": { "description": "Get market episodes", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Episode" } }, "snapshot_date": { "type": "string", "format": "date" } } } } } }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "404": { "$ref": "#/components/responses/404" }, "429": { "$ref": "#/components/responses/429" } } } }, "/market/history": { "get": { "tags": [ "Market" ], "summary": "Get market historical time series", "description": "Returns a time series of daily market snapshots (the overall market-level daily narrative report), ordered oldest to newest. One row per day with α-sentiment OHLC and 1d/7d deltas, market sentiment mean/median/std, z-score, strength index, regime, consensus, episode count, headline and narrative summaries.\n\n**Tier limits on `days`:** free=7, alpha=365, pro=730, enterprise=1000. Requests exceeding the limit are silently capped to the tier maximum.\n\n**`date` (end-date anchor) is only honored for enterprise.** For free / alpha / pro it is ignored and the window always ends at the latest available snapshot. If today has no snapshot yet, the most recent existing snapshot is used as the anchor.\n\nResponse includes `tier_cap`, `effective_days`, `start_date`, `end_date` and `date_param_honored` so clients can see exactly what window was returned. Each row always carries `status`; `version_num`/`version_label` are included when `version_info=true`.", "parameters": [ { "$ref": "#/components/parameters/days" }, { "$ref": "#/components/parameters/date" }, { "$ref": "#/components/parameters/snapshot_type" }, { "$ref": "#/components/parameters/version_info" } ], "responses": { "200": { "description": "Get market historical time series", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/MarketSnapshot" } }, "snapshot_date": { "type": "string", "format": "date" } } } } } }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "404": { "$ref": "#/components/responses/404" }, "429": { "$ref": "#/components/responses/429" } } } }, "/ticker/snapshot": { "get": { "tags": [ "Ticker" ], "summary": "Get asset snapshot", "description": "Get detailed daily insights snapshot for a specific crypto asset. Returns daily asset summary, α-index (0-1), α-pulse (0-1), episode count, attention share (0-1), α-sentiment OHLC and 1-7 day delta (0-10 scale), bull/bear/neutral ratios (0-1), consensus score (0-1), novelty score (0-1), momentum, narrative intensity, narrative summary.", "parameters": [ { "$ref": "#/components/parameters/ticker" }, { "$ref": "#/components/parameters/date" }, { "$ref": "#/components/parameters/snapshot_type" }, { "$ref": "#/components/parameters/version_number" }, { "$ref": "#/components/parameters/version_info" } ], "responses": { "200": { "description": "Get asset snapshot", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/AssetSnapshot" } } } } } }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "404": { "$ref": "#/components/responses/404" }, "429": { "$ref": "#/components/responses/429" } } } }, "/ticker/signals": { "get": { "tags": [ "Ticker" ], "summary": "Get asset signals", "description": "Get scenario signals for a specific crypto asset. Returns signal type, time horizon, scenario description, trigger conditions, confidence score and invalidating conditions. (Not financial advice.)", "parameters": [ { "$ref": "#/components/parameters/ticker" }, { "$ref": "#/components/parameters/date" }, { "$ref": "#/components/parameters/snapshot_type" }, { "$ref": "#/components/parameters/version_number" }, { "$ref": "#/components/parameters/version_info" } ], "responses": { "200": { "description": "Get asset signals", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Signal" } }, "snapshot_date": { "type": "string", "format": "date" } } } } } }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "404": { "$ref": "#/components/responses/404" }, "429": { "$ref": "#/components/responses/429" } } } }, "/ticker/quotes/featured": { "get": { "tags": [ "Ticker" ], "summary": "Get asset featured quotes", "description": "Get featured podcast quotes for a specific crypto asset on a given date, with α-sentiment scores (0-10 scale), ranked by selection score.", "parameters": [ { "$ref": "#/components/parameters/ticker" }, { "$ref": "#/components/parameters/date" }, { "$ref": "#/components/parameters/snapshot_type" }, { "$ref": "#/components/parameters/version_number" }, { "$ref": "#/components/parameters/version_info" } ], "responses": { "200": { "description": "Get asset featured quotes", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Quote" } }, "snapshot_date": { "type": "string", "format": "date" } } } } } }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "404": { "$ref": "#/components/responses/404" }, "429": { "$ref": "#/components/responses/429" } } } }, "/ticker/history": { "get": { "tags": [ "Ticker" ], "summary": "Get asset historical time series", "description": "Returns a time series of daily AudioAlpha asset snapshots for a single ticker, ordered oldest to newest. One row per day with α-index, α-pulse, α-sentiment OHLC and 1d/7d deltas, bull/bear/neutral ratios, consensus, novelty, surprise, momentum, attention share, narrative intensity and summary.\n\n**Tier limits on `days`:** free=7, alpha=365, pro=730, enterprise=1000. Requests exceeding the limit are silently capped to the tier maximum.\n\n**`date` (end-date anchor) is only honored for enterprise.** For free / alpha / pro it is ignored and the window always ends at the latest available snapshot. If today has no snapshot yet, the most recent existing snapshot is used as the anchor. This prevents back-testing on arbitrary historical periods.\n\nResponse includes `tier_cap`, `effective_days`, `start_date`, `end_date` and `date_param_honored` so clients can see exactly what window was returned.", "parameters": [ { "$ref": "#/components/parameters/ticker" }, { "$ref": "#/components/parameters/days" }, { "$ref": "#/components/parameters/date" }, { "$ref": "#/components/parameters/snapshot_type" }, { "$ref": "#/components/parameters/version_info" } ], "responses": { "200": { "description": "Get asset historical time series", "content": { "application/json": { "schema": { "type": "object", "properties": { "ticker": { "type": "string", "example": "BTC" }, "requested_days": { "type": "integer", "example": 30 }, "effective_days": { "type": "integer", "example": 30, "description": "Actual window size used after tier capping" }, "tier_cap": { "type": "integer", "example": 730, "description": "Max days allowed for the caller's tier" }, "date_param_honored": { "type": "boolean", "example": false, "description": "Whether the supplied `date` end-date was honored. Only true for enterprise tier." }, "start_date": { "type": "string", "format": "date" }, "end_date": { "type": "string", "format": "date" }, "count": { "type": "integer", "example": 30 }, "data": { "type": "array", "description": "Daily snapshots, oldest first. Each row includes `snapshot_date` plus all AssetSnapshot fields.", "items": { "allOf": [ { "type": "object", "properties": { "snapshot_date": { "type": "string", "format": "date" } } }, { "$ref": "#/components/schemas/AssetSnapshot" } ] } } } } } } }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "404": { "$ref": "#/components/responses/404" }, "429": { "$ref": "#/components/responses/429" } } } }, "/tickers/leaderboard": { "get": { "tags": [ "Ticker" ], "summary": "Get ticker leaderboard", "description": "Get ticker leaderboard for a given date. Without category param, returns highlights object that includes assetSnapshot of top_alpha_index, top_alpha_pulse, top_riser, top_dropper, most_mentioned, most_surprising. With category param (alpha_index/alpha_pulse/risers/droppers/mentioned/surprising), returns array of LeaderboardEntry.", "parameters": [ { "$ref": "#/components/parameters/date" }, { "$ref": "#/components/parameters/category" }, { "$ref": "#/components/parameters/limit" }, { "$ref": "#/components/parameters/snapshot_type" }, { "$ref": "#/components/parameters/version_info" } ], "responses": { "200": { "description": "Get ticker leaderboard", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/LeaderboardHighlights" } } } } } }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "404": { "$ref": "#/components/responses/404" }, "429": { "$ref": "#/components/responses/429" } } } }, "/podcasts/search": { "get": { "tags": [ "Podcast" ], "summary": "Search podcasts", "description": "Search for crypto podcasts by name. Returns podcast ID, name, artist, language, x-handle, and artwork.", "parameters": [ { "$ref": "#/components/parameters/q" } ], "responses": { "200": { "description": "Search podcasts", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Podcast" } } } } } } }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "429": { "$ref": "#/components/responses/429" } } } }, "/podcast/episodes": { "get": { "tags": [ "Podcast" ], "summary": "Get podcast episodes", "description": "Get recent episodes for a specific podcast by podcast ID.", "parameters": [ { "$ref": "#/components/parameters/podcast_id" }, { "$ref": "#/components/parameters/limit" } ], "responses": { "200": { "description": "Get podcast episodes", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Episode" } } } } } } }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "404": { "$ref": "#/components/responses/404" }, "429": { "$ref": "#/components/responses/429" } } } }, "/podcast/latest": { "get": { "tags": [ "Podcast" ], "summary": "Get latest episode of podcast", "description": "Get the latest episode for a specific podcast, including title, episode_id, transcript summary, episode artwork, α-sentiment (crypto markets), and traditional markets sentiment.", "parameters": [ { "$ref": "#/components/parameters/podcast_id" } ], "responses": { "200": { "description": "Get latest episode of podcast", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Episode" } } } } } }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "404": { "$ref": "#/components/responses/404" }, "429": { "$ref": "#/components/responses/429" } } } }, "/podcast/latest/full": { "get": { "tags": [ "Podcast" ], "summary": "Get latest episode (full) of podcast", "description": "Get the latest episode for a podcast with full details including quotes and asset mentions.", "parameters": [ { "$ref": "#/components/parameters/podcast_id" } ], "responses": { "200": { "description": "Get latest episode (full) of podcast", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/EpisodeFull" } } } } } }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "404": { "$ref": "#/components/responses/404" }, "429": { "$ref": "#/components/responses/429" } } } }, "/episode/details": { "get": { "tags": [ "Episode" ], "summary": "Get episode details", "description": "Get metadata for a specific episode including title, publish date, duration, α-sentiment score (crypto) (0-10 scale), traditional markets sentiment (0-10), and podcast info.", "parameters": [ { "$ref": "#/components/parameters/episode_id" } ], "responses": { "200": { "description": "Get episode details", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Episode" } } } } } }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "404": { "$ref": "#/components/responses/404" }, "429": { "$ref": "#/components/responses/429" } } } }, "/episode/summary": { "get": { "tags": [ "Episode" ], "summary": "Get episode summary", "description": "Get the transcript summary for a specific episode, including assets mentioned and their α-sentiment (0-10 scale).", "parameters": [ { "$ref": "#/components/parameters/episode_id" } ], "responses": { "200": { "description": "Get episode summary", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Episode" } } } } } }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "404": { "$ref": "#/components/responses/404" }, "429": { "$ref": "#/components/responses/429" } } } }, "/episode/quotes": { "get": { "tags": [ "Episode" ], "summary": "Get episode quotes", "description": "Get all quotes extracted from a specific episode, with speaker, α-sentiment score (0-10 scale) and associated ticker.", "parameters": [ { "$ref": "#/components/parameters/episode_id" } ], "responses": { "200": { "description": "Get episode quotes", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Quote" } } } } } } }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "404": { "$ref": "#/components/responses/404" }, "429": { "$ref": "#/components/responses/429" } } } }, "/episode/transcript": { "get": { "tags": [ "Episode" ], "summary": "Get episode transcript", "description": "Get the full transcript for a specific episode including speaker diarization and speaker name mapping. Pro and Enterprise plans only.", "parameters": [ { "$ref": "#/components/parameters/episode_id" } ], "responses": { "200": { "description": "Get episode transcript", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Transcript" } } } } } }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "404": { "$ref": "#/components/responses/404" }, "429": { "$ref": "#/components/responses/429" } } } }, "/episode/full": { "get": { "tags": [ "Episode" ], "summary": "Get full episode", "description": "Get full episode data in one call — details, summary, quotes and asset mentions.", "parameters": [ { "$ref": "#/components/parameters/episode_id" } ], "responses": { "200": { "description": "Get full episode", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object" } } } } } }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "404": { "$ref": "#/components/responses/404" }, "429": { "$ref": "#/components/responses/429" } } } }, "/me/favorites/assets": { "get": { "tags": [ "Personal" ], "summary": "Get favorite assets", "description": "Get the list of crypto assets the authenticated user has favorited on AudioAlpha. Always returns the latest authoritative snapshot (is_latest) per asset.", "parameters": [ { "$ref": "#/components/parameters/snapshot_type" }, { "$ref": "#/components/parameters/version_info" } ], "responses": { "200": { "description": "Get favorite assets", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/AssetSnapshot" } } } } } } }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "429": { "$ref": "#/components/responses/429" } } } }, "/me/favorites/podcasts": { "get": { "tags": [ "Personal" ], "summary": "Get favorite podcasts", "description": "Get the list of podcasts the authenticated user follows on AudioAlpha.", "parameters": [], "responses": { "200": { "description": "Get favorite podcasts", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Podcast" } } } } } } }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "429": { "$ref": "#/components/responses/429" } } } }, "/me/feed": { "get": { "tags": [ "Personal" ], "summary": "Get personalized feed", "description": "Get a personalized feed based on the user's favorite assets and followed podcasts. Always uses the latest authoritative snapshot (is_latest). Returns snapshot_date and an array of assets, each containing: ticker, daily snapshot (sentiment, attention, consensus, momentum, summary), trading signals (with horizon, scenario, trigger, confidence, invalidating condition), and curated quotes (ranked with selection reason).", "parameters": [ { "$ref": "#/components/parameters/episodes_lookback" }, { "$ref": "#/components/parameters/snapshot_type" }, { "$ref": "#/components/parameters/version_info" } ], "responses": { "200": { "description": "Get personalized feed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PersonalizedFeed" } } } }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "429": { "$ref": "#/components/responses/429" } } } } } }