API Reference

Complete endpoint documentation for the ChessGrammar API v3.0.

Base URL: https://chessgrammar.com/api/v1

POST /extract

Analyze a position (FEN) or a game (PGN) for tactical patterns.

FEN Request

{
  "fen": "6k1/5p1p/4p3/4q3/3n4/2Q3P1/PP1N1P1P/6K1 b - - 3 37",
  "patterns": ["fork", "pin"]
}
  • fen (required): Valid FEN string
  • patterns (optional): Filter by pattern names. If omitted, all 10 patterns are scanned.

PGN Request

{
  "pgn": "1. e4 e5 2. Nf3 Nc6 3. Bc4 ...",
  "mode": "played",
  "patterns": ["fork", "discovered_attack"]
}
  • pgn (required): PGN string of a complete game
  • mode (optional): "played" (default) or "available"
    • played: Only tactics that were actually executed in the game
    • available: All tactical opportunities at each position
  • patterns (optional): Filter by pattern names

Response

{
  "tactics": [
    {
      "pattern": "fork",
      "color": "black",
      "key_squares": ["e2"],
      "target_squares": ["g1", "c3"],
      "targets": [
        {"square": "g1", "piece": "K", "piece_name": "king", "color": "white"},
        {"square": "c3", "piece": "Q", "piece_name": "queen", "color": "white"}
      ],
      "gain": 700,
      "gain_confirmed": true,
      "is_mate": false,
      "trigger_move": "d4e2",
      "sequence": ["d4e2", "g1g2", "e2c3", "b2c3"],
      "fen": "6k1/5p1p/..."
    }
  ],
  "count": 1,
  "performance_ms": 48.2,
  "fen": "6k1/5p1p/..."
}

PGN Response (additional fields)

Each tactic includes:

  • ply: The half-move number in the game
  • status: "played" or "existing" (mode played only)

Errors

StatusBodyCause
400"error": "Missing 'fen' or 'pgn' field"No input provided
400"error": "Invalid FEN"Malformed FEN string
400"error": "Invalid PGN"Malformed PGN
400"error": "Invalid pattern: xyz"Unknown pattern name
429"error": "Rate limit exceeded"Too many requests

GET /health

Returns service status.

{
  "status": "ok",
  "version": "3.0",
  "patterns": 10,
  "engine": "chess-tactics v2.5"
}