BidClub Episodes API

openapi: 3.2.0
info:
  title: BidClub Open Podcast Transcript Episodes API
  version: 2026.9.22.2
  description: 'Public reads are keyless, account-free, CORS *. Pitch administrator POST routes use a verified private session. All /api/* responses carry X-Robots-Tag: noindex. Agents: POST /api/mcp speaks Model Context Protocol over Streamable HTTP and exposes the same library as tools (rate limited, JSON-RPC, deliberately not modelled here as it is not a REST resource). Private: POST /api/revalidate (publish hook, Bearer auth — not documented here). Direct SQL-style queries: public read-only PostgREST endpoint documented at https://bidclub.ai/api-docs (PostgREST self-serves its own OpenAPI at {SUPABASE_URL}/rest/v1/).'
  x-bilingual: All editorial content is bilingual EN/ZH via *_alt fields; lang/lang_alt mark each edition's language.
servers:
- url: https://bidclub.ai
tags:
- name: Episodes
paths:
  /api/v1/episodes:
    get:
      operationId: listEpisodes
      summary: Paginated episode metadata
      description: Newest-first metadata without the long Markdown bodies. Follow pagination.next_offset until it is null.
      parameters:
      - name: show
        in: query
        required: false
        description: Exact show id from /api/v1/shows.
        schema:
          type: string
          pattern: ^[a-z0-9][a-z0-9_-]{0,63}$
      - name: lang
        in: query
        required: false
        description: Source language of the episode. Input is uppercased before matching.
        schema:
          type: string
          enum:
          - EN
          - ZH
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          minimum: 1
          maximum: 100
          default: 50
      - name: offset
        in: query
        required: false
        schema:
          type: integer
          minimum: 0
          default: 0
      - name: asset
        in: query
        required: false
        description: Comma-separated asset ids. Values are ORed within this facet; supplied facets are ANDed. Omitting the facet or selecting every id leaves it unfiltered, including untagged episodes; none returns no episodes.
        schema:
          type: string
          pattern: ^(?:none|(?:equities|crypto|vc_pe|other)(?:,(?:equities|crypto|vc_pe|other))*)$
      - name: sector
        in: query
        required: false
        description: Comma-separated sector ids. Values are ORed within this facet; supplied facets are ANDed. Omitting the facet or selecting every id leaves it unfiltered, including untagged episodes; none returns no episodes.
        schema:
          type: string
          pattern: ^(?:none|(?:ai_software|semis|robotics|biotech|consumer|finance|blockchain|energy|space_defense)(?:,(?:ai_software|semis|robotics|biotech|consumer|finance|blockchain|energy|space_defense))*)$
      - name: focus
        in: query
        required: false
        description: Comma-separated focus ids. Values are ORed within this facet; supplied facets are ANDed. Omitting the facet or selecting every id leaves it unfiltered, including untagged episodes; none returns no episodes.
        schema:
          type: string
          pattern: ^(?:none|(?:investing|company_building|technical|macro|policy)(?:,(?:investing|company_building|technical|macro|policy))*)$
      responses:
        '200':
          description: One page of metadata.
          headers:
            Cache-Control:
              schema:
                type: string
                const: public, s-maxage=300, stale-while-revalidate=600
              description: Origin cache policy. The hosting CDN may consume shared-cache directives before forwarding this header to clients.
            Access-Control-Allow-Origin:
              schema:
                type: string
                const: '*'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EpisodeListResponse'
        '400':
          description: 'invalid limit | invalid offset | invalid show | invalid lang | invalid {asset|sector|focus} tag: {id}'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '502':
          description: 'Upstream database unavailable. Body: {"error": "upstream unavailable"}.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      tags:
      - Episodes
    options:
      summary: CORS preflight
      description: Returns 204 with permissive CORS headers. No body.
      responses:
        '204':
          description: Preflight accepted.
      tags:
      - Episodes
      operationId: optionsApiV1Episodes
      x-operation-id-source: derived
  /api/v1/episodes/{slug}:
    get:
      operationId: getEpisode
      summary: One full episode
      description: Editorial Markdown, transcript, alternate-language fields, and provenance. This is the correct route for bulk or automated content access — responses are CDN-cached with a configured shared-cache lifetime of 60 seconds and no stale-while-revalidate. Conditional-response validators are not guaranteed.
      parameters:
      - name: slug
        in: path
        required: true
        schema:
          type: string
          pattern: ^[a-z0-9](?:[a-z0-9-]{0,158}[a-z0-9])?$
          maxLength: 160
      responses:
        '200':
          description: The episode record.
          headers:
            Cache-Control:
              schema:
                type: string
                const: public, s-maxage=60
              description: Origin cache policy. The hosting CDN may consume shared-cache directives before forwarding this header to clients.
            Access-Control-Allow-Origin:
              schema:
                type: string
                const: '*'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Episode'
        '404':
          description: 'No published episode with that slug. Body: {"error": "not found"}.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '502':
          description: 'Upstream database unavailable. Body: {"error": "upstream unavailable"}.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      tags:
      - Episodes
    options:
      summary: CORS preflight
      description: Returns 204 with permissive CORS headers. No body.
      responses:
        '204':
          description: Preflight accepted.
      tags:
      - Episodes
      operationId: optionsApiV1EpisodesBySlug
      x-operation-id-source: derived
