BidClub Feed Index API

openapi: 3.2.0
info:
  title: BidClub Open Podcast Transcript Feed Index 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: Feed Index
paths:
  /api/feed-index:
    get:
      operationId: getFeedIndex
      summary: Complete catalog in one response
      description: Every published episode as compact metadata. Complete at the current scale, with no pagination. Clients MUST tolerate a future `pagination` object and `Link` headers appearing in this response. Intended for occasional discovery or mirroring; conditional-response validators are not guaranteed. Query filters are not accepted; use the show/person paths or filter returned metadata locally.
      responses:
        '200':
          description: The whole catalog.
          headers:
            Cache-Control:
              schema:
                type: string
                const: public, max-age=60, 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/FeedIndexResponse'
        '502':
          description: 'Upstream database unavailable. Body: {"error": "upstream unavailable"}.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      tags:
      - Feed Index
    options:
      summary: CORS preflight
      description: Returns 204 with permissive CORS headers. No body.
      responses:
        '204':
          description: Preflight accepted.
      tags:
      - Feed Index
      operationId: optionsApiFeedIndex
      x-operation-id-source: derived
  /api/feed-index/person/{person}:
    get:
      operationId: getFeedIndexByPerson
      summary: Catalog filtered to one participant
      description: Same shape as /api/feed-index, restricted to episodes tagged "person:{person}". The path segment is the bare name, URL-encoded; matching is exact.
      parameters:
      - name: person
        in: path
        required: true
        schema:
          type: string
          minLength: 1
          maxLength: 120
      responses:
        '200':
          description: Matching catalog rows.
          headers:
            Cache-Control:
              schema:
                type: string
                const: public, max-age=60, 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/FeedIndexResponse'
        '400':
          description: 'Empty, overlong, or control-character name. Body: {"error": "invalid person"}.'
          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:
      - Feed Index
    options:
      summary: CORS preflight
      description: Returns 204 with permissive CORS headers. No body.
      responses:
        '204':
          description: Preflight accepted.
      tags:
      - Feed Index
      operationId: optionsApiFeedIndexPersonByPerson
      x-operation-id-source: derived
  /api/feed-index/show/{show}:
    get:
      operationId: getFeedIndexByShow
      summary: Catalog filtered to one show
      description: Same shape as /api/feed-index, restricted to a single show id.
      parameters:
      - name: show
        in: path
        required: true
        schema:
          type: string
          pattern: ^[a-z0-9][a-z0-9_-]{0,63}$
      responses:
        '200':
          description: Matching catalog rows.
          headers:
            Cache-Control:
              schema:
                type: string
                const: public, max-age=60, 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/FeedIndexResponse'
        '400':
          description: 'Body: {"error": "invalid show"}.'
          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:
      - Feed Index
    options:
      summary: CORS preflight
      description: Returns 204 with permissive CORS headers. No body.
      responses:
        '204':
          description: Preflight accepted.
      tags:
      - Feed Index
      operationId: optionsApiFeedIndexShowByShow
      x-operation-id-source: derived
components:
  schemas:
    FeedIndexItem:
      type: object
      required:
      - slug
      - show_id
      - show
      - title
      properties:
        slug:
          type: string
          description: Stable public identifier.
        show_id:
          type: string
          description: Foreign key into /api/v1/shows.
        show:
          type: string
          description: Show display name, flattened.
        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_alt:
          type:
          - string
          - 'null'
          description: Title in the alternate language (lang_alt).
        display_title_alt:
          type:
          - string
          - 'null'
        title_orig:
          type:
          - string
          - 'null'
          description: Source-platform title when it differs.
        dek:
          type:
          - string
          - 'null'
          description: One-line editorial standfirst.
        dek_alt:
          type:
          - string
          - 'null'
        chips:
          type: array
          items:
            type: string
          description: Participant tags, each prefixed "person:" (e.g. "person:Jensen Huang").
        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.
        youtube_id:
          type:
          - string
          - 'null'
        thumbnail_url:
          type:
          - string
          - 'null'
        source_url:
          type:
          - string
          - 'null'
        source_label:
          type:
          - string
          - 'null'
        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.
    FeedIndexResponse:
      type: object
      required:
      - count
      - episodes
      properties:
        count:
          type: integer
        episodes:
          type: array
          items:
            $ref: '#/components/schemas/FeedIndexItem'
    Error:
      type: object
      required:
      - error
      properties:
        error:
          type: string