openapi: 3.2.0
info:
  title: Chessigma Public Game 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: Game
paths:
  /game:
    post:
      operationId: submitGame
      summary: Submit a game (PGN) for analysis
      description: Stores a chess game and returns a URL to view and analyze it on Chessigma. Duplicate games (same players + date) are deduplicated and return the existing gameId.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GameSubmission'
            example:
              pgn: '[White "Alice"]

                [Black "Bob"]

                [Result "1-0"]


                1. e4 e5 2. Nf3 Nc6 3. Bb5 a6 1-0'
      responses:
        '201':
          description: Game submitted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GameSubmissionResponse'
              example:
                gameId: f222a278-3ed5-46c5-bd14-d0af7fa92e3d
                url: https://www.chessigma.com/games/f222a278-3ed5-46c5-bd14-d0af7fa92e3d
                status: submitted
                message: Successfully saved 1 game
        '400':
          description: Invalid or missing PGN, or missing required tags
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: Rate limit exceeded (30 req/min global)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      tags:
      - Game
  /game/{gameId}:
    get:
      operationId: getGame
      summary: Retrieve analysis for a submitted game
      description: Returns game metadata and analysis. Because analysis runs client-side, this returns data only if a user has already opened the game page and triggered analysis. Only games submitted via this public API are readable here.
      parameters:
      - name: gameId
        in: path
        required: true
        description: UUID returned by POST /game.
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: Game analysis
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GameAnalysisResponse'
        '400':
          description: Invalid game ID format (must be a UUID)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Game exists but was not submitted via the public API
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Game not found or analysis not yet available
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: Rate limit exceeded
        '500':
          description: Internal server error
      tags:
      - Game
components:
  schemas:
    GameSubmission:
      type: object
      required:
      - pgn
      additionalProperties: false
      properties:
        pgn:
          type: string
          minLength: 1
          maxLength: 10000
          description: PGN text. Must include [White], [Black], [Result] tags and a valid moves section.
    GameAnalysisResponse:
      type: object
      properties:
        gameId:
          type: string
          format: uuid
        status:
          type: string
          enum:
          - completed
        analysis:
          type: object
          properties:
            game:
              $ref: '#/components/schemas/Game'
        metadata:
          type: object
          properties:
            analysisCompletedAt:
              type: string
              format: date-time
            version:
              type: string
    Error:
      type: object
      properties:
        error:
          type: string
        details:
          description: Optional validation detail.
      required:
      - error
    Game:
      type: object
      properties:
        id:
          type: string
        pgn:
          type: string
        white_username:
          type:
          - string
          - 'null'
        black_username:
          type:
          - string
          - 'null'
        white_rating:
          type:
          - integer
          - 'null'
        black_rating:
          type:
          - integer
          - 'null'
        white_result:
          type:
          - string
          - 'null'
        black_result:
          type:
          - string
          - 'null'
        time_class:
          type:
          - string
          - 'null'
        time_control:
          type:
          - string
          - 'null'
        source:
          type: string
    GameSubmissionResponse:
      type: object
      properties:
        gameId:
          type: string
          format: uuid
        url:
          type: string
          format: uri
          description: Open this to view and analyze the game.
        status:
          type: string
          enum:
          - submitted
        message:
          type: string