schemaVersion: "llms-index.v1"
openapi: "3.1.0"
info:
  title: "PlatPhorm Podcasts API"
  version: "1.1.1"
  description: "Public Media Library and Source-Attributed Player. Ask once or paste one public URL. Find, resolve, play, save, and share podcasts, radio, recordings, music, and playlists with attribution. The universal prompt uses grounded retrieval and an optional Vercel AI Gateway model; URL resolution and playback remain source-backed. Durable activity relates plays, follows, votes, playlist adds, and freshness to content records without exposing persistent user identity. Operator controls are governed by PLATPHORM_PROTECTED and the backend PlatPhorm key policy."
  contact:
    name: "PlatPhorm Support"
    email: "support@platphormnews.com"
    url: "https://platphormnews.com/support"
tags:
  - name: "PlatPhorm Podcasts"
    description: "Public media discovery, resolution, playback, persistence, and platform protocol routes."
servers:
  - url: "https://podcasts.platphormnews.com"
    description: "Production"
x-platphorm-mcp:
  endpoint: "https://podcasts.platphormnews.com/api/mcp"
  transport: "json-rpc-2.0"
  protocolVersion: "2026-07-28"
  supportedProtocolVersions:
    - "2026-07-28"
    - "2024-11-05"
  methods:
    - "server/discover"
    - "ping"
    - "tools/list"
    - "tools/call"
    - "resources/list"
    - "resources/read"
    - "prompts/list"
    - "prompts/get"
  legacyCompatibility:
    protocolVersion: "2024-11-05"
    initialize: true
  publicTools:
    - "get_podcasts_info"
    - "get_podcasts_status"
    - "get_storage_status"
    - "resolve_podcast_url"
    - "inspect_media_reference"
    - "discover_radio_stations"
    - "discover_live_channels"
    - "validate_feed_dry_run"
    - "validate_xml_feed"
    - "validate_json_feed"
    - "list_feeds"
    - "get_feed"
    - "list_episodes"
    - "get_episode"
    - "search_podcasts"
    - "search_media"
    - "get_media"
    - "get_collection"
    - "resolve_source"
    - "validate_source"
    - "list_live_media"
    - "list_nearby_stations"
    - "get_playback_capability"
    - "get_attribution"
    - "get_ranking"
    - "get_discovery_graph"
    - "compose_playlist"
    - "create_playlist"
    - "list_playlists"
    - "get_playlist"
    - "list_tags"
    - "list_categories"
    - "get_playback_info"
    - "create_local_playlist"
    - "create_share_packet"
    - "get_share_page"
    - "list_podcast_examples"
    - "get_integrations_status"
    - "get_web_status"
    - "get_maintenance_workflow_status"
    - "get_web_manifest"
    - "list_podcasts_fingerprints"
    - "lookup_podcasts_provenance"
    - "verify_podcasts_provenance"
  protectedTools:
    - "ingest_feed"
    - "refresh_feed"
    - "ingest_episode"
    - "archive_episode_media"
    - "create_clip"
    - "persist_playlist"
    - "generate_tags"
    - "score_episode_emoji"
    - "publish_show_to_opencontent"
    - "publish_summary_to_docs"
    - "export_episodes_to_sheets"
    - "validate_feed_with_spec"
    - "register_feed_with_monitor"
    - "launch_browserops_journey"
    - "create_evals_suite"
    - "create_agentui_workflow"
    - "create_claws_toolchain"
    - "register_catalog_capability"
    - "send_trace_update"
    - "rebuild_podcasts_fingerprints"
    - "create_podcasts_provenance"
  resources:
    - "podcasts://feeds"
    - "podcasts://feed/{id}"
    - "podcasts://episodes"
    - "podcasts://media-inspection"
    - "podcasts://live-channels"
    - "podcasts://episode/{id}"
    - "podcasts://playlists"
    - "podcasts://shares"
    - "podcasts://clips"
    - "podcasts://integrations"
    - "podcasts://archive-status"
    - "podcasts://metrics"
    - "podcasts://examples"
    - "podcasts://llms"
    - "podcasts://openapi"
    - "podcasts://web-status"
  prompts:
    - "import_podcast_feed"
    - "resolve_podcast_link"
    - "create_cross_platform_playlist"
    - "create_podcast_playlist"
    - "create_podcast_clip"
    - "publish_podcast_to_opencontent"
    - "create_podcast_docs_summary"
    - "export_podcast_sheet_matrix"
    - "validate_podcast_feed"
    - "create_podcast_browserops_journey"
    - "create_podcast_evals_suite"
  auth:
    publicIntrospection: true
    protectedToolCalls: "PLATPHORM_API_KEY when PLATPHORM_PROTECTED=1"
components:
  securitySchemes:
    PlatformApiKey:
      type: "apiKey"
      in: "header"
      name: "X-PlatPhorm-API-Key"
      description: "Only enforced when PLATPHORM_PROTECTED=1."
    PlatformBearer:
      type: "http"
      scheme: "bearer"
      bearerFormat: "PLATPHORM_API_KEY"
      description: "Only enforced when PLATPHORM_PROTECTED=1."
  schemas:
    SuccessResponse:
      type: "object"
      required:
        - "ok"
        - "data"
      properties:
        ok:
          const: true
        data:
          type: "object"
          additionalProperties: true
      additionalProperties: false
    ErrorDetail:
      type: "object"
      required:
        - "code"
        - "message"
      properties:
        code:
          type: "string"
        message:
          type: "string"
        details:
          type: "object"
          additionalProperties: true
      additionalProperties: false
    ErrorResponse:
      type: "object"
      required:
        - "ok"
        - "error"
      properties:
        ok:
          const: false
        error:
          "$ref": "#/components/schemas/ErrorDetail"
      additionalProperties: false
    WebStatusSystems:
      type: "object"
      description: "Cached operational-plane projection. Rendering this status must not fan out to media providers."
      required:
        - "observationMode"
        - "providerProbeMode"
        - "vercelFrontend"
        - "cloudflareWorker"
        - "d1"
        - "kv"
        - "r2"
        - "queues"
        - "workflows"
        - "search"
        - "ranking"
        - "ai"
        - "localeLocality"
        - "relay"
        - "providerHealth"
        - "rss"
        - "openapi"
        - "mcp"
        - "pwa"
      properties:
        observationMode:
          const: "cached_backend_status"
        providerProbeMode:
          const: "no_request_fanout"
        vercelFrontend:
          type: "string"
        cloudflareWorker:
          type: "string"
        d1:
          type: "string"
        kv:
          type: "string"
        r2:
          type: "string"
        queues:
          type: "string"
        workflows:
          type: "string"
        search:
          type: "string"
        ranking:
          type: "string"
        ai:
          type: "string"
        localeLocality:
          type: "string"
        relay:
          type: "string"
        providerHealth:
          type: "string"
        rss:
          type: "string"
        openapi:
          type: "string"
        mcp:
          type: "string"
        pwa:
          type: "string"
      additionalProperties: false
