BidClub Dl API

openapi: 3.2.0
info:
  title: BidClub Open Podcast Transcript Dl 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: Dl
paths:
  /dl/{slug}/{file}:
    get:
      operationId: downloadEpisodeArtifact
      summary: Download one episode as a file
      description: Assembles a Markdown, plain-text, or typeset PDF artifact for a single episode. Errors are short plain-text bodies, not JSON.
      x-notes: File routes can run for up to 300 seconds. Most responses use private, no-store; single-episode Markdown containing only a transcript is served inline with public, s-maxage=300, stale-while-revalidate=86400. PDF objects are reused from storage, while PDF responses and show ZIPs remain private, no-store. Automated clients MUST use the JSON API (/api/v1/episodes/{slug}) for polling or bulk access.
      parameters:
      - name: slug
        in: path
        required: true
        schema:
          type: string
          pattern: ^[a-z0-9](?:[a-z0-9-]{0,158}[a-z0-9])?$
          maxLength: 160
      - name: file
        in: path
        required: true
        description: summary = TL;DR + digest, transcript = transcript only, full = both. If only a summary or transcript exists, full returns that available section. md keeps Markdown structure, txt strips most of it, pdf is typeset.
        schema:
          type: string
          pattern: ^(summary|transcript|full)\.(md|txt|pdf)$
      - name: lang
        in: query
        required: false
        description: Requested edition. Case-insensitive; any other value (including omission) means orig, the episode's source language. Translated summaries require both TL;DR and digest translations; otherwise the source summary is served. Transcripts always retain the source language, so full can combine translated summaries with source transcripts. Single-episode responses report summary fallback in X-BidClub-Language-Fallback; show ZIPs record it per episode in README.txt.
        schema:
          type: string
          enum:
          - EN
          - ZH
          - orig
          default: orig
      responses:
        '200':
          description: The artifact. Markdown containing only a transcript is inline; other artifacts are attachments.
          headers:
            Content-Disposition:
              schema:
                type: string
              description: inline; filename="…" for Markdown containing only a transcript, including full.md when no summary exists. attachment otherwise.
            Cache-Control:
              schema:
                type: string
                enum:
                - private, no-store
                - public, s-maxage=300, stale-while-revalidate=86400
              description: Origin cache policy. Markdown containing only a transcript uses the public policy; all other artifacts use private, no-store. The CDN may consume shared-cache directives.
            Access-Control-Expose-Headers:
              schema:
                type: string
                const: Content-Disposition, Content-Length, Content-Range, X-BidClub-PDF, X-BidClub-PDF-Renderer, X-BidClub-Language, X-BidClub-Language-Fallback
            Content-Length:
              schema:
                type: integer
                minimum: 0
              description: Response body size in bytes when known before streaming.
            Content-Range:
              schema:
                type: string
              description: Byte range served when the hosting layer answers a range request.
            X-BidClub-Language:
              schema:
                type: string
                enum:
                - EN
                - ZH
              description: Summary language for summary/full artifacts, source language for transcript-only artifacts. A full artifact can contain a transcript in another language.
            X-BidClub-Language-Fallback:
              schema:
                type: string
                enum:
                - source
                - none
              description: source when a requested translated summary was unavailable; none otherwise. This does not promise a translated transcript.
            X-BidClub-PDF:
              schema:
                type: string
              description: 'PDF responses only: whether the object was cached or freshly rendered.'
            X-BidClub-PDF-Renderer:
              schema:
                type: string
              description: 'PDF responses only: renderer identity, part of the cache key.'
          content:
            text/markdown:
              schema:
                type: string
            text/plain:
              schema:
                type: string
            application/pdf:
              schema:
                type: string
                format: binary
        '404':
          description: Unknown slug, unsupported file name, or no content for the requested artifact.
          content:
            text/plain:
              schema:
                type: string
        '502':
          description: PDF is temporarily unavailable.
          content:
            text/plain:
              schema:
                type: string
      tags:
      - Dl
  /dl/show/{show}/{file}:
    get:
      operationId: downloadShowArchive
      summary: Download a whole show as a ZIP
      description: Streams a ZIP containing available published artifacts for one show, plus a README.txt recording unavailable artifacts and language fallbacks. Assembly uses one database listing and is subject to its row cap; use paginated JSON for complete exports of large shows. A large PDF archive can take minutes. Errors are short plain-text bodies, not JSON.
      x-notes: File routes can run for up to 300 seconds. Most responses use private, no-store; single-episode Markdown containing only a transcript is served inline with public, s-maxage=300, stale-while-revalidate=86400. PDF objects are reused from storage, while PDF responses and show ZIPs remain private, no-store. Automated clients MUST use the JSON API (/api/v1/episodes/{slug}) for polling or bulk access.
      parameters:
      - name: show
        in: path
        required: true
        description: Show id in slug form. Note this path accepts hyphens only and at most 80 characters — a narrower pattern than the api show query parameter.
        schema:
          type: string
          pattern: ^[a-z0-9](?:[a-z0-9-]{0,78}[a-z0-9])?$
      - name: file
        in: path
        required: true
        description: summary = TL;DR + digest, transcript = transcript only, full = both. If only a summary or transcript exists, full returns that available section. md keeps Markdown structure, txt strips most of it, pdf is typeset.
        schema:
          type: string
          pattern: ^(summary|transcript|full)\.(md|txt|pdf)$
      - name: lang
        in: query
        required: false
        description: Requested edition. Case-insensitive; any other value (including omission) means orig, the episode's source language. Translated summaries require both TL;DR and digest translations; otherwise the source summary is served. Transcripts always retain the source language, so full can combine translated summaries with source transcripts. Single-episode responses report summary fallback in X-BidClub-Language-Fallback; show ZIPs record it per episode in README.txt.
        schema:
          type: string
          enum:
          - EN
          - ZH
          - orig
          default: orig
      responses:
        '200':
          description: The streamed archive, as an attachment.
          headers:
            Content-Disposition:
              schema:
                type: string
              description: attachment; filename="…" (RFC 5987 filename* is added for CJK names).
            Cache-Control:
              schema:
                type: string
                const: private, no-store
            Access-Control-Expose-Headers:
              schema:
                type: string
                const: Content-Disposition, Content-Length, Content-Range, X-BidClub-PDF, X-BidClub-PDF-Renderer, X-BidClub-Language, X-BidClub-Language-Fallback
            Content-Length:
              schema:
                type: integer
                minimum: 0
              description: Response body size in bytes when known before streaming.
            Content-Range:
              schema:
                type: string
              description: Byte range served when the hosting layer answers a range request.
          content:
            application/zip:
              schema:
                type: string
                format: binary
        '404':
          description: Unknown show, unsupported file name, or no published episodes.
          content:
            text/plain:
              schema:
                type: string
        '502':
          description: Podcast download is temporarily unavailable.
          content:
            text/plain:
              schema:
                type: string
      tags:
      - Dl