openapi.yaml

openapi: "3.0.3"
info:
  title: ChessTB Explorer API
  version: "1.0.0"
  description: |
    Chess endgame tablebase probe API.
    Submit a FEN position and receive ranked move lists for Distance to Zeroing (DTZ),
    Distance to Conversion (DTC), Distance to Mate (DTM), and DTM under the 50-move rule (DTM50).

paths:
  /probe:
    post:
      operationId: probePosition
      summary: Probe a chess position (buffered response)
      parameters:
        - $ref: "#/components/parameters/XPrefetch"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ProbeRequest"
            example:
              fen: "4k3/8/8/8/8/8/8/4K2R w - - 0 1"
      responses:
        "200":
          description: Successful probe
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ProbeResponse"
        "400":
          description: Invalid FEN, empty body, or missing tablebase coverage
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "413":
          description: Request body exceeds 4 KB limit
        "429":
          description: >-
            Rate limit exceeded -- PROBE_RATE_LIMIT per client IP, or the
            separate, tighter PREFETCH_RATE_LIMIT when the request carries
            "X-Prefetch: 1" (see that parameter above). Retrying after a
            short wait should succeed.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "502":
          description: >-
            Remote (URL) tablebase entries only: the tablebase's HTTP
            source couldn't be reached for this probe. Retrying may
            succeed.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "503":
          description: >-
            Two distinct causes, both with this status code: (1) tablebase
            not initialised (TABLEBASE_PATH failed to open) - no
            error_code is set on the response body in this case; (2) an
            in-flight probe of this (variant, FEN) pair by another
            concurrent request didn't finish within PROBE_TIMEOUT_SECS
            (error_code=probe_timeout). Retrying may succeed for case (2).
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "500":
          description: Internal server error

  /probe/stream:
    post:
      operationId: probePositionStream
      summary: Probe a chess position with SSE streaming progress
      description: |
        Identical to /probe but returns text/event-stream.
        Each SSE event has a JSON payload in its data field.
        Events are emitted as child positions are probed, followed by the
        final result or an error event. An error event with
        error_code=probe_timeout means a concurrent request was already
        probing the same (variant, FEN) pair and didn't finish in time;
        retrying is usually cheap and likely to resolve.
      parameters:
        - $ref: "#/components/parameters/XPrefetch"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ProbeRequest"
      responses:
        "200":
          description: SSE stream
          content:
            text/event-stream:
              schema:
                oneOf:
                  - $ref: "#/components/schemas/ProgressEvent"
                  - $ref: "#/components/schemas/DoneEvent"
                  - $ref: "#/components/schemas/ErrorEvent"
        "400":
          description: >-
            Invalid request body, returned before the stream opens: missing
            or non-string FEN, empty FEN, FEN over 100 characters, or
            unsupported variant. An invalid board or a position outside
            tablebase coverage is reported as an error event on the stream.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "429":
          description: >-
            Rate limit exceeded, returned before the stream opens --
            PROBE_RATE_LIMIT per client IP, or the separate, tighter
            PREFETCH_RATE_LIMIT when the request carries "X-Prefetch: 1"
            (see that parameter above; this is the endpoint the
            frontend's hover-prefetch actually sets it on). Retrying
            after a short wait should succeed.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"

  /health:
    get:
      operationId: healthCheck
      summary: Tablebase readiness check
      responses:
        "200":
          description: Tablebase loaded and ready
        "503":
          description: Tablebase not initialised

  /admin/cache/stats:
    get:
      operationId: cacheStats
      summary: LRU cache hit-rate statistics
      security:
        - adminBearer: []
        - adminSession: []
      responses:
        "200":
          description: Cache statistics
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CacheStatsResponse"
        "401":
          description: Admin authentication required
        "503":
          description: Admin panel disabled (ADMIN_TOKEN not configured)

  /admin/cache/clear:
    post:
      operationId: cacheClear
      summary: Purge both in-process LRU caches, and the tablebase's own block cache if supported
      security:
        - adminBearer: []
        - adminSession: []
      responses:
        "200":
          description: Caches cleared
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CacheClearResponse"
        "401":
          description: Admin authentication required
        "503":
          description: Admin panel disabled (ADMIN_TOKEN not configured)

  /admin/login:
    post:
      operationId: adminLogin
      summary: Start an admin session
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [token]
              properties:
                token:
                  type: string
                  description: Value of ADMIN_TOKEN (config.py's "Admin" section)
      responses:
        "200":
          description: Session started; response sets the admin session cookie
        "401":
          description: Incorrect token
        "429":
          description: >-
            Rate limit exceeded (ADMIN_LOGIN_RATE_LIMIT, per client IP).
            Retrying after a short wait should succeed.
        "503":
          description: Admin panel disabled (ADMIN_TOKEN not configured)

  /admin/logout:
    post:
      operationId: adminLogout
      summary: End the admin session
      responses:
        "200":
          description: Session ended

components:
  securitySchemes:
    adminBearer:
      type: http
      scheme: bearer
      description: "Authorization: Bearer <ADMIN_TOKEN>"
    adminSession:
      type: apiKey
      in: cookie
      name: session
      description: Session cookie set by a successful POST /admin/login
  parameters:
    XPrefetch:
      name: X-Prefetch
      in: header
      required: false
      schema:
        type: string
        enum: ["1"]
      description: >-
        Set to "1" by the frontend's hover-prefetch (frontend/src/engine/tablebase.js)
        to route this request to PREFETCH_RATE_LIMIT instead of
        PROBE_RATE_LIMIT -- a separate, tighter per-client-IP budget, never
        an exemption from rate limiting (see app.py's _request_probe_limit).
        A real, user-initiated probe should not set this header.
  schemas:
    ProbeRequest:
      type: object
      required: [fen]
      properties:
        fen:
          type: string
          description: >-
            FEN notation (4–6 fields; shorter forms are auto-padded). The
            castling-availability field accepts standard KQkq letters (in
            that order) for variant="standard", or additionally
            Shredder-FEN/X-FEN rook-file letters (e.g. "A", "Ha") for
            variant="chess960". Either way, a letter naming a right with
            no matching king and rook on the board is rejected with a 400
            response. A right that does have one is accepted and probed
            (see TABLEBASE_PATH in the project README). A FEN
            longer than 100 characters is rejected with a 400 response.
          example: "4k3/8/8/8/8/8/8/4K2R w - - 0 1"
        variant:
          type: string
          enum: ["standard", "chess960"]
          default: "standard"
          description: >-
            The rules variant "fen" is interpreted under. Never inferred
            from the FEN itself - the orthodox starting array is itself a
            legal Chess960 starting position, so the same FEN text is
            genuinely ambiguous without this field. Omitted or absent
            defaults to "standard". Board geometry,
            piece movement, and tablebase material selection are
            identical between the two variants - only the interpretation
            of castling rights/moves differs.
          example: "standard"

    MoveEntry:
      type: object
      properties:
        san:
          type: string
          description: Standard Algebraic Notation of the move
        plies:
          type: integer
          description: >-
            Distance in plies. 1 for a move that delivers immediate
            checkmate (the move itself is the mate); 0 for a move that
            ends the game immediately as a draw (stalemate or insufficient
            material), for an unprobed/unknown move, or when available is
            false.
        order:
          type: integer
          description: >-
            DTC only: pawn pushes still owed before this move's line
            reaches its next capture or promotion (see chess.chesstb's
            probe_dtc/ProbeResult docs). Always 0 for dtz/dtm/dtm50
            entries. 0 for a DTC entry when the move itself is a capture
            or a promotion, or when it ends the game outright (checkmate
            or an immediate draw) - nothing more is owed once the game is
            decided or the conversion has already happened. A quiet pawn
            push does not settle the count: it only pays down one of the
            pushes still owed.
        is_mate:
          type: boolean
          description: True if this move delivers immediate checkmate
        outcome:
          type: string
          enum: [win, cursed_win, draw, blessed_loss, loss, unknown, not_available]
        available:
          type: boolean
          description: >-
            False when this material's tablebase has no table for this
            entry's metric (DTZ, DTC, DTM, or DTM50 - WDL is always
            available), in which case outcome is flatly not_available and
            plies/order are 0. No metric's row ever derives its answer
            from another metric.
        child_fen:
          type: string
          nullable: true
          description: FEN of the position after this move; null for terminal positions
        draw_reason:
          type: string
          nullable: true
          enum: [stalemate, insufficient_material, null]
          description: Reason for a draw outcome that ends the game immediately; null otherwise
        rounded:
          type: boolean
          description: >-
            Present on available moves_dtz entries only. True when plies may
            still be one ply off after cross-checking the moves against the
            position's dtz. False for zeroing moves, whose plies is exactly 1,
            and for moves whose value the cross-check determined.

    Summary:
      type: object
      description: >-
        Outcome distribution across all legal moves under the 50-move rule,
        using each resulting position's halfmove clock. Outcomes use DTM50
        when available, otherwise DTC (including DTZ-derived DTC for pawnless
        material). Clock-independent draws, cursed wins and blessed losses
        count as draws. A move whose clock-aware outcome cannot be resolved
        counts as unknown, including failed child probes.
      properties:
        wins:    {type: integer}
        draws:   {type: integer}
        losses:  {type: integer}
        unknown: {type: integer}

    ProbeResponse:
      type: object
      properties:
        wdl:
          type: integer
          enum: [-2, -1, 0, 1, 2]
          description: Root position WDL (2=win, 1=cursed win, 0=draw, -1=blessed loss, -2=loss)
        dtz:
          type: integer
          nullable: true
          description: >-
            Distance to Zeroing (DTZ) in plies; null when
            dtz_available is false
        dtz_available:
          type: boolean
          description: False when this material's tablebase has no DTZ table
        dtz_rounded:
          type: boolean
          nullable: true
          description: >-
            True when dtz may still be one ply off after the moves have been
            cross-checked against it. Only cursed wins and blessed losses can
            be rounded. Null when dtz_available is false.
        dtc:
          type: array
          items:
            type: integer
            nullable: true
          minItems: 3
          maxItems: 3
          description: >-
            [wdl_under_dtc, pawn_pushes_still_owed, plies_to_next_conversion]:
            Distance to Conversion (DTC), the chess.chesstb probe_dtc() pair
            (pawn pushes still owed, signed plies) preceded by the wdl
            class; [null, null, null] when dtc_available is false. DTC is
            always rule50-aware (probed at the position's own halfmove
            clock, like DTM50), so wdl_under_dtc can differ from the root
            wdl above the same way dtm50's own wdl can.
        dtc_available:
          type: boolean
          description: >-
            False when this material's tablebase has no DTC table. A
            .lzdtc table only exists for material with at least one pawn;
            chess.chesstb derives an equivalent DTC answer from DTZ/WDL for
            pawnless material instead, so this is False in practice only
            when a pawnful material's own DTC table hasn't been generated.
        dtm:
          type: integer
          nullable: true
          description: Distance to Mate in plies; null when dtm_available is false
        dtm_available:
          type: boolean
          description: False when this material's tablebase has no DTM table
        dtm50:
          type: array
          items:
            type: integer
            nullable: true
          minItems: 2
          maxItems: 2
          description: >-
            [wdl_under_50move_rule, plies_to_mate_under_50move_rule];
            [null, null] when dtm50_available is false
        dtm50_available:
          type: boolean
          description: False when this material's tablebase has no DTM50 table
        draw_reason:
          type: string
          nullable: true
          enum: [stalemate, insufficient_material, null]
          description: Reason the root position itself is an immediate draw; null otherwise
        moves_dtz:
          type: array
          items:
            $ref: "#/components/schemas/MoveEntry"
          description: >-
            All legal moves ranked by Distance to Zeroing (best first). A
            quiet move that gives up castling rights into a cursed win or
            blessed loss takes its plies from chess.chesstb's cursed-exit
            rule: one or two more than the resulting position's dtz. A
            rounded value is exact whenever the position's dtz and the other
            moves leave a single possibility.
        moves_dtc:
          type: array
          items:
            $ref: "#/components/schemas/MoveEntry"
          description: >-
            All legal moves ranked by Distance to Conversion (best first);
            ranked by pawn pushes still owed first, then plies (DTC's own
            notion of a better line - see MoveEntry.order)
        moves_dtm:
          type: array
          items:
            $ref: "#/components/schemas/MoveEntry"
          description: All legal moves ranked by Distance to Mate (best first)
        moves_dtm50:
          type: array
          items:
            $ref: "#/components/schemas/MoveEntry"
          description: All legal moves ranked by DTM under the 50-move rule (best first)
        summary:
          $ref: "#/components/schemas/Summary"

    ErrorResponse:
      type: object
      properties:
        error:
          type: string
          description: Human-readable error message
        error_code:
          type: string
          enum: [missing_table, remote_unavailable, probe_timeout]
          description: >-
            Machine-readable error code (only present for specific errors).
            remote_unavailable only occurs with a remote (URL)
            TABLEBASE_PATH, when its HTTP source couldn't be reached.
            probe_timeout means a concurrent request was already probing
            this same FEN and didn't finish within PROBE_TIMEOUT_SECS;
            retrying is generally cheap and likely to succeed, since the
            original probe has usually finished and been cached by then.
        piece_count:
          type: integer
          nullable: true
          description: Number of pieces on the board (only when error_code=missing_table)

    ProgressEvent:
      type: object
      properties:
        status: {type: string, enum: [probing]}
        completed: {type: integer}
        total: {type: integer}

    DoneEvent:
      allOf:
        - $ref: "#/components/schemas/ProbeResponse"
        - type: object
          properties:
            status: {type: string, enum: [done]}

    ErrorEvent:
      type: object
      properties:
        status: {type: string, enum: [error]}
        error: {type: string}
        error_code: {type: string, enum: [missing_table, remote_unavailable, probe_timeout]}
        piece_count: {type: integer, nullable: true}

    CacheStatsResponse:
      type: object
      description: >-
        Point-in-time hit-rate counters for both in-process LRUs, plus the
        static config and tablebase tier info they're sized against.
      properties:
        evaluate_fen_cache:
          $ref: "#/components/schemas/CacheCounters"
        probe_fen_cache:
          $ref: "#/components/schemas/CacheCounters"
        config:
          type: object
          properties:
            evaluate_cache_size: {type: integer}
            probe_cache_size: {type: integer}
            block_cache_bytes: {type: integer}
        tablebase:
          type: object
          description: Whether the ordered source resolver is configured.
          properties:
            configured: {type: boolean}
        thread_pool:
          type: object
          properties:
            max_workers: {type: integer}
            parallel_threshold: {type: integer}
            probe_timeout_secs: {type: number}
        tablebase_cache:
          type: object
          description: >-
            Per-source cache statistics: block_cache plus one entry
            named source containing the resolver's own cache statistics.
            Omitted when nothing reports statistics.
          additionalProperties: true

    CacheCounters:
      type: object
      properties:
        currsize: {type: integer}
        maxsize: {type: integer}
        hits: {type: integer}
        misses: {type: integer}
        hit_rate: {type: number}

    CacheClearResponse:
      type: object
      properties:
        status: {type: string, enum: [ok]}
        message: {type: string}
        evaluate_fen_cache:
          $ref: "#/components/schemas/CacheCounters"
        probe_fen_cache:
          $ref: "#/components/schemas/CacheCounters"
        tablebase_internal_cache_cleared:
          type: boolean
          description: >-
            Whether the underlying chess.chesstb block cache was also
            cleared, not just this app's own two LRUs above.
        tablebase_cache:
          type: object
          description: >-
            Per-source cache statistics: block_cache plus one entry
            named source containing the resolver's own cache statistics.
            Omitted when nothing reports statistics.
          additionalProperties: true