paths:
  "/api/health":
    get:
      summary: "Public service health."
      x-platphorm:
        output:
          required:
            - "service"
            - "version"
            - "environment"
            - "status"
            - "timestamp"
          properties:
            service:
{}
            version:
{}
            environment:
{}
            status:
{}
            timestamp:
{}
            uptime:
{}
            database:
{}
            mcp:
{}
            trace:
{}
            archive:
{}
            routeComplianceScore:
{}
            observabilityComplianceScore:
{}
            discoveryStatus:
{}
            rssStatus:
{}
            sitemapStatus:
{}
            llmsStatus:
{}
            openapiStatus:
{}
            trustedDomainStatus:
{}
            lastNetworkSyncAt:
{}
            lastSitemapSyncAt:
{}
            lastFeedSyncAt:
{}
            vercelMetadataCaptured:
{}
            vercelMetadata:
{}
            operatorControls:
{}
            publicReadOnly:
{}
      responses:
        200:
          description: "Standard PlatPhorm response."
          content:
            "application/json":
              schema:
                "$ref": "#/components/schemas/SuccessResponse"
      operationId: "getApiHealth"
      tags:
        - "PlatPhorm Podcasts"
  "/api/v1/health":
    get:
      summary: "Versioned public service health."
      responses:
        200:
          description: "Standard PlatPhorm response."
          content:
            "application/json":
              schema:
                "$ref": "#/components/schemas/SuccessResponse"
      operationId: "getApiV1Health"
      tags:
        - "PlatPhorm Podcasts"
  "/api/docs":
    get:
      summary: "Read the public human API documentation page."
      responses:
        200:
          description: "Human-readable API documentation."
          content:
            "text/html":
              schema:
                type: "string"
      operationId: "getApiDocs"
      tags:
        - "PlatPhorm Podcasts"
  "/api/v1/feeds":
    get:
      summary: "List public feed sources."
      responses:
        200:
          description: "Standard PlatPhorm response."
          content:
            "application/json":
              schema:
                "$ref": "#/components/schemas/SuccessResponse"
      operationId: "getApiV1Feeds"
      tags:
        - "PlatPhorm Podcasts"
    post:
      summary: "Submit one public feed URL for durable indexing; bulk ingestion and destructive operations remain protected."
      responses:
        200:
          description: "Standard PlatPhorm response."
          content:
            "application/json":
              schema:
                "$ref": "#/components/schemas/SuccessResponse"
      operationId: "postApiV1Feeds"
      tags:
        - "PlatPhorm Podcasts"
  "/api/v1/media/{id}":
    get:
      summary: "Retrieve one canonical persisted public media item and bounded playback candidates."
      parameters:
        - name: "id"
          in: "path"
          required: true
          schema:
            type: "string"
            maxLength: 220
      responses:
        200:
          description: "Source-attributed media item persisted in Cloudflare D1."
        404:
          description: "Media item not found."
      operationId: "getApiV1MediaId"
      tags:
        - "PlatPhorm Podcasts"
  "/api/v1/media/search":
    get:
      summary: "Search persisted public submissions and the provider-neutral media index; explicit Archive.org searches asynchronously index normalized remote variants."
      description: "Searches D1 FTS and performs bounded Archive.org discovery when needed. Search-discovered records are metadata-indexed in D1 on demand; source media bytes remain remote and are streamed only when selected."
      responses:
        200:
          description: "Standard PlatPhorm response."
          content:
            "application/json":
              schema:
                "$ref": "#/components/schemas/SuccessResponse"
      operationId: "getApiV1MediaSearch"
      tags:
        - "PlatPhorm Podcasts"
  "/api/v1/media/recent":
    get:
      summary: "List recently published or indexed records from the public provider-neutral media index."
      description: "Returns bounded D1 metadata and playback-variant summaries for Library discovery. Source media bytes remain remote and are streamed only when selected."
      responses:
        200:
          description: "Standard PlatPhorm response."
          content:
            "application/json":
              schema:
                "$ref": "#/components/schemas/SuccessResponse"
      operationId: "getApiV1MediaRecent"
      tags:
        - "PlatPhorm Podcasts"
  "/api/v1/activity/recent":
    get:
      summary: "List a unified, source-attributed timeline of newly added feeds, playlists, and media records."
      description: "Reads the typed Cloudflare D1 activity ledger with a bounded application-record fallback. Refresh activity does not masquerade as a new addition."
      responses:
        200:
          description: "Standard PlatPhorm response."
          content:
            "application/json":
              schema:
                "$ref": "#/components/schemas/SuccessResponse"
      operationId: "getApiV1ActivityRecent"
      tags:
        - "PlatPhorm Podcasts"
  "/api/v1/activity/played":
    post:
      summary: "Persist one source-attributed play observation and related metadata for the public recent activity stream."
      description: "The action is related to a content record, not a user profile. One-way short-lived deduplication may be used for system integrity; raw identity and expiring playback URLs are not published."
      responses:
        200:
          description: "Standard PlatPhorm response."
          content:
            "application/json":
              schema:
                "$ref": "#/components/schemas/SuccessResponse"
      operationId: "postApiV1ActivityPlayed"
      tags:
        - "PlatPhorm Podcasts"
  "/api/v1/library":
    get:
      summary: "Page through the deduplicated public media library across feeds, entries, media, playlists, and playlist items."
      description: "Cloudflare D1 applies search, format, playback-state filtering, canonical deduplication, global ordering, totals, and stable offsets before returning one bounded page."
      responses:
        200:
          description: "Standard PlatPhorm response."
          content:
            "application/json":
              schema:
                "$ref": "#/components/schemas/SuccessResponse"
      operationId: "getApiV1Library"
      tags:
        - "PlatPhorm Podcasts"
  "/api/v1/library/lookup":
    get:
      summary: "Find the durable feed, playlist, or media route for one canonical public source URL before resolving it again."
      description: "Prefers typed Cloudflare D1 activity and falls back to the persistent feed and playlist indexes. It never fetches or mutates the submitted source."
      responses:
        200:
          description: "Standard PlatPhorm response."
          content:
            "application/json":
              schema:
                "$ref": "#/components/schemas/SuccessResponse"
      operationId: "getApiV1LibraryLookup"
      tags:
        - "PlatPhorm Podcasts"
  "/api/v1/archive/discovery/status":
    get:
      summary: "Read scheduled Archive.org discovery runs, continuation acceptance history, and aggregate remote-variant verification state."
      description: "Includes a public-safe assertion that the internal 125-item fixture completed the expected non-null cursor chain, normalized failed-check diagnostics, the latest bounded fixture refresh summary, and fixture-specific dead-letter counts. Fixture records, raw failure payloads, and mutation controls remain protected."
      responses:
        200:
          description: "Standard PlatPhorm response."
          content:
            "application/json":
              schema:
                "$ref": "#/components/schemas/SuccessResponse"
      operationId: "getApiV1ArchiveDiscoveryStatus"
      tags:
        - "PlatPhorm Podcasts"
  "/api/v1/radio/stations":
    get:
      summary: "Discover healthy public internet-radio stations through Radio Browser and persist returned station metadata to the public Cloudflare D1 index."
      description: "Results preserve station and Radio Browser attribution. Audio remains at the station stream host and is relayed on demand only when selected."
      responses:
        200:
          description: "Standard PlatPhorm response."
          content:
            "application/json":
              schema:
                "$ref": "#/components/schemas/SuccessResponse"
      operationId: "getApiV1RadioStations"
      tags:
        - "PlatPhorm Podcasts"
  "/api/v1/live/channels":
    get:
      summary: "Discover public live channels through bounded IPTV-org category, country, language, or region playlists and persist returned source metadata to Cloudflare D1."
      description: "Adult scopes are excluded. Channel health and access restrictions remain honest, source attribution is retained, and live bytes remain remote until a user selects playback through the signed relay."
      responses:
        200:
          description: "Standard PlatPhorm response."
          content:
            "application/json":
              schema:
                "$ref": "#/components/schemas/SuccessResponse"
      operationId: "getApiV1LiveChannels"
      tags:
        - "PlatPhorm Podcasts"
  "/api/v1/live/gamestream":
    get:
      summary: "List bounded, source-attributed GameStream content with an honest RSS fallback when its JSON API is degraded."
      responses:
        200:
          description: "Standard PlatPhorm response."
          content:
            "application/json":
              schema:
                "$ref": "#/components/schemas/SuccessResponse"
      operationId: "getApiV1LiveGamestream"
      tags:
        - "PlatPhorm Podcasts"
  "/api/v1/media/space":
    get:
      summary: "Search trusted PlatPhorm Space articles and public YouTube media with bounded API and RSS fallback behavior."
      description: "Space articles are indexed as source-attributed metadata. YouTube children are playable through provider embeds in the one persistent player; HTML article pages are never treated as relay media."
      responses:
        200:
          description: "Standard PlatPhorm response."
          content:
            "application/json":
              schema:
                "$ref": "#/components/schemas/SuccessResponse"
      operationId: "getApiV1MediaSpace"
      tags:
        - "PlatPhorm Podcasts"
  "/api/v1/media/relay":
    get:
      summary: "Stream one resolved public media URL through a short-lived signed Cloudflare relay."
      description: "The public resolver issues the bounded token. The relay preserves byte ranges and source attribution, does not store media bytes, and rejects unsigned or expired requests."
      responses:
        200:
          description: "Standard PlatPhorm response."
          content:
            "application/json":
              schema:
                "$ref": "#/components/schemas/SuccessResponse"
      operationId: "getApiV1MediaRelay"
      tags:
        - "PlatPhorm Podcasts"
    head:
      summary: "Inspect a signed on-demand media relay response without transferring its body."
      responses:
        200:
          description: "Standard PlatPhorm response."
          content:
            "application/json":
              schema:
                "$ref": "#/components/schemas/SuccessResponse"
      operationId: "headApiV1MediaRelay"
      tags:
        - "PlatPhorm Podcasts"
  "/api/v1/playback/resolve":
    get:
      summary: "Describe the in-app playback verification contract."
      responses:
        200:
          description: "Standard PlatPhorm response."
          content:
            "application/json":
              schema:
                "$ref": "#/components/schemas/SuccessResponse"
      operationId: "getApiV1PlaybackResolve"
      tags:
        - "PlatPhorm Podcasts"
    post:
      summary: "Verify a relay, browser-capable direct source, or allowlisted provider embed before any Play control is enabled."
      description: "Persists public-safe capability evidence without storing expiring signed URLs or source media bytes. Provider embeds remain inside the one persistent PlatPhorm player."
      responses:
        200:
          description: "Standard PlatPhorm response."
          content:
            "application/json":
              schema:
                "$ref": "#/components/schemas/SuccessResponse"
      operationId: "postApiV1PlaybackResolve"
      tags:
        - "PlatPhorm Podcasts"
  "/api/v1/media/variants/verify":
    post:
      summary: "Persist verification state for already-indexed media variants in Cloudflare D1."
      description: "Accepts bounded public-safe verification results from the playback verifier. It never stores signed relay URLs or media bytes and requires PLATPHORM_API_KEY."
      security:
        - PlatformApiKey:
