openapi: "3.1.0"
info:
  title: "PlatPhorm Podcasts API"
  version: "4.0.0"
  description: "Cross-Platform Podcast Playlist Builder. Paste any podcast link. Build a playlist. Listen here. Share with attribution. Public routes support URL resolution, dry-run validation, remote playback, local playlist/share packets, discovery files, and MCP. 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"
servers:
  - url: "https://podcasts.platphormnews.com"
    description: "Production"
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."
paths:
  "/api/health":
    get:
      summary: "Public service health."
      responses:
        200:
          description: "Standard PlatPhorm response."
          content:
            "application/json":
              schema:
                type: "object"
                properties:
                  ok:
                    type: "boolean"
                  data:
                    type: "object"
                  error:
                    type: "object"
                required:
                  - "ok"
  "/api/v1/health":
    get:
      summary: "Versioned public service health."
      responses:
        200:
          description: "Standard PlatPhorm response."
          content:
            "application/json":
              schema:
                type: "object"
                properties:
                  ok:
                    type: "boolean"
                  data:
                    type: "object"
                  error:
                    type: "object"
                required:
                  - "ok"
  "/api/v1/feeds":
    get:
      summary: "List public feed sources."
      responses:
        200:
          description: "Standard PlatPhorm response."
          content:
            "application/json":
              schema:
                type: "object"
                properties:
                  ok:
                    type: "boolean"
                  data:
                    type: "object"
                  error:
                    type: "object"
                required:
                  - "ok"
    post:
      summary: "Persistent feed ingestion with runtime operator controls."
      security:
        - PlatformApiKey:
[]
        - PlatformBearer:
[]
      responses:
        200:
          description: "Standard PlatPhorm response."
          content:
            "application/json":
              schema:
                type: "object"
                properties:
                  ok:
                    type: "boolean"
                  data:
                    type: "object"
                  error:
                    type: "object"
                required:
                  - "ok"
  "/api/v1/ingest":
    get:
      summary: "Describe public podcast indexing ingest."
      responses:
        200:
          description: "Standard PlatPhorm response."
          content:
            "application/json":
              schema:
                type: "object"
                properties:
                  ok:
                    type: "boolean"
                  data:
                    type: "object"
                  error:
                    type: "object"
                required:
                  - "ok"
    post:
      summary: "Persistent podcast/feed ingestion with runtime operator controls."
      security:
        - PlatformApiKey:
[]
        - PlatformBearer:
[]
      responses:
        200:
          description: "Standard PlatPhorm response."
          content:
            "application/json":
              schema:
                type: "object"
                properties:
                  ok:
                    type: "boolean"
                  data:
                    type: "object"
                  error:
                    type: "object"
                required:
                  - "ok"
  "/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:
                type: "object"
                properties:
                  ok:
                    type: "boolean"
                  data:
                    type: "object"
                  error:
                    type: "object"
                required:
                  - "ok"
  "/api/v1/resolve":
    get:
      summary: "Describe the URL resolver."
      responses:
        200:
          description: "Standard PlatPhorm response."
          content:
            "application/json":
              schema:
                type: "object"
                properties:
                  ok:
                    type: "boolean"
                  data:
                    type: "object"
                  error:
                    type: "object"
                required:
                  - "ok"
    post:
      summary: "Resolve RSS, Atom, JSON Feed, platform, episode, host, and direct audio URLs into playable or honestly degraded podcast records."
      responses:
        200:
          description: "Standard PlatPhorm response."
          content:
            "application/json":
              schema:
                type: "object"
                properties:
                  ok:
                    type: "boolean"
                  data:
                    type: "object"
                  error:
                    type: "object"
                required:
                  - "ok"
  "/api/v1/storage/status":
    get:
      summary: "Runtime storage mode and archive configuration status."
      responses:
        200:
          description: "Standard PlatPhorm response."
          content:
            "application/json":
              schema:
                type: "object"
                properties:
                  ok:
                    type: "boolean"
                  data:
                    type: "object"
                  error:
                    type: "object"
                required:
                  - "ok"
  "/api/v1/feeds/{id}":
    get:
      summary: "Get a feed source."
      responses:
        200:
          description: "Standard PlatPhorm response."
          content:
            "application/json":
              schema:
                type: "object"
                properties:
                  ok:
                    type: "boolean"
                  data:
                    type: "object"
                  error:
                    type: "object"
                required:
                  - "ok"
    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:
                type: "object"
                properties:
                  ok:
                    type: "boolean"
                  data:
                    type: "object"
                  error:
                    type: "object"
                required:
                  - "ok"
    delete:
      summary: "Non-destructive archive request with runtime operator controls."
      security:
        - PlatformApiKey:
