openapi: 3.1.0
info:
  title: "Desert Bus Westfalia Edition API"
  version: 0.1.0
  description: "Public browser tribute game for the 1979 VW Westfalia Desert Bus endurance premise. Canonical mode is 360 miles at 45 mph. This is an unofficial tribute and does not process donations."
servers:
  - 
    url: https://desertbus.platphormnews.com
tags:
  - 
    name: game
    description: "Desert Bus gameplay, route, rules, and milestone metadata."
  - 
    name: platform
    description: "Health, discovery, MCP, auth boundary, and integration metadata."
  - 
    name: charity
    description: "Official outbound charity links only."
paths:
  /api/health:
    get:
      summary: "Health summary with honest degraded states."
      description: "Health summary with honest degraded states. Boundary: public-safe."
      security: []
      responses:
        200:
          description: "Standard PlatPhorm response"
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/PlatPhormResponse"
  /api/v1/health:
    get:
      summary: "Versioned health summary."
      description: "Versioned health summary. Boundary: public-safe."
      security: []
      responses:
        200:
          description: "Standard PlatPhorm response"
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/PlatPhormResponse"
  /api/v1/game:
    get:
      summary: "Game metadata and rules."
      description: "Game metadata and rules. Boundary: public-safe."
      security: []
      responses:
        200:
          description: "Standard PlatPhorm response"
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/PlatPhormResponse"
  /api/v1/game/state-schema:
    get:
      summary: "Local game state schema."
      description: "Local game state schema. Boundary: public-safe."
      security: []
      responses:
        200:
          description: "Standard PlatPhorm response"
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/PlatPhormResponse"
  /api/v1/game/rules:
    get:
      summary: "Canonical and non-canonical mode rules."
      description: "Canonical and non-canonical mode rules. Boundary: public-safe."
      security: []
      responses:
        200:
          description: "Standard PlatPhorm response"
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/PlatPhormResponse"
  /api/v1/runs/local-schema:
    get:
      summary: "Browser-local run schema."
      description: "Browser-local run schema. Boundary: public-safe."
      security: []
      responses:
        200:
          description: "Standard PlatPhorm response"
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/PlatPhormResponse"
  /api/v1/leaderboard:
    get:
      summary: "Leaderboard policy and ephemeral server cache."
      description: "Leaderboard policy and ephemeral server cache. Boundary: public-safe."
      security: []
      responses:
        200:
          description: "Standard PlatPhorm response"
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/PlatPhormResponse"
  /api/v1/route:
    get:
      summary: "Route and landmarks."
      description: "Route and landmarks. Boundary: public-safe."
      security: []
      responses:
        200:
          description: "Standard PlatPhorm response"
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/PlatPhormResponse"
  /api/v1/milestones:
    get:
      summary: "Route milestones including Dateland."
      description: "Route milestones including Dateland. Boundary: public-safe."
      security: []
      responses:
        200:
          description: "Standard PlatPhorm response"
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/PlatPhormResponse"
  /api/v1/charity-links:
    get:
      summary: "Official external charity links."
      description: "Official external charity links. Boundary: public-safe."
      security: []
      responses:
        200:
          description: "Standard PlatPhorm response"
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/PlatPhormResponse"
  /api/v1/story:
    get:
      summary: "Story sections."
      description: "Story sections. Boundary: public-safe."
      security: []
      responses:
        200:
          description: "Standard PlatPhorm response"
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/PlatPhormResponse"
  /api/v1/polaroids:
    get:
      summary: "Accessible polaroid gallery metadata."
      description: "Accessible polaroid gallery metadata. Boundary: public-safe."
      security: []
      responses:
        200:
          description: "Standard PlatPhorm response"
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/PlatPhormResponse"
  /api/events:
    get:
      summary: "Event capability metadata."
      description: "Event capability metadata. Boundary: public-safe."
      security: []
      responses:
        200:
          description: "Standard PlatPhorm response"
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/PlatPhormResponse"
  /api/v1/events:
    get:
      summary: "Versioned event capability metadata."
      description: "Versioned event capability metadata. Boundary: public-safe."
      security: []
      responses:
        200:
          description: "Standard PlatPhorm response"
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/PlatPhormResponse"
    post:
      summary: "Bounded event validation scaffold; future protected sync."
      description: "Bounded event validation scaffold; future protected sync. Boundary: future protected PLATPHORM_API_KEY when enabled."
      security:
        - 
          PlatPhormApiKey: []
      responses:
        200:
          description: "Standard PlatPhorm response"
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/PlatPhormResponse"
  /api/webhooks:
    post:
      summary: "Webhook validation scaffold."
      description: "Webhook validation scaffold. Boundary: future protected PLATPHORM_API_KEY when enabled."
      security:
        - 
          PlatPhormApiKey: []
      responses:
        200:
          description: "Standard PlatPhorm response"
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/PlatPhormResponse"
  /api/v1/webhooks:
    post:
      summary: "Versioned webhook validation scaffold."
      description: "Versioned webhook validation scaffold. Boundary: future protected PLATPHORM_API_KEY when enabled."
      security:
        - 
          PlatPhormApiKey: []
      responses:
        200:
          description: "Standard PlatPhorm response"
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/PlatPhormResponse"
  /api/v1/webhooks/status:
    get:
      summary: "Webhook degraded status."
      description: "Webhook degraded status. Boundary: public-safe."
      security: []
      responses:
        200:
          description: "Standard PlatPhorm response"
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/PlatPhormResponse"
  /api/v1/integrations/games:
    get:
      summary: "Games/BBS integration status."
      description: "Games/BBS integration status. Boundary: public-safe."
      security: []
      responses:
        200:
          description: "Standard PlatPhorm response"
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/PlatPhormResponse"
  /api/v1/integrations/status:
    get:
      summary: "Cross-site integration status."
      description: "Cross-site integration status. Boundary: public-safe."
      security: []
      responses:
        200:
          description: "Standard PlatPhorm response"
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/PlatPhormResponse"
  /api/mcp:
    get:
      summary: "MCP metadata and usage."
      description: "MCP metadata and usage. Boundary: public-safe."
      security: []
      responses:
        200:
          description: "Standard PlatPhorm response"
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/PlatPhormResponse"
    post:
      summary: "JSON-RPC 2.0 MCP endpoint."
      description: "JSON-RPC 2.0 MCP endpoint. Boundary: future protected PLATPHORM_API_KEY when enabled."
      security:
        - 
          PlatPhormApiKey: []
      responses:
        200:
          description: "Standard PlatPhorm response"
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/PlatPhormResponse"
  /api/cron/refresh:
    get:
      summary: "Bounded refresh preview/status."
      description: "Bounded refresh preview/status. Boundary: future protected PLATPHORM_API_KEY when enabled."
      security:
        - 
          PlatPhormApiKey: []
      responses:
        200:
          description: "Standard PlatPhorm response"
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/PlatPhormResponse"
    post:
      summary: "Bounded refresh job."
      description: "Bounded refresh job. Boundary: future protected PLATPHORM_API_KEY when enabled."
      security:
        - 
          PlatPhormApiKey: []
      responses:
        200:
          description: "Standard PlatPhorm response"
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/PlatPhormResponse"
components:
  securitySchemes:
    PlatPhormApiKey:
      type: apiKey
      in: header
      name: X-PlatPhorm-API-Key
      description: "Future protected backend actions accept PLATPHORM_API_KEY via Authorization: Bearer or X-PlatPhorm-API-Key when enforcement is enabled."
  schemas:
    PlatPhormResponse:
      type: object
      properties:
        ok:
          type: boolean
        data:
          type: object
        error:
          type: object
          properties:
            code:
              type: string
            message:
              type: string
            details:
              type: object
    GameRules:
      type: object
      properties:
        routeMiles:
          type: number
          const: 360
        speedMph:
          type: number
          const: 45
        canonicalTripSeconds:
          type: number
          const: 28800
        noPause:
          type: boolean
          const: true
        driftLeft:
          type: boolean
          const: true
    CharityLink:
      type: object
      description: "Official external charity link. This site does not process donations."
      examples:
        - 
          name: "Desert Bus for Hope"
          url: https://desertbus.org/
          donationHandling: "Outbound only. This site does not process or route donations."
        - 
          name: "Childs Play Charity"
          url: https://childsplaycharity.org/
          donationHandling: "Outbound only. This site does not process or route donations."
        - 
          name: "Support Childs Play"
          url: https://childsplaycharity.org/get-involved
          donationHandling: "Outbound only. Support actions happen on Childs Play systems, not PlatPhormNews."
x-platphorm-auth-policy:
  publicSafeByDefault: true
  enforcementEnv: PLATPHORM_REQUIRE_API_KEY
  keyEnv: PLATPHORM_API_KEY
  acceptedHeaders:
    - "Authorization: Bearer $PLATPHORM_API_KEY"
    - "X-PlatPhorm-API-Key: $PLATPHORM_API_KEY"
  neverStore: "PLATPHORM_API_KEY is never stored in browser storage, scores, local runs, traces, logs, RSS, sitemap, OpenAPI examples, or public discovery files."
x-unofficial-tribute: "Unofficial fan tribute. Not affiliated with Penn & Teller, Absolute Entertainment, LoadingReadyRun, Desert Bus for Hope, or Childs Play."