[]
        - PlatformBearer:
[]
      responses:
        200:
          description: "Standard PlatPhorm response."
          content:
            "application/json":
              schema:
                "$ref": "#/components/schemas/SuccessResponse"
      operationId: "postApiV1MediaVariantsVerify"
      tags:
        - "PlatPhorm Podcasts"
  "/api/v1/operations/dead-letters":
    get:
      summary: "List bounded durable dead-letter records from the Cloudflare Queue consumer."
      description: "Protected operator read. URL-bearing jobs are redacted before D1 persistence."
      security:
        - PlatformApiKey:
[]
        - PlatformBearer:
[]
      responses:
        200:
          description: "Standard PlatPhorm response."
          content:
            "application/json":
              schema:
                "$ref": "#/components/schemas/SuccessResponse"
      operationId: "getApiV1OperationsDeadLetters"
      tags:
        - "PlatPhorm Podcasts"
  "/api/v1/operations/duplicates":
    get:
      summary: "Inspect recent protected duplicate cleanup runs and duplicate-to-canonical ledger entries."
      security:
        - PlatformBearer:
[]
        - PlatformHeader:
[]
      responses:
        200:
          description: "Bounded cleanup evidence."
        401:
          description: "PLATPHORM_API_KEY required."
      operationId: "getApiV1OperationsDuplicates"
      tags:
        - "PlatPhorm Podcasts"
    post:
      summary: "Preview or apply recoverable duplicate cleanup without deleting source records."
      security:
        - PlatformBearer:
[]
        - PlatformHeader:
[]
      responses:
        200:
          description: "Cleanup applied."
        202:
          description: "Cleanup preview completed."
        401:
          description: "PLATPHORM_API_KEY required."
      operationId: "postApiV1OperationsDuplicates"
      tags:
        - "PlatPhorm Podcasts"
  "/api/v1/operations/ranking-materialization":
    get:
      summary: "Inspect persisted ranking-signal rollups and recent materialization runs."
      description: "Public evidence includes bounded aggregate counts for Useful votes, qualified plays, successful validations, follows, playlist additions, flags, and failures."
      responses:
        200:
          description: "Standard PlatPhorm response."
          content:
            "application/json":
              schema:
                "$ref": "#/components/schemas/SuccessResponse"
      operationId: "getApiV1OperationsRankingMaterialization"
      tags:
        - "PlatPhorm Podcasts"
    post:
      summary: "Queue a fresh ranking-signal materialization run."
      description: "Protected operator action. The Cloudflare Queue recomputes transparent D1 rollups without treating a Useful vote as playback validation."
      security:
        - PlatformApiKey:
[]
        - PlatformBearer:
[]
      responses:
        200:
          description: "Standard PlatPhorm response."
          content:
            "application/json":
              schema:
                "$ref": "#/components/schemas/SuccessResponse"
      operationId: "postApiV1OperationsRankingMaterialization"
      tags:
        - "PlatPhorm Podcasts"
  "/api/v1/operations/maintenance-workflows":
    get:
      summary: "Inspect durable Cloudflare maintenance Workflow lifecycle state."
      description: "Public-safe D1 evidence reports the current stage and terminal state for scheduled discovery, health verification, IPTV refresh, collection expansion, ranking materialization, and continuation acceptance. Raw errors and secrets are excluded."
      responses:
        200:
          description: "Standard PlatPhorm response."
          content:
            "application/json":
              schema:
                "$ref": "#/components/schemas/SuccessResponse"
      operationId: "getApiV1OperationsMaintenanceWorkflows"
      tags:
        - "PlatPhorm Podcasts"
    post:
      summary: "Start one durable Cloudflare maintenance Workflow instance."
      description: "Protected operator action. The Workflow executes retryable stages and delegates bounded item work to the Cloudflare Queue."
      security:
        - PlatformApiKey:
[]
        - PlatformBearer:
[]
      responses:
        200:
          description: "Standard PlatPhorm response."
          content:
            "application/json":
              schema:
                "$ref": "#/components/schemas/SuccessResponse"
      operationId: "postApiV1OperationsMaintenanceWorkflows"
      tags:
        - "PlatPhorm Podcasts"
  "/api/v1/rsscloud/registrations":
    get:
      summary: "Inspect protected RSSCloud registration, renewal, challenge, and notification evidence."
      description: "Returns bounded D1 lifecycle records without exposing callback capability tokens."
      security:
        - PlatformApiKey:
[]
        - PlatformBearer:
[]
      responses:
        200:
          description: "Standard PlatPhorm response."
          content:
            "application/json":
              schema:
                "$ref": "#/components/schemas/SuccessResponse"
      operationId: "getApiV1RsscloudRegistrations"
      tags:
        - "PlatPhorm Podcasts"
    post:
      summary: "Opt one persisted RSSCloud-declaring feed into callback registration."
      description: "Protected operator action. Registration is explicit, bounded, source-matched, and renewed by scheduled Cloudflare maintenance."
      security:
        - PlatformApiKey:
[]
        - PlatformBearer:
