AudioAlpha Episode API

openapi: 3.2.0
info:
  title: AudioAlpha Episode 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: Episode
  description: Individual episode data
paths:
  /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'
      operationId: getEpisodeDetails
      x-operation-id-source: derived
  /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'
      operationId: getEpisodeSummary
      x-operation-id-source: derived
  /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'
      operationId: getEpisodeQuotes
      x-operation-id-source: derived
  /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'
      operationId: getEpisodeTranscript
      x-operation-id-source: derived
  /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'
      operationId: getEpisodeFull
      x-operation-id-source: derived
components:
  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
    Error:
      type: object
      properties:
        error:
          type: string
    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
    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
  responses:
    '404':
      description: Not found
      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'
    '403':
      description: Not available on your plan
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  parameters:
    episode_id:
      name: episode_id
      in: query
      required: true
      schema:
        type: string
      description: Episode ID
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: API key generated from https://audioalpha.io/account