[]
        - PlatformBearer:
[]
      responses:
        200:
          description: "Standard PlatPhorm response."
          content:
            "application/json":
              schema:
                type: "object"
                properties:
                  ok:
                    type: "boolean"
                  data:
                    type: "object"
                  error:
                    type: "object"
                required:
                  - "ok"
  "/api/v1/feeds/{id}/sync":
    post:
      summary: "Public resync of an indexed public feed source."
      responses:
        200:
          description: "Standard PlatPhorm response."
          content:
            "application/json":
              schema:
                type: "object"
                properties:
                  ok:
                    type: "boolean"
                  data:
                    type: "object"
                  error:
                    type: "object"
                required:
                  - "ok"
  "/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:
                type: "object"
                properties:
                  ok:
                    type: "boolean"
                  data:
                    type: "object"
                  error:
                    type: "object"
                required:
                  - "ok"
  "/api/v1/feeds/{id}/entries":
    get:
      summary: "List entries for one feed."
      responses:
        200:
          description: "Standard PlatPhorm response."
          content:
            "application/json":
              schema:
                type: "object"
                properties:
                  ok:
                    type: "boolean"
                  data:
                    type: "object"
                  error:
                    type: "object"
                required:
                  - "ok"
  "/api/v1/feeds/{id}/status":
    get:
      summary: "Get feed sync and archive status."
      responses:
        200:
          description: "Standard PlatPhorm response."
          content:
            "application/json":
              schema:
                type: "object"
                properties:
                  ok:
                    type: "boolean"
                  data:
                    type: "object"
                  error:
                    type: "object"
                required:
                  - "ok"
  "/api/v1/entries":
    get:
      summary: "List archived entries."
      responses:
        200:
          description: "Standard PlatPhorm response."
          content:
            "application/json":
              schema:
                type: "object"
                properties:
                  ok:
                    type: "boolean"
                  data:
                    type: "object"
                  error:
                    type: "object"
                required:
                  - "ok"
  "/api/v1/entries/search":
    get:
      summary: "Search archived entries."
      responses:
        200:
          description: "Standard PlatPhorm response."
          content:
            "application/json":
              schema:
                type: "object"
                properties:
                  ok:
                    type: "boolean"
                  data:
                    type: "object"
                  error:
                    type: "object"
                required:
                  - "ok"
  "/api/v1/entries/recent":
    get:
      summary: "List recent archived entries."
      responses:
        200:
          description: "Standard PlatPhorm response."
          content:
            "application/json":
              schema:
                type: "object"
                properties:
                  ok:
                    type: "boolean"
                  data:
                    type: "object"
                  error:
                    type: "object"
                required:
                  - "ok"
  "/api/v1/entries/archive":
    get:
      summary: "List archive entries and policy."
      responses:
        200:
          description: "Standard PlatPhorm response."
          content:
            "application/json":
              schema:
                type: "object"
                properties:
                  ok:
                    type: "boolean"
                  data:
                    type: "object"
                  error:
                    type: "object"
                required:
                  - "ok"
  "/api/v1/entries/{id}":
    get:
      summary: "Read one archived entry."
      responses:
        200:
          description: "Standard PlatPhorm response."
          content:
            "application/json":
              schema:
                type: "object"
                properties:
                  ok:
                    type: "boolean"
                  data:
                    type: "object"
                  error:
                    type: "object"
                required:
                  - "ok"
  "/api/v1/shows":
    get:
      summary: "List podcast shows/feed sources."
      responses:
        200:
          description: "Standard PlatPhorm response."
          content:
            "application/json":
              schema:
                type: "object"
                properties:
                  ok:
                    type: "boolean"
                  data:
                    type: "object"
                  error:
                    type: "object"
                required:
                  - "ok"
  "/api/v1/shows/{id}":
    get:
      summary: "Read one show."
      responses:
        200:
          description: "Standard PlatPhorm response."
          content:
            "application/json":
              schema:
                type: "object"
                properties:
                  ok:
                    type: "boolean"
                  data:
                    type: "object"
                  error:
                    type: "object"
                required:
                  - "ok"
  "/api/v1/shows/{id}/episodes":
    get:
      summary: "List show episodes."
      responses:
        200:
          description: "Standard PlatPhorm response."
          content:
            "application/json":
              schema:
                type: "object"
                properties:
                  ok:
                    type: "boolean"
                  data:
                    type: "object"
                  error:
                    type: "object"
                required:
                  - "ok"
  "/api/v1/episodes":
    get:
      summary: "List audio episodes."
      responses:
        200:
          description: "Standard PlatPhorm response."
          content:
            "application/json":
              schema:
                type: "object"
                properties:
                  ok:
                    type: "boolean"
                  data:
                    type: "object"
                  error:
                    type: "object"
                required:
                  - "ok"
  "/api/v1/episodes/{id}":
    get:
      summary: "Read one audio episode."
      responses:
        200:
          description: "Standard PlatPhorm response."
          content:
            "application/json":
              schema:
                type: "object"
                properties:
                  ok:
                    type: "boolean"
                  data:
                    type: "object"
                  error:
                    type: "object"
                required:
                  - "ok"
  "/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:
                type: "object"
                properties:
                  ok:
                    type: "boolean"
                  data:
                    type: "object"
                  error:
                    type: "object"
                required:
                  - "ok"
  "/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:
                type: "object"
                properties:
                  ok:
                    type: "boolean"
                  data:
                    type: "object"
                  error:
                    type: "object"
                required:
                  - "ok"
  "/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:
                type: "object"
                properties:
                  ok:
                    type: "boolean"
                  data:
                    type: "object"
                  error:
                    type: "object"
                required:
                  - "ok"
  "/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:
                type: "object"
                properties:
                  ok:
                    type: "boolean"
                  data:
                    type: "object"
                  error:
                    type: "object"
                required:
                  - "ok"
    post:
      summary: "Create an ephemeral playlist record; durable server persistence reports its runtime state."
      responses:
        200:
          description: "Standard PlatPhorm response."
          content:
            "application/json":
              schema:
                type: "object"
                properties:
                  ok:
                    type: "boolean"
                  data:
                    type: "object"
                  error:
                    type: "object"
                required:
                  - "ok"
  "/api/v1/playlists/{id}":
    get:
      summary: "Read one playlist record."
      responses:
        200:
          description: "Standard PlatPhorm response."
          content:
            "application/json":
              schema:
                type: "object"
                properties:
                  ok:
                    type: "boolean"
                  data:
                    type: "object"
                  error:
                    type: "object"
                required:
                  - "ok"
    put:
      summary: "Durable playlist persistence update with runtime operator controls."
      security:
        - PlatformApiKey:
