{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/audivo-dev/json-schema/audivo-dev-episodes-list-response-schema.json",
  "title": "EpisodesListResponse",
  "x-generated": "2026-11-10",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/audivo-dev-catalog-api-openapi.yml#/components/schemas/EpisodesListResponse",
  "type": "object",
  "additionalProperties": false,
  "required": [
    "data",
    "next_cursor"
  ],
  "properties": {
    "data": {
      "type": "array",
      "maxItems": 100,
      "items": {
        "$ref": "#/$defs/EpisodeSummary"
      }
    },
    "next_cursor": {
      "$ref": "#/$defs/NullableCursor"
    }
  },
  "$defs": {
    "CreditAmount": {
      "type": "integer",
      "minimum": 0,
      "maximum": 9007199254740991,
      "description": "A non-negative JavaScript-safe integer credit amount. The upper bound matches `Number.MAX_SAFE_INTEGER`, which is enforced by the domain ledger so arithmetic and JSON round-trips cannot silently lose cents worth of credit precision."
    },
    "Cursor": {
      "type": "string",
      "pattern": "^[A-Za-z0-9_-]{1,512}$",
      "description": "An opaque pagination cursor. Callers must treat it as opaque."
    },
    "EpisodeGuid": {
      "type": "string",
      "minLength": 1,
      "maxLength": 512,
      "description": "An episode GUID as published in the feed's `<guid>` element. Used verbatim — GUIDs are case- and whitespace-significant."
    },
    "EpisodeId": {
      "type": "string",
      "pattern": "^ep_[a-z2-7]{16}$",
      "description": "Canonical episode identifier."
    },
    "EpisodeSummary": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "episode_id",
        "show_id",
        "guid",
        "title",
        "published_at",
        "publisher_transcript_available",
        "is_cached"
      ],
      "description": "Episode metadata, publisher-transcript presence, cache availability, and a credit estimate.\n\n**`is_cached` is `null` on a listing.** Knowing it requires the episode's asset revision, which is a network probe of the audio per episode — a cost a browse surface must not pay a hundred times over. `POST /v1/quotes` probes the handful of episodes it is actually pricing and reports the real answer there. A listing therefore says \"not determined\", never `false`, so a caller cannot read an unprobed episode as a known cache miss.",
      "properties": {
        "episode_id": {
          "$ref": "#/$defs/EpisodeId"
        },
        "show_id": {
          "$ref": "#/$defs/ShowId"
        },
        "guid": {
          "$ref": "#/$defs/EpisodeGuid"
        },
        "title": {
          "type": "string",
          "minLength": 1,
          "maxLength": 500
        },
        "published_at": {
          "type": "string",
          "format": "date-time"
        },
        "duration_sec": {
          "description": "Feed-published duration if known, else `null`.",
          "anyOf": [
            {
              "type": "number",
              "minimum": 0,
              "maximum": 129600
            },
            {
              "enum": [
                null
              ]
            }
          ]
        },
        "publisher_transcript_available": {
          "type": "boolean"
        },
        "is_cached": {
          "description": "`true` or `false` where the surface probed the audio; `null` on a listing, which does not. See the note on this schema.",
          "anyOf": [
            {
              "type": "boolean"
            },
            {
              "enum": [
                null
              ]
            }
          ]
        },
        "estimated_credits": {
          "description": "A credit estimate for transcribing this episode fresh, if not cached.",
          "anyOf": [
            {
              "$ref": "#/$defs/CreditAmount"
            },
            {
              "enum": [
                null
              ]
            }
          ]
        }
      }
    },
    "NullableCursor": {
      "description": "An opaque pagination cursor, or `null` when there is no next page.",
      "anyOf": [
        {
          "$ref": "#/$defs/Cursor"
        },
        {
          "enum": [
            null
          ]
        }
      ]
    },
    "ShowId": {
      "type": "string",
      "pattern": "^sh_[a-z2-7]{16}$",
      "description": "Canonical show identifier."
    }
  }
}