[]
      responses:
        200:
          description: "Standard PlatPhorm response."
          content:
            "application/json":
              schema:
                "$ref": "#/components/schemas/SuccessResponse"
      operationId: "postApiV1RsscloudRegistrations"
      tags:
        - "PlatPhorm Podcasts"
  "/api/v1/operations/playlist-continuation-fixture":
    get:
      summary: "Inspect the internal 125-item production continuation fixture and its D1 refresh ledger."
      description: "Protected acceptance evidence includes item integrity, exact cursor-chain checks, and scheduled D1 assertion history. The fixture is internal and excluded from public playlists and discovery."
      security:
        - PlatformApiKey:
[]
        - PlatformBearer:
[]
      responses:
        200:
          description: "Standard PlatPhorm response."
          content:
            "application/json":
              schema:
                "$ref": "#/components/schemas/SuccessResponse"
      operationId: "getApiV1OperationsPlaylistContinuationFixture"
      tags:
        - "PlatPhorm Podcasts"
    post:
      summary: "Assert, seed, or advance the internal production continuation fixture."
      description: "Assert performs a read-only integrity evaluation and records its result. Seed resets only the named internal fixture. Advance queues one bounded page and persists before/after cursors in D1."
      security:
        - PlatformApiKey:
[]
        - PlatformBearer:
[]
      responses:
        200:
          description: "Standard PlatPhorm response."
          content:
            "application/json":
              schema:
                "$ref": "#/components/schemas/SuccessResponse"
      operationId: "postApiV1OperationsPlaylistContinuationFixture"
      tags:
        - "PlatPhorm Podcasts"
  "/api/v1/operations/dead-letters/{id}":
    get:
      summary: "Inspect one durable dead-letter record and its safe replay metadata."
      security:
        - PlatformApiKey:
[]
        - PlatformBearer:
[]
      responses:
        200:
          description: "Standard PlatPhorm response."
          content:
            "application/json":
              schema:
                "$ref": "#/components/schemas/SuccessResponse"
      operationId: "getApiV1OperationsDeadLettersId"
      tags:
        - "PlatPhorm Podcasts"
  "/api/v1/operations/dead-letters/{id}/replay":
    post:
      summary: "Replay one pending, replay-safe dead-letter job through the primary Cloudflare Queue."
      security:
        - PlatformApiKey:
[]
        - PlatformBearer:
[]
      responses:
        200:
          description: "Standard PlatPhorm response."
          content:
            "application/json":
              schema:
                "$ref": "#/components/schemas/SuccessResponse"
      operationId: "postApiV1OperationsDeadLettersIdReplay"
      tags:
        - "PlatPhorm Podcasts"
  "/api/v1/operations/dead-letters/{id}/dismiss":
    post:
      summary: "Dismiss one pending dead-letter record without deleting its evidence."
      security:
        - PlatformApiKey:
[]
        - PlatformBearer:
[]
      responses:
        200:
          description: "Standard PlatPhorm response."
          content:
            "application/json":
              schema:
                "$ref": "#/components/schemas/SuccessResponse"
      operationId: "postApiV1OperationsDeadLettersIdDismiss"
      tags:
        - "PlatPhorm Podcasts"
  "/api/v1/community/actions":
    get:
      summary: "Read persisted public curation actions for one indexed target."
      responses:
        200:
          description: "Standard PlatPhorm response."
          content:
            "application/json":
              schema:
                "$ref": "#/components/schemas/SuccessResponse"
      operationId: "getApiV1CommunityActions"
      tags:
        - "PlatPhorm Podcasts"
    post:
      summary: "Record one anonymous daily community curation action with a scoped fingerprint."
      description: "A useful action may include a canonical followOnUseful target. The backend persists that source or parent-feed follow before accepting the useful vote, so ranking, activity, indexing, and follow state share one durable outcome."
      responses:
        200:
          description: "Standard PlatPhorm response."
          content:
            "application/json":
              schema:
                "$ref": "#/components/schemas/SuccessResponse"
      operationId: "postApiV1CommunityActions"
      tags:
        - "PlatPhorm Podcasts"
  "/api/v1/community/remediation":
    post:
      summary: "Queue one authenticated community report for durable Cloudflare remediation processing."
      security:
        - PlatformApiKey:
[]
        - PlatformBearer:
[]
      responses:
        200:
          description: "Standard PlatPhorm response."
          content:
            "application/json":
              schema:
                "$ref": "#/components/schemas/SuccessResponse"
      operationId: "postApiV1CommunityRemediation"
      tags:
        - "PlatPhorm Podcasts"
  "/api/v1/source-follows":
    get:
      summary: "Read the public follow state for one canonical source."
      responses:
        200:
          description: "Standard PlatPhorm response."
          content:
            "application/json":
              schema:
                "$ref": "#/components/schemas/SuccessResponse"
      operationId: "getApiV1SourceFollows"
      tags:
        - "PlatPhorm Podcasts"
    post:
      summary: "Persist an idempotent follow for one canonical public source."
      description: "Follows are positive ranking and discovery signals in their own right. They do not fabricate a separate useful vote; a useful vote with a canonical target does persist the corresponding follow."
      responses:
        200:
          description: "Standard PlatPhorm response."
          content:
            "application/json":
              schema:
                "$ref": "#/components/schemas/SuccessResponse"
      operationId: "postApiV1SourceFollows"
      tags:
        - "PlatPhorm Podcasts"
  "/api/v1/feed-catalog":
    get:
      summary: "List verified live podcast feeds and their dynamic playlist targets."
      responses:
        200:
          description: "Standard PlatPhorm response."
          content:
            "application/json":
              schema:
                "$ref": "#/components/schemas/SuccessResponse"
      operationId: "getApiV1FeedCatalog"
      tags:
        - "PlatPhorm Podcasts"
  "/api/v1/ingest":
    get:
      summary: "Describe public single-source podcast indexing ingest."
      responses:
        200:
          description: "Standard PlatPhorm response."
          content:
            "application/json":
              schema:
                "$ref": "#/components/schemas/SuccessResponse"
      operationId: "getApiV1Ingest"
      tags:
        - "PlatPhorm Podcasts"
    post:
      summary: "Ingest one public URL, feed, provider collection, direct media source, or iframe/embed snippet through the canonical resolver; bulk insertion and destructive operations remain protected."
      responses:
        200:
          description: "Standard PlatPhorm response."
          content:
            "application/json":
              schema:
                "$ref": "#/components/schemas/SuccessResponse"
      operationId: "postApiV1Ingest"
      tags:
        - "PlatPhorm Podcasts"
  "/api/v1/ingest/dry-run":
    post:
      summary: "Public dry-run URL resolution and feed parser evidence without server-side persistence."
      responses:
        200:
          description: "Standard PlatPhorm response."
          content:
            "application/json":
              schema:
                "$ref": "#/components/schemas/SuccessResponse"
      operationId: "postApiV1IngestDryRun"
      tags:
        - "PlatPhorm Podcasts"
  "/api/v1/resolve":
    get:
      summary: "Describe the URL resolver."
      responses:
        200:
          description: "Standard PlatPhorm response."
          content:
            "application/json":
              schema:
                "$ref": "#/components/schemas/SuccessResponse"
      operationId: "getApiV1Resolve"
      tags:
        - "PlatPhorm Podcasts"
    post:
      summary: "Resolve and persist RSS, Atom, JSON Feed, JSON:API compound catalogs, platform, playlist, episode, host, and direct media URLs with typed source observations, aliases, feed refresh state, and playable or honestly degraded capability evidence."
      responses:
        200:
          description: "Standard PlatPhorm response."
          content:
            "application/json":
              schema:
                "$ref": "#/components/schemas/SuccessResponse"
      operationId: "postApiV1Resolve"
      tags:
        - "PlatPhorm Podcasts"
  "/api/v1/imports/{id}":
    get:
      summary: "Read durable source-import progress by job id or playlist id."
      responses:
        200:
          description: "Standard PlatPhorm response."
          content:
            "application/json":
              schema:
                "$ref": "#/components/schemas/SuccessResponse"
      operationId: "getApiV1ImportsId"
      tags:
        - "PlatPhorm Podcasts"
  "/api/v1/storage/status":
    get:
      summary: "Runtime storage mode and archive configuration status."
      responses:
        200:
          description: "Standard PlatPhorm response."
          content:
            "application/json":
              schema:
                "$ref": "#/components/schemas/SuccessResponse"
      operationId: "getApiV1StorageStatus"
      tags:
        - "PlatPhorm Podcasts"
  "/api/v1/archive/remote-status":
    get:
      summary: "Read-only status of the configured Cloudflare archive Worker connection."
      responses:
        200:
          description: "Standard PlatPhorm response."
          content:
            "application/json":
              schema:
                "$ref": "#/components/schemas/SuccessResponse"
      operationId: "getApiV1ArchiveRemoteStatus"
      tags:
        - "PlatPhorm Podcasts"
  "/api/v1/analysis":
    post:
      summary: "Publicly persist one bounded, source-grounded analysis result or evidence record in the Cloudflare archive."
      responses:
        200:
          description: "Standard PlatPhorm response."
          content:
            "application/json":
              schema:
                "$ref": "#/components/schemas/SuccessResponse"
      operationId: "postApiV1Analysis"
      tags:
        - "PlatPhorm Podcasts"
  "/api/v1/providers/archive-org/items/{identifier}":
    get:
      summary: "Normalize one Archive.org item and its playable remote variants on demand without mirroring media bytes."
      responses:
        200:
          description: "Standard PlatPhorm response."
          content:
            "application/json":
              schema:
                "$ref": "#/components/schemas/SuccessResponse"
      operationId: "getApiV1ProvidersArchiveOrgItemsIdentifier"
      tags:
        - "PlatPhorm Podcasts"
    post:
      summary: "Persist normalized Archive.org metadata, attribution, rights, and remote URI variants in D1."
      security:
        - PlatformApiKey:
