openapi: "3.1.0"
info:
  title: "Quake / PlatPhorm Arena API"
  version: "1.0.0"
  description: "Canonical browser FPS arena API for live server sessions, protected server registration, match records, leaderboard, bot practice, game events, discovery, and MCP. Public reads are available; protected mutations use PLATPHORM_API_KEY only."
servers:
  - 
    url: "https://quake.innovativefuturesolutions.com"
components:
  securitySchemes:
    PlatPhormBearer:
      type: "http"
      scheme: "bearer"
      description: "Use Authorization: Bearer $PLATPHORM_API_KEY for protected Quake operations."
    PlatPhormApiKey:
      type: "apiKey"
      in: "header"
      name: "X-PlatPhorm-API-Key"
      description: "Use X-PlatPhorm-API-Key: $PLATPHORM_API_KEY for protected Quake operations."
paths:
  /api/health:
    get:
      summary: "Public Quake health summary with honest degraded persistence state"
      description: "Public Quake health summary with honest degraded persistence state"
      responses:
        200:
          description: "OK"
  /api/v1/health:
    get:
      summary: "Versioned public Quake health summary"
      description: "Versioned public Quake health summary"
      responses:
        200:
          description: "OK"
  /api/v1/servers:
    get:
      summary: "List real active browser sessions and protected registered servers"
      description: "List real active browser sessions and protected registered servers"
      responses:
        200:
          description: "OK"
    post:
      summary: "Register a Quake game server"
      description: "Register a Quake game server. Protected write/admin operations require Authorization: Bearer $PLATPHORM_API_KEY or X-PlatPhorm-API-Key: $PLATPHORM_API_KEY."
      responses:
        200:
          description: "OK"
        401:
          description: "Missing or invalid PLATPHORM_API_KEY"
      security:
        - 
          PlatPhormApiKey:

        - 
          PlatPhormBearer:

  /api/v1/servers/{id}:
    get:
      summary: "Get one server with roster and host-owned map, mode, capacity, and configured bot count when backed by an active browser session"
      description: "Get one server with roster and host-owned map, mode, capacity, and configured bot count when backed by an active browser session"
      responses:
        200:
          description: "OK"
    patch:
      summary: "Update protected server state"
      description: "Update protected server state. Protected write/admin operations require Authorization: Bearer $PLATPHORM_API_KEY or X-PlatPhorm-API-Key: $PLATPHORM_API_KEY."
      responses:
        200:
          description: "OK"
        401:
          description: "Missing or invalid PLATPHORM_API_KEY"
      security:
        - 
          PlatPhormApiKey:

        - 
          PlatPhormBearer:

    delete:
      summary: "Deregister a protected server"
      description: "Deregister a protected server. Protected write/admin operations require Authorization: Bearer $PLATPHORM_API_KEY or X-PlatPhorm-API-Key: $PLATPHORM_API_KEY."
      responses:
        200:
          description: "OK"
        401:
          description: "Missing or invalid PLATPHORM_API_KEY"
      security:
        - 
          PlatPhormApiKey:

        - 
          PlatPhormBearer:

  /api/v1/servers/{id}/heartbeat:
    post:
      summary: "Record a protected server heartbeat"
      description: "Record a protected server heartbeat. Protected write/admin operations require Authorization: Bearer $PLATPHORM_API_KEY or X-PlatPhorm-API-Key: $PLATPHORM_API_KEY."
      responses:
        200:
          description: "OK"
        401:
          description: "Missing or invalid PLATPHORM_API_KEY"
      security:
        - 
          PlatPhormApiKey:

        - 
          PlatPhormBearer:

  /api/v1/matches:
    get:
      summary: "List protected recorded match history; returns empty when no real records exist"
      description: "List protected recorded match history; returns empty when no real records exist"
      responses:
        200:
          description: "OK"
    post:
      summary: "Create a match draft or record a match result"
      description: "Create a match draft or record a match result. Protected write/admin operations require Authorization: Bearer $PLATPHORM_API_KEY or X-PlatPhorm-API-Key: $PLATPHORM_API_KEY."
      responses:
        200:
          description: "OK"
        401:
          description: "Missing or invalid PLATPHORM_API_KEY"
      security:
        - 
          PlatPhormApiKey:

        - 
          PlatPhormBearer:

  /api/v1/matches/{id}:
    get:
      summary: "Get one match record"
      description: "Get one match record"
      responses:
        200:
          description: "OK"
  /api/v1/matches/active:
    get:
      summary: "List live human-backed matches with host, rules, elapsed time, bot fill, kills, deaths, and leaderboard"
      description: "List live human-backed matches with host, rules, elapsed time, bot fill, kills, deaths, and leaderboard"
      responses:
        200:
          description: "OK"
  /api/v1/matches/active/{id}:
    get:
      summary: "Get one public-safe live match snapshot"
      description: "Get one public-safe live match snapshot"
      responses:
        200:
          description: "OK"
  /api/v1/matches/{id}/join:
    post:
      summary: "Return a browser play URL for a match"
      description: "Return a browser play URL for a match"
      responses:
        200:
          description: "OK"
  /api/v1/matches/{id}/leave:
    post:
      summary: "Acknowledge browser match leave state"
      description: "Acknowledge browser match leave state"
      responses:
        200:
          description: "OK"
  /api/v1/matches/{id}/record:
    post:
      summary: "Record a protected official or local/degraded match result"
      description: "Record a protected official or local/degraded match result. Protected write/admin operations require Authorization: Bearer $PLATPHORM_API_KEY or X-PlatPhorm-API-Key: $PLATPHORM_API_KEY."
      responses:
        200:
          description: "OK"
        401:
          description: "Missing or invalid PLATPHORM_API_KEY"
      security:
        - 
          PlatPhormApiKey:

        - 
          PlatPhormBearer:

  /api/v1/matches/{id}/events:
    get:
      summary: "List public-safe events for one match"
      description: "List public-safe events for one match"
      responses:
        200:
          description: "OK"
  /api/v1/leaderboard:
    get:
      summary: "Leaderboard derived only from real recorded match results"
      description: "Leaderboard derived only from real recorded match results"
      responses:
        200:
          description: "OK"
  /api/v1/stats:
    get:
      summary: "Global game stats derived from active sessions and recorded matches"
      description: "Global game stats derived from active sessions and recorded matches"
      responses:
        200:
          description: "OK"
  /api/v1/maps:
    get:
      summary: "List playable and honestly degraded Quake map catalog entries"
      description: "List playable and honestly degraded Quake map catalog entries"
      responses:
        200:
          description: "OK"
  /api/v1/maps/{id}:
    get:
      summary: "Get one Quake map with playable/degraded state"
      description: "Get one Quake map with playable/degraded state"
      responses:
        200:
          description: "OK"
  /api/v1/modes:
    get:
      summary: "List Quake modes with playable/local/degraded truth labels"
      description: "List Quake modes with playable/local/degraded truth labels"
      responses:
        200:
          description: "OK"
  /api/v1/weapons:
    get:
      summary: "List shipped Quake weapon behavior, ammo, damage, and telemetry metadata"
      description: "List shipped Quake weapon behavior, ammo, damage, and telemetry metadata"
      responses:
        200:
          description: "OK"
  /api/v1/player/local-schema:
    get:
      summary: "Describe browser-local player profile, settings, stats, and forbidden secret fields"
      description: "Describe browser-local player profile, settings, stats, and forbidden secret fields"
      responses:
        200:
          description: "OK"
  /api/v1/performance/status:
    get:
      summary: "Describe browser-runtime WebGL/FPS/pointer-lock detection and reduced-effects policy"
      description: "Describe browser-runtime WebGL/FPS/pointer-lock detection and reduced-effects policy"
      responses:
        200:
          description: "OK"
  /api/v1/xr/status:
    get:
      summary: "Describe WebXR, Meta Quest, AR, VR, and comfort-mode readiness with client runtime detection"
      description: "Describe WebXR, Meta Quest, AR, VR, and comfort-mode readiness with client runtime detection"
      responses:
        200:
          description: "OK"
  /api/v1/game/manifest:
    get:
      summary: "Get public Quake game manifest and exact capability counts"
      description: "Get public Quake game manifest and exact capability counts"
      responses:
        200:
          description: "OK"
  /api/v1/game-assets/integrations:
    get:
      summary: "Get the ordered, versioned, public-safe optional game asset-service registry"
      description: "Get the ordered, versioned, public-safe optional game asset-service registry"
      responses:
        200:
          description: "OK"
  /api/v1/game/config:
    get:
      summary: "Get public Quake game configuration defaults and local settings keys"
      description: "Get public Quake game configuration defaults and local settings keys"
      responses:
        200:
          description: "OK"
  /api/v1/lan/status:
    get:
      summary: "Get public LAN/WebRTC transport support and honest limitations"
      description: "Get public LAN/WebRTC transport support and honest limitations"
      responses:
        200:
          description: "OK"
  /api/v1/model/status:
    get:
      summary: "Get backend model-integration and isolated Workers AI coach status with deterministic fallback for unsupported tasks"
      description: "Get backend model-integration and isolated Workers AI coach status with deterministic fallback for unsupported tasks"
      responses:
        200:
          description: "OK"
  /api/v1/bots:
    get:
      summary: "List local AI bot profiles available for practice"
      description: "List local AI bot profiles available for practice"
      responses:
        200:
          description: "OK"
  /api/v1/ai/coach:
    get:
      summary: "Describe the isolated Cloudflare Workers AI post-match coach"
      description: "Describe the isolated Cloudflare Workers AI post-match coach"
      responses:
        200:
          description: "OK"
    post:
      summary: "Generate bounded post-match coaching from caller-supplied match statistics"
      description: "Generate bounded post-match coaching from caller-supplied match statistics. Protected write/admin operations require Authorization: Bearer $PLATPHORM_API_KEY or X-PlatPhorm-API-Key: $PLATPHORM_API_KEY."
      responses:
        200:
          description: "OK"
        401:
          description: "Missing or invalid PLATPHORM_API_KEY"
      security:
        - 
          PlatPhormApiKey:

        - 
          PlatPhormBearer:

  /api/multiplayer/status:
    get:
      summary: "Probe the active multiplayer backend and report Cloudflare edge-room or fallback reachability without exposing connection details"
      description: "Probe the active multiplayer backend and report Cloudflare edge-room or fallback reachability without exposing connection details"
      responses:
        200:
          description: "OK"
  /api/multiplayer/sessions/{sessionId}:
    get:
      summary: "Poll player/event deltas, server timing, and synchronized broken-block/Combat Matter world state"
      description: "Poll player/event deltas, server timing, and synchronized broken-block/Combat Matter world state"
      responses:
        200:
          description: "OK"
  /api/multiplayer/sessions/{sessionId}/join:
    post:
      summary: "Atomically join a capacity-bounded room coordinated by its Cloudflare Durable Object"
      description: "Atomically join a capacity-bounded room coordinated by its Cloudflare Durable Object"
      responses:
        200:
          description: "OK"
  /api/multiplayer/sessions/{sessionId}/events:
    post:
      summary: "Publish bounded movement, crouch, combat, arena chat, death, block-world, and Combat Matter events"
      description: "Publish bounded movement, crouch, combat, arena chat, death, block-world, and Combat Matter events"
      responses:
        200:
          description: "OK"
  /api/multiplayer/sessions/{sessionId}/reports:
    post:
      summary: "Report an existing arena-chat message for protected D1-backed moderation review"
      description: "Report an existing arena-chat message for protected D1-backed moderation review"
      responses:
        200:
          description: "OK"
  /api/multiplayer/sessions/{sessionId}/leave:
    post:
      summary: "Leave an ephemeral browser-game room"
      description: "Leave an ephemeral browser-game room"
      responses:
        200:
          description: "OK"
  /api/v1/practice:
    post:
      summary: "Start a local bot practice session"
      description: "Start a local bot practice session"
      responses:
        200:
          description: "OK"
  /api/v1/practice/{id}:
    get:
      summary: "Get one local practice session"
      description: "Get one local practice session"
      responses:
        200:
          description: "OK"
  /api/v1/practice/{id}/record:
    post:
      summary: "Record a local practice result"
      description: "Record a local practice result"
      responses:
        200:
          description: "OK"
  /api/events:
    get:
      summary: "List public-safe game event outbox entries"
      description: "List public-safe game event outbox entries"
      responses:
        200:
          description: "OK"
  /api/v1/events:
    get:
      summary: "Versioned public-safe game event outbox"
      description: "Versioned public-safe game event outbox"
      responses:
        200:
          description: "OK"
  /api/webhooks:
    post:
      summary: "Receive a signed game webhook; webhook signature is authenticity, not platform auth"
      description: "Receive a signed game webhook; webhook signature is authenticity, not platform auth"
      responses:
        200:
          description: "OK"
  /api/v1/webhooks:
    post:
      summary: "Versioned signed game webhook receiver"
      description: "Versioned signed game webhook receiver"
      responses:
        200:
          description: "OK"
  /api/v1/webhooks/status:
    get:
      summary: "Read public-safe webhook/event status"
      description: "Read public-safe webhook/event status"
      responses:
        200:
          description: "OK"
  /api/mcp:
    get:
      summary: "MCP metadata, tools, resources, prompts, and usage"
      description: "MCP metadata, tools, resources, prompts, and usage"
      responses:
        200:
          description: "OK"
    post:
      summary: "MCP JSON-RPC 2.0 endpoint; protected tools require PLATPHORM_API_KEY"
      description: "MCP JSON-RPC 2.0 endpoint; protected tools require PLATPHORM_API_KEY"
      responses:
        200:
          description: "OK"
  /llms.txt:
    get:
      summary: "Concise LLM-readable Quake platform context"
      description: "Concise LLM-readable Quake platform context"
      responses:
        200:
          description: "OK"
  /llms-full.txt:
    get:
      summary: "Full LLM-readable Quake platform context"
      description: "Full LLM-readable Quake platform context"
      responses:
        200:
          description: "OK"
  /llms-index.json:
    get:
      summary: "LLM discovery index"
      description: "LLM discovery index"
      responses:
        200:
          description: "OK"
  /openapi.yaml:
    get:
      summary: "OpenAPI YAML"
      description: "OpenAPI YAML"
      responses:
        200:
          description: "OK"
  /openapi.json:
    get:
      summary: "OpenAPI JSON"
      description: "OpenAPI JSON"
      responses:
        200:
          description: "OK"
  /rss.xml:
    get:
      summary: "Public-safe RSS feed for active matches, recorded results, and game events"
      description: "Public-safe RSS feed for active matches, recorded results, and game events"
      responses:
        200:
          description: "OK"
  /feed.xml:
    get:
      summary: "Public-safe Atom feed for active matches, recorded results, and game events"
      description: "Public-safe Atom feed for active matches, recorded results, and game events"
      responses:
        200:
          description: "OK"
  /sitemap.xml:
    get:
      summary: "Sitemap"
      description: "Sitemap"
      responses:
        200:
          description: "OK"
  /sitemap-main.xml:
    get:
      summary: "Main sitemap XML generated from public route/catalog state"
      description: "Main sitemap XML generated from public route/catalog state"
      responses:
        200:
          description: "OK"
  /sitemap-index.xml:
    get:
      summary: "Sitemap index"
      description: "Sitemap index"
      responses:
        200:
          description: "OK"
  /manifest.webmanifest:
    get:
      summary: "Web app manifest"
      description: "Web app manifest"
      responses:
        200:
          description: "OK"
  /manifest.json:
    get:
      summary: "Legacy manifest alias"
      description: "Legacy manifest alias"
      responses:
        200:
          description: "OK"
  /faq:
    get:
      summary: "FAQ page"
      description: "FAQ page"
      responses:
        200:
          description: "OK"
  /offline:
    get:
      summary: "PWA offline fallback page"
      description: "PWA offline fallback page"
      responses:
        200:
          description: "OK"
  /privacy:
    get:
      summary: "Privacy page"
      description: "Privacy page"
      responses:
        200:
          description: "OK"
  /terms:
    get:
      summary: "Terms page"
      description: "Terms page"
      responses:
        200:
          description: "OK"
  /disclaimer:
    get:
      summary: "Gameplay and multiplayer truth-state disclaimer"
      description: "Gameplay and multiplayer truth-state disclaimer"
      responses:
        200:
          description: "OK"
  /.well-known/mcp.json:
    get:
      summary: "MCP discovery"
      description: "MCP discovery"
      responses:
        200:
          description: "OK"
  /.well-known/agents.json:
    get:
      summary: "Agent discovery"
      description: "Agent discovery"
      responses:
        200:
          description: "OK"
  /.well-known/security.txt:
    get:
      summary: "Security contact and policy"
      description: "Security contact and policy"
      responses:
        200:
          description: "OK"
  /.well-known/trust.json:
    get:
      summary: "Trust policy and public/protected boundary"
      description: "Trust policy and public/protected boundary"
      responses:
        200:
          description: "OK"
