openapi: 3.1.0
info:
  title: PlatPhorm Vanlife API
  version: 1.0.0
  description: Public Vanlife resources, events, honest sensor state, protected road updates, and a read-only MCP server.
servers:
  - url: https://vanlife.platphormnews.com
components:
  securitySchemes:
    PlatPhormBearer:
      type: http
      scheme: bearer
    PlatPhormApiKey:
      type: apiKey
      in: header
      name: X-PlatPhorm-API-Key
paths:
  /api/health:
    get:
      summary: Get public service health
      responses:
        "200": { description: Health response }
  /api/v1/health:
    get:
      summary: Get versioned public service health
      responses:
        "200": { description: Health response }
  /api/docs:
    get:
      summary: Get API documentation
      responses:
        "200": { description: OpenAPI document }
  /api/resources:
    get:
      summary: List curated Vanlife resources
      responses:
        "200": { description: Resource catalog }
  /api/events:
    get:
      summary: List current events from PlatPhorm Calendar
      responses:
        "200": { description: Active or empty event result }
        "503": { description: Calendar degraded state }
  /api/sensors:
    get:
      summary: Get honest current or empty sensor state
      responses:
        "200": { description: Sensor state }
    post:
      summary: Update ephemeral sensor state
      security:
        - PlatPhormBearer: []
        - PlatPhormApiKey: []
      responses:
        "200": { description: Sensor state updated }
        "401": { description: Unauthorized }
        "503": { description: Platform auth is not configured }
  /api/update:
    get:
      summary: Get road update endpoint metadata
      responses:
        "200": { description: Endpoint metadata }
    post:
      summary: Create an ephemeral road update
      security:
        - PlatPhormBearer: []
        - PlatPhormApiKey: []
      responses:
        "200": { description: Update accepted by this runtime }
        "401": { description: Unauthorized }
        "503": { description: Platform auth is not configured }
  /api/chat:
    post:
      summary: Stream a Vanlife assistant response
      responses:
        "200": { description: AI SDK message stream }
  /api/mcp:
    get:
      summary: Get public Vanlife MCP metadata
      responses:
        "200": { description: MCP metadata and usage }
    post:
      summary: Call the public read-only MCP JSON-RPC server
      description: Supports initialize, ping, tools, resources, and prompts. No mutation tools are exposed.
      responses:
        "200": { description: JSON-RPC response }
        "400": { description: JSON parse error }