[]
        - PlatformBearer:
[]
      responses:
        200:
          description: "Standard PlatPhorm response."
          content:
            "application/json":
              schema:
                "$ref": "#/components/schemas/SuccessResponse"
      operationId: "postApiV1ProvidersArchiveOrgItemsIdentifier"
      tags:
        - "PlatPhorm Podcasts"
  "/api/v1/discovery":
    get:
      summary: "Public discovery manifest for Podcasts routes, capabilities, MCP, LLMS, graph, and Web Status."
      responses:
        200:
          description: "Standard PlatPhorm response."
          content:
            "application/json":
              schema:
                "$ref": "#/components/schemas/SuccessResponse"
      operationId: "getApiV1Discovery"
      tags:
        - "PlatPhorm Podcasts"
  "/api/v1/metrics":
    get:
      summary: "Public-safe runtime metrics from real archive, share, category, tag, and storage state."
      responses:
        200:
          description: "Standard PlatPhorm response."
          content:
            "application/json":
              schema:
                "$ref": "#/components/schemas/SuccessResponse"
      operationId: "getApiV1Metrics"
      tags:
        - "PlatPhorm Podcasts"
  "/api/v1/feeds/{id}":
    get:
      summary: "Get a feed source."
      responses:
        200:
          description: "Standard PlatPhorm response."
          content:
            "application/json":
              schema:
                "$ref": "#/components/schemas/SuccessResponse"
      operationId: "getApiV1FeedsId"
      tags:
        - "PlatPhorm Podcasts"
    put:
      summary: "Non-destructive feed source update status with runtime operator controls."
      security:
        - PlatformApiKey:
[]
        - PlatformBearer:
[]
      responses:
        200:
          description: "Standard PlatPhorm response."
          content:
            "application/json":
              schema:
                "$ref": "#/components/schemas/SuccessResponse"
      operationId: "putApiV1FeedsId"
      tags:
        - "PlatPhorm Podcasts"
    delete:
      summary: "Non-destructive archive request with runtime operator controls."
      security:
        - PlatformApiKey:
[]
        - PlatformBearer:
[]
      responses:
        200:
          description: "Standard PlatPhorm response."
          content:
            "application/json":
              schema:
                "$ref": "#/components/schemas/SuccessResponse"
      operationId: "deleteApiV1FeedsId"
      tags:
        - "PlatPhorm Podcasts"
  "/api/v1/feeds/{id}/sync":
    post:
      summary: "Resync an indexed public feed source with operator controls."
      security:
        - PlatformApiKey:
[]
        - PlatformBearer:
[]
      responses:
        200:
          description: "Standard PlatPhorm response."
          content:
            "application/json":
              schema:
                "$ref": "#/components/schemas/SuccessResponse"
      operationId: "postApiV1FeedsIdSync"
      tags:
        - "PlatPhorm Podcasts"
  "/api/v1/feeds/{id}/refresh":
    post:
      summary: "Scheduled or persistent feed refresh with runtime operator controls."
      security:
        - PlatformApiKey:
[]
        - PlatformBearer:
