openapi: 3.1.0
info:
  title: Escapers Agent Public API
  version: 1.0.0
  summary: Public agent interface for Escapers MVP
servers:
  - url: https://ws.escapers.app
paths:
  /api/public/game-info:
    get:
      operationId: getGameInfo
      summary: Get canonical Escapers game facts.
      responses:
        "200":
          description: Game facts, mechanics, public links, and API status.
        "503":
          description: agentApiEnabled is disabled.
  /api/public/daily:
    get:
      operationId: getDailyChallenge
      summary: Get the public daily challenge without correct answers.
      parameters:
        - name: day
          in: query
          required: false
          schema:
            type: string
            pattern: "^\\d{4}-\\d{2}-\\d{2}$"
      responses:
        "200":
          description: Daily challenge question set. correct_index is not returned.
        "503":
          description: agentApiEnabled is disabled.
  /api/public/rooms:
    post:
      operationId: createRoom
      summary: Create a free Escapers room.
      description: Returns a join URL tagged with room_source=agent_api and join_source=agent_api. The 6th request per hour from the same IP/client returns 429.
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              properties:
                campaign_id:
                  type: string
                channel:
                  type: string
                landing_page:
                  type: string
                website:
                  type: string
                  description: Honeypot field. Leave empty.
      responses:
        "200":
          description: Room created.
        "400":
          description: Honeypot or malformed request rejected.
        "429":
          description: agent_api_create_room rate limit exceeded.
        "503":
          description: agentApiEnabled or roomsEnabled is disabled.
  /mcp:
    post:
      operationId: mcpJsonRpc
      summary: MCP JSON-RPC endpoint.
      description: Supports initialize, tools/list, and tools/call for get_game_info, get_daily_challenge, and create_room.
      responses:
        "200":
          description: JSON-RPC response.
components:
  schemas:
    PublicDailyQuestion:
      type: object
      not:
        required: [correct_index]