components:
  schemas:
    EpisodeListItem:
      type: object
      required:
      - slug
      - show_id
      - title
      properties:
        slug:
          type: string
          description: Stable public identifier.
        show_id:
          type: string
          description: Foreign key into /api/v1/shows.
        title:
          type: string
          description: Complete canonical publisher title.
        display_title:
          type:
          - string
          - 'null'
          description: Feed-only compression of an overlength title; null when unneeded.
        title_orig:
          type:
          - string
          - 'null'
          description: Source-platform title when it differs.
        dek:
          type:
          - string
          - 'null'
          description: One-line editorial standfirst.
        lang:
          type:
          - string
          - 'null'
          enum:
          - EN
          - ZH
          - null
          description: Language of the primary editorial fields.
        date:
          type:
          - string
          - 'null'
          description: Publication calendar date, YYYY-MM-DD.
        published_at:
          type:
          - string
          - 'null'
          description: Exact publication timestamp (RFC 3339); null for date-only archives.
        duration_min:
          type:
          - number
          - 'null'
          description: Episode length in minutes.
        source_url:
          type:
          - string
          - 'null'
        source_label:
          type:
          - string
          - 'null'
        rss_url:
          type:
          - string
          - 'null'
        youtube_id:
          type:
          - string
          - 'null'
        youtube_url:
          type:
          - string
          - 'null'
        provenance:
          type: array
          description: Ordered [stage, tool] pairs recording how the episode was produced.
          items:
            type: array
            items:
              type: string
            minItems: 2
            maxItems: 2
        chips:
          type: array
          items:
            type: string
          description: Participant tags, each prefixed "person:" (e.g. "person:Jensen Huang").
        tag_assets:
          type: array
          maxItems: 2
          uniqueItems: true
          items:
            type: string
            enum:
            - equities
            - crypto
            - vc_pe
            - other
          description: Zero to two closed asset taxonomy ids, primary first. Empty is valid even after classification.
        tag_sectors:
          type: array
          maxItems: 2
          uniqueItems: true
          items:
            type: string
            enum:
            - ai_software
            - semis
            - robotics
            - biotech
            - consumer
            - finance
            - blockchain
            - energy
            - space_defense
          description: Zero to two closed sector taxonomy ids, primary first. Empty is valid even after classification.
        tag_focus:
          type: array
          maxItems: 2
          uniqueItems: true
          items:
            type: string
            enum:
            - investing
            - company_building
            - technical
            - macro
            - policy
          description: Zero to two closed editorial-focus taxonomy ids, primary first. Empty is valid even after classification.
        tagging_status:
          type: string
          enum:
          - pending
          - classified
          - failed
          - skipped
          description: Classification state. Non-classified episodes have empty tag arrays; classified does not require a tag in every facet.
        tagging_version:
          type:
          - string
          - 'null'
          description: Taxonomy version used for classification; nonblank when tagging_status is classified, otherwise it may be null.
        shows:
          type:
          - object
          - 'null'
          properties:
            name:
              type: string
    Episode:
      type: object
      required:
      - slug
      - show_id
      - title
      properties:
        slug:
          type: string
          description: Stable public identifier.
        show_id:
          type: string
          description: Foreign key into /api/v1/shows.
        title:
          type: string
          description: Complete canonical publisher title.
        display_title:
          type:
          - string
          - 'null'
          description: Feed-only compression of an overlength title; null when unneeded.
        title_orig:
          type:
          - string
          - 'null'
          description: Source-platform title when it differs.
        dek:
          type:
          - string
          - 'null'
          description: One-line editorial standfirst.
        lang:
          type:
          - string
          - 'null'
          enum:
          - EN
          - ZH
          - null
          description: Language of the primary editorial fields.
        date:
          type:
          - string
          - 'null'
          description: Publication calendar date, YYYY-MM-DD.
        published_at:
          type:
          - string
          - 'null'
          description: Exact publication timestamp (RFC 3339); null for date-only archives.
        duration_min:
          type:
          - number
          - 'null'
          description: Episode length in minutes.
        source_url:
          type:
          - string
          - 'null'
        source_label:
          type:
          - string
          - 'null'
        rss_url:
          type:
          - string
          - 'null'
        youtube_id:
          type:
          - string
          - 'null'
        youtube_url:
          type:
          - string
          - 'null'
        provenance:
          type: array
          description: Ordered [stage, tool] pairs recording how the episode was produced.
          items:
            type: array
            items:
              type: string
            minItems: 2
            maxItems: 2
        chips:
          type: array
          items:
            type: string
          description: Participant tags, each prefixed "person:" (e.g. "person:Jensen Huang").
        tag_assets:
          type: array
          maxItems: 2
          uniqueItems: true
          items:
            type: string
            enum:
            - equities
            - crypto
            - vc_pe
            - other
          description: Zero to two closed asset taxonomy ids, primary first. Empty is valid even after classification.
        tag_sectors:
          type: array
          maxItems: 2
          uniqueItems: true
          items:
            type: string
            enum:
            - ai_software
            - semis
            - robotics
            - biotech
            - consumer
            - finance
            - blockchain
            - energy
            - space_defense
          description: Zero to two closed sector taxonomy ids, primary first. Empty is valid even after classification.
        tag_focus:
          type: array
          maxItems: 2
          uniqueItems: true
          items:
            type: string
            enum:
            - investing
            - company_building
            - technical
            - macro
            - policy
          description: Zero to two closed editorial-focus taxonomy ids, primary first. Empty is valid even after classification.
        tagging_status:
          type: string
          enum:
          - pending
          - classified
          - failed
          - skipped
          description: Classification state. Non-classified episodes have empty tag arrays; classified does not require a tag in every facet.
        tagging_version:
          type:
          - string
          - 'null'
          description: Taxonomy version used for classification; nonblank when tagging_status is classified, otherwise it may be null.
        thumbnail_url:
          type:
          - string
          - 'null'
        title_alt:
          type:
          - string
          - 'null'
          description: Title in the alternate language (lang_alt).
        display_title_alt:
          type:
          - string
          - 'null'
        dek_alt:
          type:
          - string
          - 'null'
        lang_alt:
          type:
          - string
          - 'null'
          enum:
          - EN
          - ZH
          - null
          description: Language of every *_alt field.
        tldr_md:
          type:
          - string
          - 'null'
          description: TL;DR bullets as Markdown.
        digest_md:
          type:
          - string
          - 'null'
          description: Structured digest as Markdown.
        transcript_md:
          type:
          - string
          - 'null'
          description: Full speaker-attributed transcript.
        tldr_md_alt:
          type:
          - string
          - 'null'
        digest_md_alt:
          type:
          - string
          - 'null'
        shows:
          type:
          - object
          - 'null'
          properties:
            name:
              type: string
            hosts:
              type:
              - string
              - 'null'
    Pagination:
      type: object
      required:
      - limit
      - offset
      - next_offset
      properties:
        limit:
          type: integer
        offset:
          type: integer
        next_offset:
          type:
          - integer
          - 'null'
          description: Offset of the next page, or null on the final page.
    EpisodeListResponse:
      type: object
      required:
      - episodes
      - pagination
      - artifacts
      properties:
        episodes:
          type: array
          items:
            $ref: '#/components/schemas/EpisodeListItem'
        pagination:
          $ref: '#/components/schemas/Pagination'
        artifacts:
          type: string
          description: Constant hint string naming the per-episode JSON and file routes.
    Error:
      type: object
      required:
      - error
      properties:
        error:
          type: string