[]
      responses:
        200:
          description: "Standard PlatPhorm response."
          content:
            "application/json":
              schema:
                "$ref": "#/components/schemas/SuccessResponse"
      operationId: "postApiV1FeedsIdRefresh"
      tags:
        - "PlatPhorm Podcasts"
  "/api/v1/feeds/{id}/entries":
    get:
      summary: "List entries for one feed."
      responses:
        200:
          description: "Standard PlatPhorm response."
          content:
            "application/json":
              schema:
                "$ref": "#/components/schemas/SuccessResponse"
      operationId: "getApiV1FeedsIdEntries"
      tags:
        - "PlatPhorm Podcasts"
  "/api/v1/feeds/{id}/episodes":
    get:
      summary: "List playable episodes for one feed with pagination."
      responses:
        200:
          description: "Standard PlatPhorm response."
          content:
            "application/json":
              schema:
                "$ref": "#/components/schemas/SuccessResponse"
      operationId: "getApiV1FeedsIdEpisodes"
      tags:
        - "PlatPhorm Podcasts"
  "/api/v1/feeds/{id}/status":
    get:
      summary: "Get feed sync and archive status."
      responses:
        200:
          description: "Standard PlatPhorm response."
          content:
            "application/json":
              schema:
                "$ref": "#/components/schemas/SuccessResponse"
      operationId: "getApiV1FeedsIdStatus"
      tags:
        - "PlatPhorm Podcasts"
  "/api/v1/entries":
    get:
      summary: "List archived entries."
      responses:
        200:
          description: "Standard PlatPhorm response."
          content:
            "application/json":
              schema:
                "$ref": "#/components/schemas/SuccessResponse"
      operationId: "getApiV1Entries"
      tags:
        - "PlatPhorm Podcasts"
  "/api/v1/entries/search":
    get:
      summary: "Search archived entries."
      responses:
        200:
          description: "Standard PlatPhorm response."
          content:
            "application/json":
              schema:
                "$ref": "#/components/schemas/SuccessResponse"
      operationId: "getApiV1EntriesSearch"
      tags:
        - "PlatPhorm Podcasts"
  "/api/v1/entries/recent":
    get:
      summary: "List recent archived entries."
      responses:
        200:
          description: "Standard PlatPhorm response."
          content:
            "application/json":
              schema:
                "$ref": "#/components/schemas/SuccessResponse"
      operationId: "getApiV1EntriesRecent"
      tags:
        - "PlatPhorm Podcasts"
  "/api/v1/entries/archive":
    get:
      summary: "List archive entries and policy."
      responses:
        200:
          description: "Standard PlatPhorm response."
          content:
            "application/json":
              schema:
                "$ref": "#/components/schemas/SuccessResponse"
      operationId: "getApiV1EntriesArchive"
      tags:
        - "PlatPhorm Podcasts"
  "/api/v1/entries/{id}":
    get:
      summary: "Read one archived entry."
      responses:
        200:
          description: "Standard PlatPhorm response."
          content:
            "application/json":
              schema:
                "$ref": "#/components/schemas/SuccessResponse"
      operationId: "getApiV1EntriesId"
      tags:
        - "PlatPhorm Podcasts"
  "/api/v1/shows":
    get:
      summary: "List podcast shows/feed sources."
      responses:
        200:
          description: "Standard PlatPhorm response."
          content:
            "application/json":
              schema:
                "$ref": "#/components/schemas/SuccessResponse"
      operationId: "getApiV1Shows"
      tags:
        - "PlatPhorm Podcasts"
  "/api/v1/shows/{id}":
    get:
      summary: "Read one show."
      responses:
        200:
          description: "Standard PlatPhorm response."
          content:
            "application/json":
              schema:
                "$ref": "#/components/schemas/SuccessResponse"
      operationId: "getApiV1ShowsId"
      tags:
        - "PlatPhorm Podcasts"
  "/api/v1/shows/{id}/episodes":
    get:
      summary: "List show episodes."
      responses:
        200:
          description: "Standard PlatPhorm response."
          content:
            "application/json":
              schema:
                "$ref": "#/components/schemas/SuccessResponse"
      operationId: "getApiV1ShowsIdEpisodes"
      tags:
        - "PlatPhorm Podcasts"
  "/api/v1/episodes":
    get:
      summary: "List audio episodes."
      responses:
        200:
          description: "Standard PlatPhorm response."
          content:
            "application/json":
              schema:
                "$ref": "#/components/schemas/SuccessResponse"
      operationId: "getApiV1Episodes"
      tags:
        - "PlatPhorm Podcasts"
    post:
      summary: "Resolve and record one public episode URL; bulk insertion and destructive operations remain protected."
      responses:
        200:
          description: "Standard PlatPhorm response."
          content:
            "application/json":
              schema:
                "$ref": "#/components/schemas/SuccessResponse"
      operationId: "postApiV1Episodes"
      tags:
        - "PlatPhorm Podcasts"
  "/api/v1/episodes/{id}":
    get:
      summary: "Read one audio episode."
      responses:
        200:
          description: "Standard PlatPhorm response."
          content:
            "application/json":
              schema:
                "$ref": "#/components/schemas/SuccessResponse"
      operationId: "getApiV1EpisodesId"
      tags:
        - "PlatPhorm Podcasts"
  "/api/v1/episodes/{id}/playback-url":
    get:
      summary: "Resolve a public remote or saved media playback URL for an episode."
      responses:
        200:
          description: "Standard PlatPhorm response."
          content:
            "application/json":
              schema:
                "$ref": "#/components/schemas/SuccessResponse"
      operationId: "getApiV1EpisodesIdPlaybackUrl"
      tags:
        - "PlatPhorm Podcasts"
  "/api/v1/episodes/{id}/archive":
    post:
      summary: "Saved media archive of a public remote audio enclosure with runtime operator controls."
      security:
        - PlatformApiKey:
[]
        - PlatformBearer:
[]
      responses:
        200:
          description: "Standard PlatPhorm response."
          content:
            "application/json":
              schema:
                "$ref": "#/components/schemas/SuccessResponse"
      operationId: "postApiV1EpisodesIdArchive"
      tags:
        - "PlatPhorm Podcasts"
  "/api/v1/episodes/{id}/score-emoji":
    post:
      summary: "Emoji scoring adapter with runtime operator controls. No score is claimed without an upstream Emoji response."
      security:
        - PlatformApiKey:
[]
        - PlatformBearer:
[]
      responses:
        200:
          description: "Standard PlatPhorm response."
          content:
            "application/json":
              schema:
                "$ref": "#/components/schemas/SuccessResponse"
      operationId: "postApiV1EpisodesIdScoreEmoji"
      tags:
        - "PlatPhorm Podcasts"
  "/api/v1/playlists":
    get:
      summary: "List public or local-compatible playlist records when persistence exists."
      responses:
        200:
          description: "Standard PlatPhorm response."
          content:
            "application/json":
              schema:
                "$ref": "#/components/schemas/SuccessResponse"
      operationId: "getApiV1Playlists"
      tags:
        - "PlatPhorm Podcasts"
    post:
      summary: "Create a durable playlist record through the protected Cloudflare D1 application-record boundary."
      security:
        - PlatformApiKey:
[]
        - PlatformBearer:
[]
      responses:
        200:
          description: "Standard PlatPhorm response."
          content:
            "application/json":
              schema:
                "$ref": "#/components/schemas/SuccessResponse"
      operationId: "postApiV1Playlists"
      tags:
        - "PlatPhorm Podcasts"
  "/api/v1/playlists/{id}":
    get:
      summary: "Read one playlist record."
      responses:
        200:
          description: "Standard PlatPhorm response."
          content:
            "application/json":
              schema:
                "$ref": "#/components/schemas/SuccessResponse"
      operationId: "getApiV1PlaylistsId"
      tags:
        - "PlatPhorm Podcasts"
    put:
      summary: "Durable playlist persistence update with runtime operator controls."
      security:
        - PlatformApiKey:
[]
        - PlatformBearer:
[]
      responses:
        200:
          description: "Standard PlatPhorm response."
          content:
            "application/json":
              schema:
                "$ref": "#/components/schemas/SuccessResponse"
      operationId: "putApiV1PlaylistsId"
      tags:
        - "PlatPhorm Podcasts"
  "/api/v1/playlists/{id}/items":
    post:
      summary: "Compatibility route for adding an item through the canonical durable playlist persistence and discovery workflow."
      responses:
        200:
          description: "Standard PlatPhorm response."
          content:
            "application/json":
              schema:
                "$ref": "#/components/schemas/SuccessResponse"
      operationId: "postApiV1PlaylistsIdItems"
      tags:
        - "PlatPhorm Podcasts"
  "/api/v1/share":
    post:
      summary: "Create a public-safe share packet for an episode, clip, or playlist."
      responses:
        200:
          description: "Standard PlatPhorm response."
          content:
            "application/json":
              schema:
                "$ref": "#/components/schemas/SuccessResponse"
      operationId: "postApiV1Share"
      tags:
        - "PlatPhorm Podcasts"
  "/api/v1/shares/{id}":
    get:
      summary: "Read a packet share page payload when encoded in the share id."
      responses:
        200:
          description: "Standard PlatPhorm response."
          content:
            "application/json":
              schema:
                "$ref": "#/components/schemas/SuccessResponse"
      operationId: "getApiV1SharesId"
      tags:
        - "PlatPhorm Podcasts"
  "/api/v1/clip/dry-run":
    post:
      summary: "Create a local clip preview without saving an artifact."
      responses:
        200:
          description: "Standard PlatPhorm response."
          content:
            "application/json":
              schema:
                "$ref": "#/components/schemas/SuccessResponse"
      operationId: "postApiV1ClipDryRun"
      tags:
        - "PlatPhorm Podcasts"
  "/api/v1/clip":
    post:
      summary: "Saved clip generation with runtime operator controls and honest degraded state."
      security:
        - PlatformApiKey:
[]
        - PlatformBearer:
