openapi: 3.2.0
info:
  title: Chessigma Public Daily Puzzle API
  version: 1.0.0
  description: 'Free, no-auth API for the Chessigma chess analysis platform. Submit games (PGN) for analysis, read analysis results, compute Elo rating changes, and fetch the daily puzzle. Chess engine analysis runs client-side in the browser (Stockfish WebAssembly), so this API is compute-free: GET /game/{gameId} returns analysis only after a user has opened the game page and triggered it. No signup, no API key, no paywall. Global rate limit: 30 requests/minute across all callers.'
  contact:
    name: Chessigma
    url: https://www.chessigma.com/developers
  license:
    name: Terms of Service
    url: https://www.chessigma.com/tos
servers:
- url: https://www.chessigma.com/public-api/v1
  description: Production
security: []
tags:
- name: Daily Puzzle
paths:
  /daily-puzzle:
    get:
      operationId: getDailyPuzzle
      summary: Get the daily chess puzzle
      description: Returns the single daily puzzle for today, or a past date via ?date=YYYY-MM-DD. Returns exactly one puzzle — the full puzzle database is not exposed.
      parameters:
      - name: date
        in: query
        required: false
        description: Past date in YYYY-MM-DD format. Defaults to today. Future dates are rejected.
        schema:
          type: string
          pattern: ^\d{4}-\d{2}-\d{2}$
      responses:
        '200':
          description: The daily puzzle
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DailyPuzzle'
              example:
                date: '2026-05-23'
                puzzleId: abcde
                fen: r1bqkbnr/pppp1ppp/2n5/4p3/2B1P3/5N2/PPPP1PPP/RNBQK2R b KQkq - 3 3
                sideToMove: black
                rating: 1523
                themes:
                - fork
                - middlegame
                solution:
                - d7d5
                - e4d5
                gameUrl: https://lichess.org/abc123
        '400':
          description: Invalid date parameter
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: Rate limit exceeded
        '500':
          description: Internal server error
      tags:
      - Daily Puzzle
components:
  schemas:
    DailyPuzzle:
      type: object
      properties:
        date:
          type: string
          pattern: ^\d{4}-\d{2}-\d{2}$
        puzzleId:
          type: string
        fen:
          type: string
          description: Position in FEN notation.
        sideToMove:
          type: string
          enum:
          - white
          - black
        rating:
          type: integer
        themes:
          type: array
          items:
            type: string
        solution:
          type: array
          items:
            type: string
          description: Moves in UCI notation; first move sets up the puzzle.
        gameUrl:
          type:
          - string
          - 'null'
          format: uri
    Error:
      type: object
      properties:
        error:
          type: string
        details:
          description: Optional validation detail.
      required:
      - error