openapi: "3.1.0"
info:
  title: "PlatPhorm 404 API"
  version: "1.0.0-phase1"
  description: "Canonical public 404 recovery, dead-link intelligence, route search, link-checking, sitemap validation, redirect suggestion, and MCP tooling for the PlatPhormNews web mesh."
  contact:
    name: "PlatPhormNews"
    url: "https://platphormnews.com"
servers:
  - 
    url: "https://404.platphormnews.com"
    description: "Production"
tags:
  - 
    name: "404 tools"
    description: "Route recovery, reporting, link checks, sitemap validation, and redirect suggestions."
  - 
    name: "API"
    description: "Public-safe API and health routes."
  - 
    name: "Discovery"
    description: "Machine-readable discovery files."
  - 
    name: "Pages"
    description: "Human recovery pages."
paths:
  /api/v1/search:
    post:
      tags:
        - "404 tools"
      summary: "POST /api/v1/search"
      description: "Public-safe Phase 1 tool endpoint. Future protected mutations use PLATPHORM_API_KEY when enabled."
      responses:
        200:
          description: "Tool response"
        400:
          description: "Validation error"
      security:

      x-future-protected-auth: "PLATPHORM_API_KEY"
  /api/v1/recover:
    post:
      tags:
        - "404 tools"
      summary: "POST /api/v1/recover"
      description: "Public-safe Phase 1 tool endpoint. Future protected mutations use PLATPHORM_API_KEY when enabled."
      responses:
        200:
          description: "Tool response"
        400:
          description: "Validation error"
      security:

      x-future-protected-auth: "PLATPHORM_API_KEY"
  /api/v1/routes:
    get:
      tags:
        - "API"
      summary: "GET /api/v1/routes"
      description: "Public-safe Phase 1 read surface."
      responses:
        200:
          description: "Public-safe response"
      security:

  /api/v1/dead-links:
    get:
      tags:
        - "API"
      summary: "GET /api/v1/dead-links"
      description: "Public-safe Phase 1 read surface."
      responses:
        200:
          description: "Public-safe response"
      security:

  /api/v1/sitemap/status:
    get:
      tags:
        - "API"
      summary: "GET /api/v1/sitemap/status"
      description: "Public-safe Phase 1 read surface."
      responses:
        200:
          description: "Public-safe response"
      security:

  /api/v1/network/graph:
    get:
      tags:
        - "API"
      summary: "GET /api/v1/network/graph"
      description: "Public-safe Phase 1 read surface."
      responses:
        200:
          description: "Public-safe response"
      security:

  /api/v1/network/sites:
    get:
      tags:
        - "API"
      summary: "GET /api/v1/network/sites"
      description: "Public-safe Phase 1 read surface."
      responses:
        200:
          description: "Public-safe response"
      security:

  /api/v1/network/route-compliance:
    get:
      tags:
        - "API"
      summary: "GET /api/v1/network/route-compliance"
      description: "Public-safe Phase 1 read surface."
      responses:
        200:
          description: "Public-safe response"
      security:

  /api/v1/network/discovery-compliance:
    get:
      tags:
        - "API"
      summary: "GET /api/v1/network/discovery-compliance"
      description: "Public-safe Phase 1 read surface."
      responses:
        200:
          description: "Public-safe response"
      security:

  /api/docs:
    get:
      tags:
        - "API"
      summary: "GET /api/docs"
      description: "Public-safe Phase 1 read surface."
      responses:
        200:
          description: "Public-safe response"
      security:

  /api/health:
    get:
      tags:
        - "API"
      summary: "GET /api/health"
      description: "Public-safe Phase 1 read surface."
      responses:
        200:
          description: "Public-safe response"
      security:

  /api/v1/health:
    get:
      tags:
        - "API"
      summary: "GET /api/v1/health"
      description: "Public-safe Phase 1 read surface."
      responses:
        200:
          description: "Public-safe response"
      security:

  /api/mcp:
    post:
      tags:
        - "404 tools"
      summary: "POST /api/mcp"
      description: "JSON-RPC 2.0 MCP endpoint."
      responses:
        200:
          description: "Tool response"
        400:
          description: "Validation error"
      security:

      x-future-protected-auth: "PLATPHORM_API_KEY"
  /openapi.yaml:
    get:
      tags:
        - "Discovery"
      summary: "GET /openapi.yaml"
      description: "Public-safe Phase 1 read surface."
      responses:
        200:
          description: "Public-safe response"
      security:

  /openapi.json:
    get:
      tags:
        - "Discovery"
      summary: "GET /openapi.json"
      description: "Public-safe Phase 1 read surface."
      responses:
        200:
          description: "Public-safe response"
      security:

  /llms.txt:
    get:
      tags:
        - "Discovery"
      summary: "GET /llms.txt"
      description: "Public-safe Phase 1 read surface."
      responses:
        200:
          description: "Public-safe response"
      security:

  /llms-full.txt:
    get:
      tags:
        - "Discovery"
      summary: "GET /llms-full.txt"
      description: "Public-safe Phase 1 read surface."
      responses:
        200:
          description: "Public-safe response"
      security:

  /llms-index.json:
    get:
      tags:
        - "Discovery"
      summary: "GET /llms-index.json"
      description: "Public-safe Phase 1 read surface."
      responses:
        200:
          description: "Public-safe response"
      security:

  /robots.txt:
    get:
      tags:
        - "Discovery"
      summary: "GET /robots.txt"
      description: "Public-safe Phase 1 read surface."
      responses:
        200:
          description: "Public-safe response"
      security:

  /rss.xml:
    get:
      tags:
        - "Discovery"
      summary: "GET /rss.xml"
      description: "Public-safe Phase 1 read surface."
      responses:
        200:
          description: "Public-safe response"
      security:

  /feed.xml:
    get:
      tags:
        - "Discovery"
      summary: "GET /feed.xml"
      description: "Public-safe Phase 1 read surface."
      responses:
        200:
          description: "Public-safe response"
      security:

  /sitemap.xml:
    get:
      tags:
        - "Discovery"
      summary: "GET /sitemap.xml"
      description: "Public-safe Phase 1 read surface."
      responses:
        200:
          description: "Public-safe response"
      security:

  /sitemap-main.xml:
    get:
      tags:
        - "Discovery"
      summary: "GET /sitemap-main.xml"
      description: "Public-safe Phase 1 read surface."
      responses:
        200:
          description: "Public-safe response"
      security:

  /sitemap-index.xml:
    get:
      tags:
        - "Discovery"
      summary: "GET /sitemap-index.xml"
      description: "Public-safe Phase 1 read surface."
      responses:
        200:
          description: "Public-safe response"
      security:

  /manifest.webmanifest:
    get:
      tags:
        - "Discovery"
      summary: "GET /manifest.webmanifest"
      description: "Public-safe Phase 1 read surface."
      responses:
        200:
          description: "Public-safe response"
      security:

  /.well-known/mcp.json:
    get:
      tags:
        - "Discovery"
      summary: "GET /.well-known/mcp.json"
      description: "Public-safe Phase 1 read surface."
      responses:
        200:
          description: "Public-safe response"
      security:

  /.well-known/agents.json:
    get:
      tags:
        - "Discovery"
      summary: "GET /.well-known/agents.json"
      description: "Public-safe Phase 1 read surface."
      responses:
        200:
          description: "Public-safe response"
      security:

  /.well-known/ai-plugin.json:
    get:
      tags:
        - "Discovery"
      summary: "GET /.well-known/ai-plugin.json"
      description: "Public-safe Phase 1 read surface."
      responses:
        200:
          description: "Public-safe response"
      security:

  /.well-known/security.txt:
    get:
      tags:
        - "Discovery"
      summary: "GET /.well-known/security.txt"
      description: "Public-safe Phase 1 read surface."
      responses:
        200:
          description: "Public-safe response"
      security:

  /.well-known/trust.json:
    get:
      tags:
        - "Discovery"
      summary: "GET /.well-known/trust.json"
      description: "Public-safe Phase 1 read surface."
      responses:
        200:
          description: "Public-safe response"
      security:

  /:
    get:
      tags:
        - "Pages"
      summary: "GET /"
      description: "Public-safe Phase 1 read surface."
      responses:
        200:
          description: "Public-safe response"
      security:

  /search:
    get:
      tags:
        - "Pages"
      summary: "GET /search"
      description: "Public-safe Phase 1 read surface."
      responses:
        200:
          description: "Public-safe response"
      security:

  /report:
    get:
      tags:
        - "Pages"
      summary: "GET /report"
      description: "Public-safe Phase 1 read surface."
      responses:
        200:
          description: "Public-safe response"
      security:

  /routes:
    get:
      tags:
        - "Pages"
      summary: "GET /routes"
      description: "Public-safe Phase 1 read surface."
      responses:
        200:
          description: "Public-safe response"
      security:

  /dead-links:
    get:
      tags:
        - "Pages"
      summary: "GET /dead-links"
      description: "Public-safe Phase 1 read surface."
      responses:
        200:
          description: "Public-safe response"
      security:

  /sitemap-status:
    get:
      tags:
        - "Pages"
      summary: "GET /sitemap-status"
      description: "Public-safe Phase 1 read surface."
      responses:
        200:
          description: "Public-safe response"
      security:

  /redirects:
    get:
      tags:
        - "Pages"
      summary: "GET /redirects"
      description: "Public-safe Phase 1 read surface."
      responses:
        200:
          description: "Public-safe response"
      security:

  /network:
    get:
      tags:
        - "Pages"
      summary: "GET /network"
      description: "Public-safe Phase 1 read surface."
      responses:
        200:
          description: "Public-safe response"
      security:

  /faq:
    get:
      tags:
        - "Pages"
      summary: "GET /faq"
      description: "Public-safe Phase 1 read surface."
      responses:
        200:
          description: "Public-safe response"
      security:

  /privacy:
    get:
      tags:
        - "Pages"
      summary: "GET /privacy"
      description: "Public-safe Phase 1 read surface."
      responses:
        200:
          description: "Public-safe response"
      security:

  /terms:
    get:
      tags:
        - "Pages"
      summary: "GET /terms"
      description: "Public-safe Phase 1 read surface."
      responses:
        200:
          description: "Public-safe response"
      security:

  /api/v1/report:
    post:
      tags:
        - "404 tools"
      summary: "POST /api/v1/report"
      description: "Public-safe Phase 1 tool endpoint. Future protected mutations use PLATPHORM_API_KEY when enabled."
      responses:
        200:
          description: "Tool response"
        400:
          description: "Validation error"
      security:

      x-future-protected-auth: "PLATPHORM_API_KEY"
  /api/v1/link-check:
    post:
      tags:
        - "404 tools"
      summary: "POST /api/v1/link-check"
      description: "Public-safe Phase 1 tool endpoint. Future protected mutations use PLATPHORM_API_KEY when enabled."
      responses:
        200:
          description: "Tool response"
        400:
          description: "Validation error"
      security:

      x-future-protected-auth: "PLATPHORM_API_KEY"
  /api/v1/sitemap/validate:
    post:
      tags:
        - "404 tools"
      summary: "POST /api/v1/sitemap/validate"
      description: "Public-safe Phase 1 tool endpoint. Future protected mutations use PLATPHORM_API_KEY when enabled."
      responses:
        200:
          description: "Tool response"
        400:
          description: "Validation error"
      security:

      x-future-protected-auth: "PLATPHORM_API_KEY"
  /api/v1/redirects/suggest:
    post:
      tags:
        - "404 tools"
      summary: "POST /api/v1/redirects/suggest"
      description: "Public-safe Phase 1 tool endpoint. Future protected mutations use PLATPHORM_API_KEY when enabled."
      responses:
        200:
          description: "Tool response"
        400:
          description: "Validation error"
      security:

      x-future-protected-auth: "PLATPHORM_API_KEY"
  /api/v1/report/{id}:
    get:
      tags:
        - "404 tools"
      summary: "Read dead-link report by id"
      description: "Reads a server or ephemeral dead-link report when available. Without database persistence this can return REPORT_NOT_FOUND after runtime reset."
      parameters:
        - 
          name: "id"
          in: "path"
          required: true
          schema:
            type: "string"
      responses:
        200:
          description: "Report response"
        404:
          description: "Report not found"
      security:

  /api/v1/routes/{id}:
    get:
      tags:
        - "404 tools"
      summary: "Read route inventory record by id"
      description: "Reads a public-safe route record from current inventory."
      parameters:
        - 
          name: "id"
          in: "path"
          required: true
          schema:
            type: "string"
      responses:
        200:
          description: "Route response"
        404:
          description: "Route not found"
      security:

