AudioAlpha Personal API

openapi: 3.2.0
info:
  title: AudioAlpha Personal API
  version: 1.0.0
  description: 'Market sentiment and narrative intelligence derived from podcast analysis.


    **Getting Started:**

    1. Generate your API key at https://audioalpha.io/account

    2. Include the key in requests as: Authorization: Bearer YOUR_API_KEY


    **MCP (Claude Integration):**

    Connect to Claude Desktop by adding to your config:

    ```json

    "mcpServers": {

    "audioalpha": {

    "command": "npx",

    "args": ["mcp-remote", "https://www.audioalpha.io/api/mcp?apiKey=YOUR_KEY"]

    }

    }

    ```'
  contact:
    url: https://audioalpha.io
    email: team@audioalpha.io
servers:
- url: https://www.audioalpha.io/api/v1
  description: Production
security:
- bearerAuth: []
tags:
- name: Personal
  description: Personalised feed based on favorites
paths:
  /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'
      operationId: getMeFavoritesAssets
      x-operation-id-source: derived
  /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'
      operationId: getMeFavoritesPodcasts
      x-operation-id-source: derived
  /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'
      operationId: getMeFeed
      x-operation-id-source: derived
components:
  schemas:
    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'
    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
    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
    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'
    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
    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
    Error:
      type: object
      properties:
        error:
          type: string
    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
    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
    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'
    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
  parameters:
    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.'
    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".
    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)
  responses:
    '401':
      description: Missing or invalid API key
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    '429':
      description: Rate limit exceeded
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    '403':
      description: Not available on your plan
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: API key generated from https://audioalpha.io/account