openapi: 3.1.0
info:
  title: PlatPhorm News Root API
  version: 0.0.4
  description: Root public DMZ API for news aggregation, network graph discovery, support, status, integrations, trust policy, agent policy, route compliance, discovery compliance, OpenAPI, llms, RSS/feed, sitemap, and MCP introspection.
servers:
  - url: https://platphormnews.com
paths:
  /api/health:
    get:
      summary: Public health summary
      responses:
        "200":
          description: Health payload
  /api/network/graph:
    get:
      summary: Canonical public root network graph
      responses:
        "200":
          description: Network graph JSON
  /api/v1/stories:
    get:
      summary: Public story aggregation snapshot
      responses:
        "200":
          description: Stories response
  /api/v1/stories/{id}/comments:
    get:
      summary: Bounded sanitized story comments
      responses:
        "200":
          description: Story comments response
  /api/v1/stories/{id}/discussion:
    get:
      summary: Public source discussion metadata
      responses:
        "200":
          description: Story discussion response
  /api/v1/hn/{category}:
    get:
      summary: HN category feed with root metadata
      responses:
        "200":
          description: HN category response
  /api/v1/hn/item/{id}:
    get:
      summary: HN item detail
      responses:
        "200":
          description: HN item response
  /api/v1/hn/item/{id}/comments:
    get:
      summary: Bounded sanitized HN comments
      responses:
        "200":
          description: HN comments response
  /api/v1/hn/docs-ingest:
    post:
      summary: Protected HN newest-feed Docs ingestion
      responses:
        "200":
          description: HN Docs ingest dry-run or commit response
        "401":
          description: PLATPHORM_API_KEY required
  /api/cron/hn-docs-ingest:
    get:
      summary: Vercel cron HN newest-feed Docs ingestion
      responses:
        "200":
          description: Scheduled HN Docs ingest response
        "401":
          description: PLATPHORM_API_KEY or configured Vercel cron authorization required
  /api/v1/search:
    get:
      summary: Public story search
      parameters:
        - name: q
          in: query
          schema:
            type: string
      responses:
        "200":
          description: Search response
  /api/v1/search/{scope}:
    get:
      summary: Scoped root search across stories, comments, network, tools, APIs, and policies
      responses:
        "200":
          description: Scoped search response
  /api/v1/network/apis:
    get:
      summary: Source-backed API endpoint inventory
      responses:
        "200":
          description: API inventory response
  /api/v1/network/mcp:
    get:
      summary: Source-backed MCP tool and site inventory
      responses:
        "200":
          description: MCP inventory response
  /api/v1/network/evidence:
    get:
      summary: Route and discovery evidence
      responses:
        "200":
          description: Evidence response
  /api/v1/trustops/source:
    get:
      summary: TrustOps public source packet
      responses:
        "200":
          description: TrustOps source response
  /api/v1/searchops/source:
    get:
      summary: SearchOps public source packet
      responses:
        "200":
          description: SearchOps source response
  /api/v1/agentops/source:
    get:
      summary: AgentOps public source packet
      responses:
        "200":
          description: AgentOps source response
  /api/v1/support:
    get:
      summary: Public support directory
      responses:
        "200":
          description: Support categories and contact routes
  /api/v1/support/report:
    post:
      summary: Generate a redacted support report packet
      responses:
        "200":
          description: Public-safe support packet
        "401":
          description: PLATPHORM_API_KEY required for protected durable persistence
  /api/v1/status:
    get:
      summary: Public root status
      responses:
        "200":
          description: Status summary
  /api/v1/status/services:
    get:
      summary: Public integration status
      responses:
        "200":
          description: Integration status records
  /api/v1/public-contract:
    get:
      summary: Canonical public contract
      responses:
        "200":
          description: Public contract model for trust, MCP, llms, status, and docs
  /api/v1/integrations:
    get:
      summary: Integration directory
      responses:
        "200":
          description: Integration matrix
  /api/v1/trust:
    get:
      summary: Trust policy
      responses:
        "200":
          description: Trust policy JSON
  /api/v1/agent-policy:
    get:
      summary: Agent and crawler policy
      responses:
        "200":
          description: Agent policy JSON
  /api/v1/route-compliance:
    get:
      summary: Route compliance
      responses:
        "200":
          description: Live route compliance result
  /api/v1/discovery-compliance:
    get:
      summary: Discovery compliance
      responses:
        "200":
          description: Live discovery compliance result
  /api/mcp:
    get:
      summary: Root MCP metadata
      responses:
        "200":
          description: MCP manifest
    post:
      summary: Root MCP JSON-RPC endpoint
      responses:
        "200":
          description: JSON-RPC result
  /openapi.json:
    get:
      summary: OpenAPI JSON
      responses:
        "200":
          description: OpenAPI JSON document
  /rss.xml:
    get:
      summary: Public RSS feed
      responses:
        "200":
          description: RSS XML
  /sitemap.xml:
    get:
      summary: Public root sitemap
      responses:
        "200":
          description: Sitemap XML
  /sitemap-index.xml:
    get:
      summary: Split sitemap index
      responses:
        "200":
          description: Sitemap index XML
  /sitemap-main.xml:
    get:
      summary: Main root route sitemap
      responses:
        "200":
          description: Main sitemap XML
  /sitemap-network.xml:
    get:
      summary: Network URL sitemap
      responses:
        "200":
          description: Network sitemap XML
  /sitemap-full.xml:
    get:
      summary: Combined root and network sitemap
      responses:
        "200":
          description: Full sitemap XML
  /llms-index.json:
    get:
      summary: LLM JSON index
      responses:
        "200":
          description: Structured LLM endpoint index
  /llm-index.json:
    get:
      summary: LLM JSON index alias
      responses:
        "200":
          description: Compatibility alias for /llms-index.json
  /manifest.webmanifest:
    get:
      summary: Web app manifest
      responses:
        "200":
          description: Web manifest JSON
  /humans.txt:
    get:
      summary: Humans.txt
      responses:
        "200":
          description: Human-readable site credits
components:
  securitySchemes:
    PlatPhormBearer:
      type: http
      scheme: bearer
      description: Protected actions accept Authorization: Bearer $PLATPHORM_API_KEY.
    PlatPhormApiKey:
      type: apiKey
      in: header
      name: X-PlatPhorm-API-Key
      description: Protected actions accept X-PlatPhorm-API-Key: $PLATPHORM_API_KEY.