[]
        - PlatformBearer:
[]
      responses:
        200:
          description: "Standard PlatPhorm response."
          content:
            "application/json":
              schema:
                type: "object"
                properties:
                  ok:
                    type: "boolean"
                  data:
                    type: "object"
                  error:
                    type: "object"
                required:
                  - "ok"
  "/api/v1/playlists/{id}/items":
    post:
      summary: "Add an item to an ephemeral playlist record."
      responses:
        200:
          description: "Standard PlatPhorm response."
          content:
            "application/json":
              schema:
                type: "object"
                properties:
                  ok:
                    type: "boolean"
                  data:
                    type: "object"
                  error:
                    type: "object"
                required:
                  - "ok"
  "/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:
                type: "object"
                properties:
                  ok:
                    type: "boolean"
                  data:
                    type: "object"
                  error:
                    type: "object"
                required:
                  - "ok"
  "/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:
                type: "object"
                properties:
                  ok:
                    type: "boolean"
                  data:
                    type: "object"
                  error:
                    type: "object"
                required:
                  - "ok"
  "/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:
                type: "object"
                properties:
                  ok:
                    type: "boolean"
                  data:
                    type: "object"
                  error:
                    type: "object"
                required:
                  - "ok"
  "/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:
                type: "object"
                properties:
                  ok:
                    type: "boolean"
                  data:
                    type: "object"
                  error:
                    type: "object"
                required:
                  - "ok"
  "/api/v1/clips":
    get:
      summary: "List saved clips when configured."
      responses:
        200:
          description: "Standard PlatPhorm response."
          content:
            "application/json":
              schema:
                type: "object"
                properties:
                  ok:
                    type: "boolean"
                  data:
                    type: "object"
                  error:
                    type: "object"
                required:
                  - "ok"
  "/api/v1/clips/{id}":
    get:
      summary: "Read one saved clip manifest."
      responses:
        200:
          description: "Standard PlatPhorm response."
          content:
            "application/json":
              schema:
                type: "object"
                properties:
                  ok:
                    type: "boolean"
                  data:
                    type: "object"
                  error:
                    type: "object"
                required:
                  - "ok"
  "/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:
                type: "object"
                properties:
                  ok:
                    type: "boolean"
                  data:
                    type: "object"
                  error:
                    type: "object"
                required:
                  - "ok"
  "/api/v1/categories":
    get:
      summary: "List categories from real feed and entry state."
      responses:
        200:
          description: "Standard PlatPhorm response."
          content:
            "application/json":
              schema:
                type: "object"
                properties:
                  ok:
                    type: "boolean"
                  data:
                    type: "object"
                  error:
                    type: "object"
                required:
                  - "ok"
  "/api/v1/tags":
    get:
      summary: "List tags from real feed and entry state."
      responses:
        200:
          description: "Standard PlatPhorm response."
          content:
            "application/json":
              schema:
                type: "object"
                properties:
                  ok:
                    type: "boolean"
                  data:
                    type: "object"
                  error:
                    type: "object"
                required:
                  - "ok"
  "/api/v1/sources":
    get:
      summary: "List feed sources."
      responses:
        200:
          description: "Standard PlatPhorm response."
          content:
            "application/json":
              schema:
                type: "object"
                properties:
                  ok:
                    type: "boolean"
                  data:
                    type: "object"
                  error:
                    type: "object"
                required:
                  - "ok"
  "/api/v1/validate/feed":
    post:
      summary: "Public feed validation dry-run with parser evidence."
      responses:
        200:
          description: "Standard PlatPhorm response."
          content:
            "application/json":
              schema:
                type: "object"
                properties:
                  ok:
                    type: "boolean"
                  data:
                    type: "object"
                  error:
                    type: "object"
                required:
                  - "ok"
  "/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:
                type: "object"
                properties:
                  ok:
                    type: "boolean"
                  data:
                    type: "object"
                  error:
                    type: "object"
                required:
                  - "ok"
  "/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:
                type: "object"
                properties:
                  ok:
                    type: "boolean"
                  data:
                    type: "object"
                  error:
                    type: "object"
                required:
                  - "ok"
  "/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:
                type: "object"
                properties:
                  ok:
                    type: "boolean"
                  data:
                    type: "object"
                  error:
                    type: "object"
                required:
                  - "ok"
  "/api/v1/status":
    get:
      summary: "Podcast product and Web Status summary."
      responses:
        200:
          description: "Standard PlatPhorm response."
          content:
            "application/json":
              schema:
                type: "object"
                properties:
                  ok:
                    type: "boolean"
                  data:
                    type: "object"
                  error:
                    type: "object"
                required:
                  - "ok"
  "/api/v1/opml/export":
    get:
      summary: "Export public feed sources as OPML."
      responses:
        200:
          description: "OPML XML."
  "/api/v1/opml/import":
    post:
      summary: "Public OPML import for public feed indexing."
      responses:
        200:
          description: "Standard PlatPhorm response."
          content:
            "application/json":
              schema:
                type: "object"
                properties:
                  ok:
                    type: "boolean"
                  data:
                    type: "object"
                  error:
                    type: "object"
                required:
                  - "ok"
  "/api/web/status":
    get:
      summary: "Web Status payload using schema web.status.v1."
      responses:
        200:
          description: "Standard PlatPhorm response."
          content:
            "application/json":
              schema:
                type: "object"
                properties:
                  ok:
                    type: "boolean"
                  data:
                    type: "object"
                  error:
                    type: "object"
                required:
                  - "ok"
  "/api/web/manifest":
    get:
      summary: "Public Web manifest for Podcasts."
      responses:
        200:
          description: "Standard PlatPhorm response."
          content:
            "application/json":
              schema:
                type: "object"
                properties:
                  ok:
                    type: "boolean"
                  data:
                    type: "object"
                  error:
                    type: "object"
                required:
                  - "ok"
  "/api/web/scorecard":
    get:
      summary: "Public Web scorecard."
      responses:
        200:
          description: "Standard PlatPhorm response."
          content:
            "application/json":
              schema:
                type: "object"
                properties:
                  ok:
                    type: "boolean"
                  data:
                    type: "object"
                  error:
                    type: "object"
                required:
                  - "ok"
  "/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:
                type: "object"
                properties:
                  ok:
                    type: "boolean"
                  data:
                    type: "object"
                  error:
                    type: "object"
                required:
                  - "ok"
  "/api/provenance/lookup":
    get:
      summary: "Public provenance lookup."
      responses:
        200:
          description: "Standard PlatPhorm response."
          content:
            "application/json":
              schema:
                type: "object"
                properties:
                  ok:
                    type: "boolean"
                  data:
                    type: "object"
                  error:
                    type: "object"
                required:
                  - "ok"
  "/api/provenance/verify":
    get:
      summary: "Public provenance verification."
      responses:
        200:
          description: "Standard PlatPhorm response."
          content:
            "application/json":
              schema:
                type: "object"
                properties:
                  ok:
                    type: "boolean"
                  data:
                    type: "object"
                  error:
                    type: "object"
                required:
                  - "ok"
  "/api/graph":
    get:
      summary: "Podcast graph nodes and edges."
      responses:
        200:
          description: "Standard PlatPhorm response."
          content:
            "application/json":
              schema:
                type: "object"
                properties:
                  ok:
                    type: "boolean"
                  data:
                    type: "object"
                  error:
                    type: "object"
                required:
                  - "ok"
  "/api/network/graph":
    get:
      summary: "Podcast graph exposed at network graph route."
      responses:
        200:
          description: "Standard PlatPhorm response."
          content:
            "application/json":
              schema:
                type: "object"
                properties:
                  ok:
                    type: "boolean"
                  data:
                    type: "object"
                  error:
                    type: "object"
                required:
                  - "ok"
  "/api/mcp":
    get:
      summary: "MCP metadata."
      responses:
        200:
          description: "Standard PlatPhorm response."
          content:
            "application/json":
              schema:
                type: "object"
                properties:
                  ok:
                    type: "boolean"
                  data:
                    type: "object"
                  error:
                    type: "object"
                required:
                  - "ok"
    post:
      summary: "JSON-RPC 2.0 MCP endpoint."
      responses:
        200:
          description: "Standard PlatPhorm response."
          content:
            "application/json":
              schema:
                type: "object"
                properties:
                  ok:
                    type: "boolean"
                  data:
                    type: "object"
                  error:
                    type: "object"
                required:
                  - "ok"