AudioAlpha Market API

openapi: 3.2.0
info:
  title: AudioAlpha Market 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: Market
  description: Market-wide sentiment and narrative data
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'
      operationId: getMarketSnapshot
      x-operation-id-source: derived
  /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'
      operationId: getMarketThemes
      x-operation-id-source: derived
  /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'
      operationId: getMarketSignals
      x-operation-id-source: derived
  /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'
      operationId: getMarketQuotesFeatured
      x-operation-id-source: derived
  /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'
      operationId: getMarketEpisodes
      x-operation-id-source: derived
  /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.


        **Tier limits on `days`:** free=7, alpha=365, pro=730, enterprise=1000. Requests exceeding the limit are silently capped to the tier maximum.


        **`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.


        Response 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'
      operationId: getMarketHistory
      x-operation-id-source: derived
components:
  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".
    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.
    date:
      name: date
      in: query
      required: false
      schema:
        type: string
        format: date
      description: Date in YYYY-MM-DD format. Omit for latest.
    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.'
  schemas:
    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
    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
    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
    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
    Error:
      type: object
      properties:
        error:
          type: string
    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
  responses:
    '404':
      description: Not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    '403':
      description: Not available on your plan
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    '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'
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: API key generated from https://audioalpha.io/account