[]
      responses:
        200:
          description: "Standard PlatPhorm response."
          content:
            "application/json":
              schema:
                "$ref": "#/components/schemas/SuccessResponse"
      operationId: "postApiV1Clip"
      tags:
        - "PlatPhorm Podcasts"
  "/api/v1/clips":
    get:
      summary: "List saved clips when configured."
      responses:
        200:
          description: "Standard PlatPhorm response."
          content:
            "application/json":
              schema:
                "$ref": "#/components/schemas/SuccessResponse"
      operationId: "getApiV1Clips"
      tags:
        - "PlatPhorm Podcasts"
  "/api/v1/clips/{id}":
    get:
      summary: "Read one saved clip manifest."
      responses:
        200:
          description: "Standard PlatPhorm response."
          content:
            "application/json":
              schema:
                "$ref": "#/components/schemas/SuccessResponse"
      operationId: "getApiV1ClipsId"
      tags:
        - "PlatPhorm Podcasts"
  "/api/v1/search":
    get:
      summary: "Search feed sources, episodes, and entries from real archive state."
      responses:
        200:
          description: "Standard PlatPhorm response."
          content:
            "application/json":
              schema:
                "$ref": "#/components/schemas/SuccessResponse"
      operationId: "getApiV1Search"
      tags:
        - "PlatPhorm Podcasts"
  "/api/ai/chat":
    get:
      summary: "Describe the single universal grounded media prompt and its configured model provider."
      responses:
        200:
          description: "Standard PlatPhorm response."
          content:
            "application/json":
              schema:
                "$ref": "#/components/schemas/SuccessResponse"
      operationId: "getApiAiChat"
      tags:
        - "PlatPhorm Podcasts"
    post:
      summary: "Search real indexed/provider records or classify one public URL for resolution; optional response generation uses Vercel AI Gateway and never invents records."
      responses:
        200:
          description: "Standard PlatPhorm response."
          content:
            "application/json":
              schema:
                "$ref": "#/components/schemas/SuccessResponse"
      operationId: "postApiAiChat"
      tags:
        - "PlatPhorm Podcasts"
  "/api/ai/analyze":
    get:
      summary: "Describe the grounded entry-analysis provider architecture and durable persistence status."
      responses:
        200:
          description: "Standard PlatPhorm response."
          content:
            "application/json":
              schema:
                "$ref": "#/components/schemas/SuccessResponse"
      operationId: "getApiAiAnalyze"
      tags:
        - "PlatPhorm Podcasts"
    post:
      summary: "Publicly analyze one real archived entry with the shared Gateway-primary/Workers AI-fallback policy; raw durable writes remain server-protected."
      responses:
        200:
          description: "Standard PlatPhorm response."
          content:
            "application/json":
              schema:
                "$ref": "#/components/schemas/SuccessResponse"
      operationId: "postApiAiAnalyze"
      tags:
        - "PlatPhorm Podcasts"
  "/api/ai/recommend":
    get:
      summary: "Describe the grounded recommendation provider architecture and status."
      responses:
        200:
          description: "Standard PlatPhorm response."
          content:
            "application/json":
              schema:
                "$ref": "#/components/schemas/SuccessResponse"
      operationId: "getApiAiRecommend"
      tags:
        - "PlatPhorm Podcasts"
    post:
      summary: "Publicly recommend real indexed sources or return an unsaved playable playlist draft from publisher enclosures; persistence remains an explicit canonical playlist action."
      responses:
        200:
          description: "Standard PlatPhorm response."
          content:
            "application/json":
              schema:
                "$ref": "#/components/schemas/SuccessResponse"
      operationId: "postApiAiRecommend"
      tags:
        - "PlatPhorm Podcasts"
  "/api/v1/categories":
    get:
      summary: "List categories from real feed and entry state."
      responses:
        200:
          description: "Standard PlatPhorm response."
          content:
            "application/json":
              schema:
                "$ref": "#/components/schemas/SuccessResponse"
      operationId: "getApiV1Categories"
      tags:
        - "PlatPhorm Podcasts"
  "/api/v1/tags":
    get:
      summary: "List tags from real feed and entry state."
      responses:
        200:
          description: "Standard PlatPhorm response."
          content:
            "application/json":
              schema:
                "$ref": "#/components/schemas/SuccessResponse"
      operationId: "getApiV1Tags"
      tags:
        - "PlatPhorm Podcasts"
  "/api/v1/sources":
    get:
      summary: "List public L0-L3 content sources from the durable Cloudflare registry, with provenance and health metadata."
      responses:
        200:
          description: "Standard PlatPhorm response."
          content:
            "application/json":
              schema:
                "$ref": "#/components/schemas/SuccessResponse"
      operationId: "getApiV1Sources"
      tags:
        - "PlatPhorm Podcasts"
    post:
      summary: "Publicly submit one inspected content source to the durable registry; bulk and administrative insertion remain protected."
      responses:
        200:
          description: "Standard PlatPhorm response."
          content:
            "application/json":
              schema:
                "$ref": "#/components/schemas/SuccessResponse"
      operationId: "postApiV1Sources"
      tags:
        - "PlatPhorm Podcasts"
  "/api/v1/community/remediations/{id}":
    get:
      summary: "Read a public-safe remediation case or request the protected operator projection."
      description: "The default projection exposes lifecycle, bounded timeline, agent status, and pull request URL while redacting browser details and internal evidence. The operator view requires PLATPHORM_API_KEY."
      parameters:
        - name: "id"
          in: "path"
          required: true
          schema:
            type: "string"
            maxLength: 200
        - name: "view"
          in: "query"
          required: false
          schema:
            type: "string"
            enum:
              - "public"
              - "operator"
            default: "public"
      responses:
        200:
          description: "Standard PlatPhorm response."
          content:
            "application/json":
              schema:
                "$ref": "#/components/schemas/SuccessResponse"
      operationId: "getApiV1CommunityRemediationsId"
      tags:
        - "PlatPhorm Podcasts"
    post:
      summary: "Record a protected remediation transition or dispatch a bounded Jules pull-request session."
      description: "Operator-only actions can claim, record evidence, retry, dispatch Jules, approve an explicitly gated plan, or record independent verification. Jules can create a pull request but receives no merge, deployment, DNS, secret, or production mutation authority."
      security:
        - PlatformApiKey:
[]
        - PlatformBearer:
