BidClub Shows API

openapi: 3.2.0
info:
  title: BidClub Open Podcast Transcript Shows 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: Shows
paths:
  /api/v1/shows:
    get:
      operationId: listShows
      summary: Show registry
      description: 'The curated roster: identity, language, hosts, tracking state, and source URLs.'
      responses:
        '200':
          description: The complete registry.
          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/ShowList'
        '502':
          description: 'Upstream database unavailable. Body: {"error": "upstream unavailable"}.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      tags:
      - Shows
    options:
      summary: CORS preflight
      description: Returns 204 with permissive CORS headers. No body.
      responses:
        '204':
          description: Preflight accepted.
      tags:
      - Shows
      operationId: optionsApiV1Shows
      x-operation-id-source: derived
components:
  schemas:
    Show:
      type: object
      required:
      - id
      - name
      - lang
      - hosts
      - tracked
      - position
      - sources
      properties:
        id:
          type: string
        name:
          type: string
        lang:
          type: string
          description: Primary language of the show, lower-case ISO code (e.g. "en", "zh").
        hosts:
          type:
          - string
          - 'null'
        tracked:
          type: boolean
          description: Whether the show is on the actively-followed roster.
        position:
          type: integer
          description: Display order in the registry.
        sources:
          type: object
          description: Known upstream locations and the registry blurb.
          properties:
            rss:
              type:
              - string
              - 'null'
            youtube:
              type:
              - string
              - 'null'
            xiaoyuzhou:
              type:
              - string
              - 'null'
            site:
              type:
              - string
              - 'null'
            description:
              type:
              - string
              - 'null'
            description_source:
              type:
              - string
              - 'null'
            other:
              type:
              - object
              - 'null'
              additionalProperties:
                type: string
    ShowList:
      type: object
      required:
      - shows
      properties:
        shows:
          type: array
          items:
            $ref: '#/components/schemas/Show'
    Error:
      type: object
      required:
      - error
      properties:
        error:
          type: string