{"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"]}}}}}}}}}