components:
  securitySchemes:
    PlatPhormApiKey:
      type: "apiKey"
      in: "header"
      name: "X-PlatPhorm-API-Key"
      description: "Future protected actions accept PLATPHORM_API_KEY via this header or Authorization: Bearer $PLATPHORM_API_KEY when PLATPHORM_REQUIRE_API_KEY=true."
  schemas:
    RestOk:
      type: "object"
      properties:
        ok:
          const: true
        data:
          type: "object"
    RestError:
      type: "object"
      properties:
        ok:
          const: false
        error:
          type: "object"
x-auth-policy:
  publicSafeByDefault: true
  protectedActionKey: "PLATPHORM_API_KEY"
  enforcementFlag: "PLATPHORM_REQUIRE_API_KEY"
  enforcementEnabled: false
  acceptedHeaders:
    - "Authorization: Bearer $PLATPHORM_API_KEY"
    - "X-PlatPhorm-API-Key: $PLATPHORM_API_KEY"
  futureProtectedActions:
    - "redirect mutation"
    - "private dead-link reports"
    - "backfill and sync jobs"
    - "report generation"
    - "registry mutation"
    - "trusted-domain mutation"
    - "sensitive audit details"
x-public-safe-default: true
x-trust-policy: "Public-safe 404 recovery, route search, dead-link reporting, sitemap validation, redirect suggestions, local non-sensitive report draft persistence, read-only MCP introspection, RSS/feed consumption, trusted-domain discovery, standard route compliance, Vercel metadata capture, backend model scaffolding, and trace-linked 404 operations are intentionally supported for public use. PLATPHORM_API_KEY support is scaffolded for future protected backend services, redirect mutation, private reports, sync, test-triggering, reporting, administrative actions, and sensitive operations."