x-quake-mcp:
  tools:
    - "list_servers"
    - "get_server"
    - "register_server"
    - "update_server"
    - "deregister_server"
    - "list_matches"
    - "list_active_matches"
    - "get_active_match"
    - "get_match"
    - "create_match"
    - "join_match"
    - "record_match"
    - "get_leaderboard"
    - "get_global_stats"
    - "list_maps"
    - "get_map"
    - "list_modes"
    - "list_weapons"
    - "get_game_manifest"
    - "get_performance_status"
    - "get_lan_status"
    - "validate_game_routes"
    - "validate_playable_arena"
    - "get_health"
    - "get_info"
    - "list_bots"
    - "start_bot_practice"
    - "record_practice_result"
    - "list_game_events"
    - "receive_game_webhook"
    - "get_route_compliance"
    - "get_discovery_compliance"
    - "create_docs_report"
    - "create_sheet_report"
    - "create_deck_summary"
  resources:
    - "quake://servers"
    - "quake://server/{id}"
    - "quake://matches"
    - "quake://active-matches"
    - "quake://match/{id}"
    - "quake://leaderboard"
    - "quake://stats"
    - "quake://maps"
    - "quake://map/{id}"
    - "quake://modes"
    - "quake://weapons"
    - "quake://game-manifest"
    - "quake://performance"
    - "quake://lan-status"
    - "quake://faq"
    - "quake://bots"
    - "quake://events"
    - "quake://settings"
    - "quake://openapi"
    - "quake://llms"
    - "quake://trust-policy"
  prompts:
    - "recommend_quake_server"
    - "explain_quake_mode"
    - "explain_quake_weapon"
    - "summarize_match"
    - "generate_bot_tuning_notes"
    - "create_game_testing_plan"
    - "create_quake_report"
    - "human_machine_quake_handoff"