[]
      parameters:
        - name: "id"
          in: "path"
          required: true
          schema:
            type: "string"
            maxLength: 200
      responses:
        200:
          description: "Standard PlatPhorm response."
          content:
            "application/json":
              schema:
                "$ref": "#/components/schemas/SuccessResponse"
      operationId: "postApiV1CommunityRemediationsId"
      tags:
        - "PlatPhorm Podcasts"
  "/api/v1/discover":
    post:
      summary: "Inspect and normalize one public feed, playlist, stream, or publisher surface without durable persistence."
      responses:
        200:
          description: "Standard PlatPhorm response."
          content:
            "application/json":
              schema:
                "$ref": "#/components/schemas/SuccessResponse"
      operationId: "postApiV1Discover"
      tags:
        - "PlatPhorm Podcasts"
  "/api/v1/validate/feed":
    post:
      summary: "Public feed validation dry-run with parser evidence."
      responses:
        200:
          description: "Standard PlatPhorm response."
          content:
            "application/json":
              schema:
                "$ref": "#/components/schemas/SuccessResponse"
      operationId: "postApiV1ValidateFeed"
      tags:
        - "PlatPhorm Podcasts"
  "/api/v1/validate/xml":
    post:
      summary: "XML validation adapter with local preflight; no external validation is claimed without service evidence."
      responses:
        200:
          description: "Standard PlatPhorm response."
          content:
            "application/json":
              schema:
                "$ref": "#/components/schemas/SuccessResponse"
      operationId: "postApiV1ValidateXml"
      tags:
        - "PlatPhorm Podcasts"
  "/api/v1/validate/json":
    post:
      summary: "JSON validation adapter with local preflight; no external validation is claimed without service evidence."
      responses:
        200:
          description: "Standard PlatPhorm response."
          content:
            "application/json":
              schema:
                "$ref": "#/components/schemas/SuccessResponse"
      operationId: "postApiV1ValidateJson"
      tags:
        - "PlatPhorm Podcasts"
  "/api/v1/integrations/status":
    get:
      summary: "Public-safe integration status for XML, JSON, Emoji, OpenContent, API analytics, and media storage."
      responses:
        200:
          description: "Standard PlatPhorm response."
          content:
            "application/json":
              schema:
                "$ref": "#/components/schemas/SuccessResponse"
      operationId: "getApiV1IntegrationsStatus"
      tags:
        - "PlatPhorm Podcasts"
  "/api/v1/status":
    get:
      summary: "Podcast product and Web Status summary."
      responses:
        200:
          description: "Standard PlatPhorm response."
          content:
            "application/json":
              schema:
                "$ref": "#/components/schemas/SuccessResponse"
      operationId: "getApiV1Status"
      tags:
        - "PlatPhorm Podcasts"
  "/api/v1/opml/export":
    get:
      summary: "Export public feed sources as OPML."
      responses:
        200:
          description: "OPML XML."
      operationId: "getApiV1OpmlExport"
      tags:
        - "PlatPhorm Podcasts"
  "/api/v1/opml/import":
    post:
      summary: "Bulk OPML feed import for public feed indexing."
      security:
        - PlatformApiKey:
[]
        - PlatformBearer:
[]
      responses:
        200:
          description: "Standard PlatPhorm response."
          content:
            "application/json":
              schema:
                "$ref": "#/components/schemas/SuccessResponse"
      operationId: "postApiV1OpmlImport"
      tags:
        - "PlatPhorm Podcasts"
  "/api/web/status":
    get:
      summary: "Web Status payload using schema web.status.v1."
      description: "Projects cached Worker and workflow observations for Vercel, Cloudflare Worker, D1, KV, R2, Queues, Workflows, search, ranking, AI, locale/locality, relay, provider health, RSS, OpenAPI, MCP, and PWA. It does not probe providers during the request."
      x-platphorm:
        observationMode: "cached_backend_status"
        providerProbeMode: "no_request_fanout"
        output:
          systems:
            "$ref": "#/components/schemas/WebStatusSystems"
      responses:
        200:
          description: "Standard PlatPhorm response."
          content:
            "application/json":
              schema:
                "$ref": "#/components/schemas/SuccessResponse"
      operationId: "getApiWebStatus"
      tags:
        - "PlatPhorm Podcasts"
  "/api/web/manifest":
    get:
      summary: "Public Web manifest for Podcasts."
      responses:
        200:
          description: "Standard PlatPhorm response."
          content:
            "application/json":
              schema:
                "$ref": "#/components/schemas/SuccessResponse"
      operationId: "getApiWebManifest"
      tags:
        - "PlatPhorm Podcasts"
  "/api/web/scorecard":
    get:
      summary: "Public Web scorecard."
      responses:
        200:
          description: "Standard PlatPhorm response."
          content:
            "application/json":
              schema:
                "$ref": "#/components/schemas/SuccessResponse"
      operationId: "getApiWebScorecard"
      tags:
        - "PlatPhorm Podcasts"
  "/api/web/fingerprints":
    get:
      summary: "Public-safe fingerprints for routes, LLMS, OpenAPI, AsyncAPI, MCP, and policies."
      responses:
        200:
          description: "Standard PlatPhorm response."
          content:
            "application/json":
              schema:
                "$ref": "#/components/schemas/SuccessResponse"
      operationId: "getApiWebFingerprints"
      tags:
        - "PlatPhorm Podcasts"
  "/api/provenance/lookup":
    get:
      summary: "Public provenance lookup."
      responses:
        200:
          description: "Standard PlatPhorm response."
          content:
            "application/json":
              schema:
                "$ref": "#/components/schemas/SuccessResponse"
      operationId: "getApiProvenanceLookup"
      tags:
        - "PlatPhorm Podcasts"
  "/api/provenance/verify":
    get:
      summary: "Public provenance verification."
      responses:
        200:
          description: "Standard PlatPhorm response."
          content:
            "application/json":
              schema:
                "$ref": "#/components/schemas/SuccessResponse"
      operationId: "getApiProvenanceVerify"
      tags:
        - "PlatPhorm Podcasts"
  "/api/graph":
    get:
      summary: "Podcast graph nodes and edges."
      responses:
        200:
          description: "Standard PlatPhorm response."
          content:
            "application/json":
              schema:
                "$ref": "#/components/schemas/SuccessResponse"
      operationId: "getApiGraph"
      tags:
        - "PlatPhorm Podcasts"
  "/api/network/graph":
    get:
      summary: "Podcast graph exposed at network graph route."
      responses:
        200:
          description: "Standard PlatPhorm response."
          content:
            "application/json":
              schema:
                "$ref": "#/components/schemas/SuccessResponse"
      operationId: "getApiNetworkGraph"
      tags:
        - "PlatPhorm Podcasts"
  "/api/mcp":
    get:
      summary: "MCP metadata."
      x-platphorm:
        output:
          required:
            - "name"
            - "version"
            - "protocol"
            - "protocolVersion"
            - "supportedProtocolVersions"
            - "endpoint"
          properties:
            name:
{}
            version:
{}
            protocol:
{}
            protocolVersion:
{}
            supportedProtocolVersions:
{}
            endpoint:
{}
            publicMethods:
{}
            operatorToolCalls:
{}
            protection:
{}
            legacyCompatibility:
{}
      responses:
        200:
          description: "Standard PlatPhorm response."
          content:
            "application/json":
              schema:
                "$ref": "#/components/schemas/SuccessResponse"
      operationId: "getApiMcp"
      tags:
        - "PlatPhorm Podcasts"
    post:
      summary: "JSON-RPC 2.0 MCP endpoint."
      responses:
        200:
          description: "Standard PlatPhorm response."
          content:
            "application/json":
              schema:
                "$ref": "#/components/schemas/SuccessResponse"
      operationId: "postApiMcp"
      tags:
        - "PlatPhorm Podcasts"
  "/sitemap.xml":
    get:
      summary: "Local product sitemap."
      responses:
        200:
          description: "Standard PlatPhorm response."
          content:
            "application/json":
              schema:
                "$ref": "#/components/schemas/SuccessResponse"
      operationId: "getSitemapXml"
      tags:
        - "PlatPhorm Podcasts"
  "/sitemap-index.xml":
    get:
      summary: "Sitemap index for local, network, and full discovery."
      responses:
        200:
          description: "Standard PlatPhorm response."
          content:
            "application/json":
              schema:
                "$ref": "#/components/schemas/SuccessResponse"
      operationId: "getSitemapIndexXml"
      tags:
        - "PlatPhorm Podcasts"
  "/sitemap-network.xml":
    get:
      summary: "Bounded dual-source PlatPhorm network sitemap."
      responses:
        200:
          description: "Standard PlatPhorm response."
          content:
            "application/json":
              schema:
                "$ref": "#/components/schemas/SuccessResponse"
      operationId: "getSitemapNetworkXml"
      tags:
        - "PlatPhorm Podcasts"
  "/sitemap-full.xml":
    get:
      summary: "Combined podcast product and PlatPhorm network sitemap."
      responses:
        200:
          description: "Standard PlatPhorm response."
          content:
            "application/json":
              schema:
                "$ref": "#/components/schemas/SuccessResponse"
      operationId: "getSitemapFullXml"
      tags:
        - "PlatPhorm Podcasts"