{"openapi":"3.1.0","info":{"title":"PlatPhorm News API","version":"0.0.4","description":"The official PlatPhorm News REST API. Provides access to top stories, latest news, HackerNews aggregation, RSS, sitemap, webhooks, and MCP endpoints.","contact":{"name":"Michael Barbine","email":"Michael@Barbineworldwide.com","url":"https://www.platphormnews.com"},"license":{"name":"MIT"},"x-logo":{"url":"https://platphormnews.com/favicon.png"}},"servers":[{"url":"https://www.platphormnews.com","description":"Production"},{"url":"https://api.platphormnews.com","description":"API subdomain"},{"url":"http://localhost:5173","description":"Local dev"}],"tags":[{"name":"News","description":"News aggregation endpoints"},{"name":"HackerNews","description":"HackerNews-specific story feeds"},{"name":"Games","description":"PlatPhorm Games — server, leaderboard, and match data"},{"name":"Platform","description":"Cross-platform PlatPhorm network stats"},{"name":"Network","description":"PlatPhorm network graph and domain discovery"},{"name":"Meta","description":"Site metadata: RSS, sitemap, health"},{"name":"Webhooks","description":"Webhook integrations (Zapier, n8n)"},{"name":"MCP","description":"Model Context Protocol endpoints"},{"name":"Sports","description":"Live sports news and stats from sports.platphormnews.com"},{"name":"Emoji","description":"Emoji library and search from emoji.platphormnews.com"},{"name":"Calendar","description":"Events and scheduling from calendar.platphormnews.com"},{"name":"ASCII","description":"ASCII art and text generation from ascii.platphormnews.com"},{"name":"Fashion","description":"Fashion news and trends from fashion.platphormnews.com"},{"name":"Comms","description":"Communications from starphone.platphormnews.com"},{"name":"Jobs","description":"Job listings from jobs.platphormnews.com"},{"name":"Gaming","description":"GTA and gaming content from gta.platphormnews.com"},{"name":"AI","description":"AI services: NPaaS, Airrow, MCP"},{"name":"Infra","description":"Infrastructure services: Reflux, Calendar"}],"paths":{"/api/v1/network/graph":{"get":{"tags":["Network","MCP"],"summary":"PlatPhorm network graph","description":"Returns the full PlatPhorm network as a graph of nodes (domains, services, API endpoints) and edges. Supports filtering, stats-only mode, and D3.js-compatible output.","parameters":[{"name":"filter","in":"query","schema":{"type":"string","enum":["root","subdomain","partner","external","service","api"]},"description":"Filter nodes by type"},{"name":"include","in":"query","schema":{"type":"string"},"description":"Comma-separated node types to include (e.g. service,api). Overrides filter."},{"name":"category","in":"query","schema":{"type":"string"},"description":"Filter nodes by category (gaming, infra, service, mcp, etc.)"},{"name":"stats","in":"query","schema":{"type":"boolean"},"description":"Return only stats summary (no nodes/edges/endpoints)"},{"name":"format","in":"query","schema":{"type":"string","enum":["d3"]},"description":"Output format. Use d3 for D3.js-compatible links[] with index refs."}],"responses":{"200":{"description":"Network graph with nodes, edges, endpoints, and stats","content":{"application/json":{"schema":{"type":"object","properties":{"version":{"type":"string"},"generated":{"type":"string","format":"date-time"},"rootDomain":{"type":"string"},"stats":{"$ref":"#/components/schemas/GraphStats"},"nodes":{"type":"array","items":{"$ref":"#/components/schemas/GraphNode"}},"edges":{"type":"array","items":{"$ref":"#/components/schemas/GraphEdge"}},"endpoints":{"type":"array","items":{"$ref":"#/components/schemas/ApiEndpoint"}}}}}}},"500":{"$ref":"#/components/responses/Error500"}}}},"/api/domains":{"get":{"tags":["Network"],"summary":"Discover PlatPhorm domains","description":"Returns all *.platphormnews.com domains from Vercel API or manifest fallback.","parameters":[{"name":"format","in":"query","schema":{"type":"string","enum":["nodes","raw"],"default":"nodes"},"description":"Response format: nodes (NetworkNode[]) or raw (VercelDomain[])"}],"responses":{"200":{"description":"Domain list","content":{"application/json":{}}}}}},"/api/news":{"get":{"tags":["News"],"summary":"Consolidated news endpoint","description":"Unified news data: homepage aggregation (latest), News API + HN combined feed (combined), or top HN story IDs (top).","parameters":[{"name":"source","in":"query","schema":{"type":"string","enum":["latest","combined","top"],"default":"latest"},"description":"Data source mode"},{"name":"limit","in":"query","schema":{"type":"integer","default":20},"description":"Max items to return"}],"responses":{"200":{"description":"News data (shape varies by source)","content":{"application/json":{"schema":{"type":"object","properties":{"newsItem":{"$ref":"#/components/schemas/NewsItem"},"newsItems":{"$ref":"#/components/schemas/NewsItemArray"},"quakeStats":{"$ref":"#/components/schemas/GameStats"},"platformStats":{"$ref":"#/components/schemas/PlatformStats"}}}}}},"400":{"description":"Invalid source parameter"},"500":{"$ref":"#/components/responses/Error500"}}}},"/api/hackernews":{"get":{"tags":["HackerNews"],"summary":"Consolidated HackerNews endpoint","description":"Unified HN data: story lists by category (top, best, ask, show, job) or full story details with comments.","parameters":[{"name":"type","in":"query","schema":{"type":"string","enum":["top","best","ask","show","job","details"],"default":"top"},"description":"Story category or \"details\" for single story"},{"name":"id","in":"query","schema":{"type":"integer"},"description":"HN item ID (required when type=details)"},{"name":"limit","in":"query","schema":{"type":"integer","default":20},"description":"Max items to return (list mode)"}],"responses":{"200":{"description":"Story list or detail with comments","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NewsItemArray"}}}},"400":{"description":"Invalid type or missing id"},"404":{"$ref":"#/components/responses/NotFound"},"500":{"$ref":"#/components/responses/Error500"}}}},"/api/games":{"get":{"tags":["Games"],"summary":"PlatPhorm Games data proxy","description":"Proxy to games.platphormnews.com — returns catalog, servers, leaderboard, stats, or matches.","parameters":[{"name":"type","in":"query","required":true,"schema":{"type":"string","enum":["catalog","servers","leaderboard","stats","matches"]}},{"name":"game","in":"query","schema":{"type":"string"},"description":"Filter by game ID (optional)"},{"name":"mode","in":"query","schema":{"type":"string"},"description":"Filter servers by game mode (servers type only)"},{"name":"sort","in":"query","schema":{"type":"string","enum":["score","deaths","kd","wins"]},"description":"Sort leaderboard (leaderboard type only)"}],"responses":{"200":{"description":"Games data","content":{"application/json":{}}},"400":{"description":"Missing or invalid type parameter"}}}},"/api/platform":{"get":{"tags":["Platform"],"summary":"Platform stats proxy","description":"Proxy to mcp.platphormnews.com — returns cross-platform stats, sites, deployments, articles, analytics, or MCP server list.","parameters":[{"name":"type","in":"query","schema":{"type":"string","enum":["stats","sites","deployments","articles","analytics","mcp_servers"],"default":"stats"}}],"responses":{"200":{"description":"Platform data","content":{"application/json":{}}}}}},"/rss.xml":{"get":{"tags":["Meta"],"summary":"RSS 2.0 feed","description":"Full RSS 2.0 feed of the latest PlatPhorm News stories.","responses":{"200":{"description":"RSS XML feed","content":{"application/rss+xml":{}}}}}},"/sitemap.xml":{"get":{"tags":["Meta"],"summary":"XML sitemap","responses":{"200":{"description":"XML sitemap","content":{"application/xml":{}}}}}},"/api/faq":{"get":{"tags":["Meta"],"summary":"Frequently Asked Questions","description":"Get frequently asked questions about PlatPhorm News and the PlatPhorm network.","responses":{"200":{"description":"List of FAQs","content":{"application/json":{}}}}}},"/api/health":{"get":{"tags":["Meta"],"summary":"Health check","responses":{"200":{"description":"Service healthy","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string"},"timestamp":{"type":"string"}}}}}}}}},"/api/webhooks":{"post":{"tags":["Webhooks"],"summary":"Inbound webhook receiver","description":"Receives webhook payloads from Zapier, n8n, or any HTTP POST source.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"event":{"type":"string","description":"Event name, e.g. story.created"},"payload":{"type":"object"},"source":{"type":"string","description":"Origin system (zapier, n8n, custom)"}}}}}},"responses":{"200":{"description":"Webhook accepted"},"400":{"description":"Bad request"}}}},"/api/sports":{"get":{"tags":["Sports"],"summary":"PlatPhorm Sports data proxy","description":"Proxy to sports.platphormnews.com — live scores, news, and stats.","parameters":[{"name":"type","in":"query","schema":{"type":"string","enum":["news","scores","stats"],"default":"news"},"description":"Data type to retrieve"},{"name":"limit","in":"query","schema":{"type":"integer","default":10}}],"responses":{"200":{"description":"Sports data","content":{"application/json":{}}}}}},"/api/emoji":{"get":{"tags":["Emoji"],"summary":"PlatPhorm Emoji data proxy","description":"Proxy to emoji.platphormnews.com — emoji search and lookup.","parameters":[{"name":"q","in":"query","schema":{"type":"string"},"description":"Search query"},{"name":"category","in":"query","schema":{"type":"string"},"description":"Emoji category filter"}],"responses":{"200":{"description":"Emoji results","content":{"application/json":{}}}}}},"/api/calendar":{"get":{"tags":["Calendar"],"summary":"PlatPhorm Calendar proxy","description":"Proxy to calendar.platphormnews.com — events and scheduling.","parameters":[{"name":"type","in":"query","schema":{"type":"string","enum":["events","upcoming","all"],"default":"events"}},{"name":"limit","in":"query","schema":{"type":"integer","default":10}},{"name":"from","in":"query","schema":{"type":"string","format":"date"},"description":"Start date filter (ISO 8601)"}],"responses":{"200":{"description":"Calendar events","content":{"application/json":{}}}}}},"/api/altnews":{"get":{"tags":["News"],"summary":"PlatPhorm AltNews proxy","description":"Proxy to altnews.platphormnews.com — alternative and independent news.","parameters":[{"name":"type","in":"query","schema":{"type":"string","enum":["stories","trending","latest"],"default":"stories"}},{"name":"limit","in":"query","schema":{"type":"integer","default":10}},{"name":"category","in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"News stories","content":{"application/json":{}}}}}},"/api/ascii":{"get":{"tags":["ASCII"],"summary":"PlatPhorm ASCII art proxy","description":"Proxy to ascii.platphormnews.com — ASCII art generation and text art.","parameters":[{"name":"type","in":"query","schema":{"type":"string","enum":["generate","gallery","fonts"],"default":"generate"}},{"name":"text","in":"query","schema":{"type":"string"},"description":"Text to convert to ASCII art"},{"name":"font","in":"query","schema":{"type":"string"},"description":"ASCII font/style name"}],"responses":{"200":{"description":"ASCII art result","content":{"application/json":{}}}}}},"/api/fashion":{"get":{"tags":["Fashion"],"summary":"PlatPhorm Fashion proxy","description":"Proxy to fashion.platphormnews.com — fashion news and trends.","parameters":[{"name":"type","in":"query","schema":{"type":"string","enum":["news","trends","collections"],"default":"news"}},{"name":"limit","in":"query","schema":{"type":"integer","default":10}}],"responses":{"200":{"description":"Fashion content","content":{"application/json":{}}}}}},"/api/starphone":{"get":{"tags":["Comms"],"summary":"PlatPhorm StarPhone proxy","description":"Proxy to starphone.platphormnews.com — communications platform.","parameters":[{"name":"type","in":"query","schema":{"type":"string","enum":["status","features","stats"],"default":"status"}}],"responses":{"200":{"description":"StarPhone data","content":{"application/json":{}}}}}},"/api/jobs":{"get":{"tags":["Jobs"],"summary":"PlatPhorm Jobs proxy","description":"Proxy to jobs.platphormnews.com — job listings and career board.","parameters":[{"name":"type","in":"query","schema":{"type":"string","enum":["listings","featured","latest"],"default":"listings"}},{"name":"q","in":"query","schema":{"type":"string"},"description":"Job title or keyword search"},{"name":"limit","in":"query","schema":{"type":"integer","default":20}},{"name":"page","in":"query","schema":{"type":"integer","default":1}}],"responses":{"200":{"description":"Job listings","content":{"application/json":{}}},"400":{"description":"Bad request"}}}},"/api/gta":{"get":{"tags":["Gaming"],"summary":"PlatPhorm GTA proxy","description":"Proxy to gta.platphormnews.com — GTA news, stats, and community.","parameters":[{"name":"type","in":"query","schema":{"type":"string","enum":["news","stats","community"],"default":"news"}},{"name":"limit","in":"query","schema":{"type":"integer","default":10}}],"responses":{"200":{"description":"GTA data","content":{"application/json":{}}}}}},"/api/npaas":{"get":{"tags":["AI"],"summary":"PlatPhorm NPaaS proxy","description":"Proxy to npaas.platphormnews.com — News Platform as a Service.","parameters":[{"name":"type","in":"query","schema":{"type":"string","enum":["status","stats","pipelines"],"default":"status"}}],"responses":{"200":{"description":"NPaaS data","content":{"application/json":{}}}}}},"/api/airrow":{"get":{"tags":["AI"],"summary":"PlatPhorm Airrow proxy","description":"Proxy to airrow.platphormnews.com — AI recommendation engine.","parameters":[{"name":"type","in":"query","schema":{"type":"string","enum":["recommendations","routes","stats"],"default":"recommendations"}},{"name":"context","in":"query","schema":{"type":"string"},"description":"Context string for recommendations"}],"responses":{"200":{"description":"Airrow data","content":{"application/json":{}}}}}},"/api/reflux":{"get":{"tags":["Infra"],"summary":"PlatPhorm Reflux proxy","description":"Proxy to reflux.platphormnews.com — data pipeline and stream processing.","parameters":[{"name":"type","in":"query","schema":{"type":"string","enum":["status","streams","metrics"],"default":"status"}}],"responses":{"200":{"description":"Reflux data","content":{"application/json":{}}}}}},"/api/mcp":{"get":{"tags":["MCP"],"summary":"MCP manifest","description":"Returns the Model Context Protocol tool manifest for AI agents.","responses":{"200":{"description":"MCP manifest JSON","content":{"application/json":{}}}}},"post":{"tags":["MCP"],"summary":"MCP tool call","description":"Execute a named MCP tool (list_stories, get_story, search).","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["tool","params"],"properties":{"tool":{"type":"string","enum":["list_stories","get_story","search_stories","list_domains","get_domain","get_network_info","get_games_catalog","get_games_servers","get_games_leaderboard","get_games_stats","get_games_matches","get_platform_stats","get_monitor_status","get_sports_news","get_emoji_data","get_calendar_events","get_altnews_stories","get_ascii_art","get_fashion_content","get_starphone_data","get_jobs_listings","get_gta_stats","get_npaas_status","get_airrow_data","get_reflux_data","get_faq"]},"params":{"type":"object"}}}}}},"responses":{"200":{"description":"Tool result"},"400":{"description":"Unknown tool or bad params"}}}},"/api/mcp/client":{"get":{"tags":["MCP"],"summary":"MCP client status","description":"Returns the MCP client connection status, discovered tools, registration state, and manifest summary. The client connects to mcp.platphormnews.com and docs.platphormnews.com.","responses":{"200":{"description":"Client status and registration","content":{"application/json":{}}}}},"post":{"tags":["MCP"],"summary":"Invoke tool via MCP client","description":"Invoke an MCP tool through the client proxy. Supports both standard and JSON-RPC 2.0 formats.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["tool"],"properties":{"tool":{"type":"string","description":"Tool name to invoke"},"params":{"type":"object","description":"Tool parameters"},"format":{"type":"string","enum":["standard","jsonrpc"],"description":"Request format (default: standard)"}}}}}},"responses":{"200":{"description":"Tool result"},"400":{"description":"Bad request"},"502":{"description":"Upstream MCP server error"},"503":{"description":"MCP client not connected"}}}}},"components":{"schemas":{"NewsItem":{"type":"object","properties":{"id":{"type":"integer"},"title":{"type":"string"},"url":{"type":"string","format":"uri"},"score":{"type":"integer"},"time":{"type":"integer","description":"Unix timestamp"},"by":{"type":"string","description":"Author username"},"descendants":{"type":"integer","description":"Comment count"},"type":{"type":"string","enum":["story","ask","job","show"]}}},"NewsItemArray":{"type":"array","items":{"$ref":"#/components/schemas/NewsItem"}},"GameStats":{"type":"object","properties":{"servers":{"type":"integer"},"players":{"type":"integer"},"matches":{"type":"integer"},"topPlayers":{"type":"array","items":{"$ref":"#/components/schemas/LeaderboardEntry"}},"recentMatches":{"type":"array","items":{"$ref":"#/components/schemas/GameMatch"}}}},"LeaderboardEntry":{"type":"object","properties":{"name":{"type":"string"},"frags":{"type":"integer"},"deaths":{"type":"integer"},"kd":{"type":"number"},"wins":{"type":"integer"}}},"GameMatch":{"type":"object","properties":{"map":{"type":"string"},"mode":{"type":"string"},"players":{"type":"integer"},"duration":{"type":"string"}}},"GameServer":{"type":"object","properties":{"name":{"type":"string"},"map":{"type":"string"},"mode":{"type":"string"},"players":{"type":"integer"},"maxPlayers":{"type":"integer"},"region":{"type":"string"}}},"PlatformStats":{"type":"object","properties":{"sites":{"type":"integer"},"tools":{"type":"integer"},"articles":{"type":"integer"},"mcpVersion":{"type":"string"}}},"GraphNode":{"type":"object","properties":{"id":{"type":"string"},"url":{"type":"string","format":"uri"},"label":{"type":"string"},"type":{"type":"string","enum":["root","subdomain","partner","external","service","api"]},"source":{"type":"string","enum":["vercel","dynamodb","manifest","config"]},"status":{"type":"string"},"category":{"type":"string"},"description":{"type":"string"},"metadata":{"type":"object"}}},"GraphEdge":{"type":"object","properties":{"source":{"type":"string"},"target":{"type":"string"},"relationship":{"type":"string","enum":["parent-child","sibling","cross-link","feed","api"]},"weight":{"type":"number"}}},"GraphStats":{"type":"object","properties":{"totalNodes":{"type":"integer"},"totalEdges":{"type":"integer"},"bySource":{"type":"object"},"byType":{"type":"object"},"filteredNodes":{"type":"integer"},"filteredEdges":{"type":"integer"}}},"ApiEndpoint":{"type":"object","properties":{"id":{"type":"string"},"path":{"type":"string"},"methods":{"type":"array","items":{"type":"string"}},"description":{"type":"string"},"tags":{"type":"array","items":{"type":"string"}}}}},"responses":{"Error500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}}}}}},"NotFound":{"description":"Resource not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}}}}}}}}}