EpisodeListResponse

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/bidclub-ai/json-schema/bidclub-ai-episode-list-response-schema.json",
  "title": "EpisodeListResponse",
  "x-generated": "2026-11-02",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/bidclub-ai-openapi.json#/components/schemas/EpisodeListResponse",
  "type": "object",
  "required": [
    "episodes",
    "pagination",
    "artifacts"
  ],
  "properties": {
    "episodes": {
      "type": "array",
      "items": {
        "$ref": "#/$defs/EpisodeListItem"
      }
    },
    "pagination": {
      "$ref": "#/$defs/Pagination"
    },
    "artifacts": {
      "type": "string",
      "description": "Constant hint string naming the per-episode JSON and file routes."
    }
  },
  "$defs": {
    "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"
            }
          }
        }
      }
    },
    "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."
        }
      }
    }
  }
}