Sign in

v2

latestOpenAPI 3.1.0Proprietary2026-07-2622331.9 KB
Analysis

Analyze a complete chess game

Analyze a complete chess game from PGN.

What you get:

  • Move-by-move evaluation with error classification (blunder/mistake/inaccuracy)
  • Per-side phase summaries (opening/middlegame/endgame for White AND Black)
  • Mistakes separated by side with best move alternatives
  • Expandable overview bullet points and a 4-category study plan (opening/tactics/strategy/endgame)
  • Turning points with phase context
  • Natural language game narrative

Per-move data (for eval charts, board overlays, move arrows): evaluation_before, best_move_uci, fen_before, fen_after, coaching_text.

post/analyze_game

Request body

pgnstring required

Full PGN game text with moves

questionstring nullable

User's question about the game. Partner-tier contracts only — ignored on standard API keys.

personalitystring

Coaching personality: 'Coach', 'Grandmaster Chessy', 'Hustler Chessy', 'Roasty Chessy'

player_colorstring nullable

Focus analysis on this player: 'white' or 'black'

user_statsobject nullable

User context (rating, recent performance) for personalized coaching

modelstring nullable

Coaching model override. Partner-tier contracts only — ignored on standard API keys.

classify_intentboolean

Classify user's question intent for better response generation

include_all_movesboolean

Include all moves (true) or just errors (false)

detect_motifsboolean

Detect tactical motifs (forks, pins, hanging pieces)

output_format'structured' | 'narrative' | 'both'

Response format: 'structured' (JSON), 'narrative' (text), or 'both'

detail_level'brief' | 'standard' | 'detailed'

Verbosity level of response

coaching_style'encouraging' | 'direct' | 'socratic'

Coaching tone

skill_level'beginner' | 'intermediate' | 'advanced'

Player skill level for tailored explanations

include_variationsboolean

Include move variations in response

max_moves_analyzedinteger nullable

Limit number of moves analyzed (null = all moves)

languagestring

Response language code (ISO 639-1)

player_ratinginteger nullable

Player rating (e.g. 1200) for rating-adjusted explanations

include_debugboolean

Internal use — ignored on customer API keys

reasoning_effort'none' | 'minimal' | 'low' | 'medium' | 'high' nullable

Reasoning effort for LLM coaching. 'none' disables reasoning entirely (fastest). Default: 'minimal'.

max_tokensinteger nullable

Max output tokens for LLM coaching response. Clamped to 256-4000.

position_analysis_scopestring nullable

Which moves get deep positional analysis: 'key' (errors + big eval swings, default), 'none' (skip), or 'all' (every move — partner-tier contracts only).

per_move_coachingboolean

Generate LLM coaching commentary per analyzed move. Each move gets a 1-3 sentence coaching comment. Runs in parallel with narrative generation (~3% overhead).

Example request

{
  "pgn": "[Event \"Test\"]\n[Result \"1-0\"]\n\n1. e4 e5 2. Nf3 Nc6 3. Bb5 1-0",
  "question": "What were my biggest mistakes?",
  "player_color": "black",
  "max_moves_analyzed": 20,
  "reasoning_effort": "low",
  "max_tokens": 500,
  "position_analysis_scope": "key"
}

Response

Structured game review. Per-move evaluations are pawn-unit floats (White's perspective) and are null on terminal plies — distinct from /analyze_position's integer centipawns.

responsestring required

Full natural-language narrative of the game.

critical_linesobject[]

Key forcing lines worth studying, when detected.

phasesobject nullable

Per-phase summaries, when the analysis pipeline produces them.

narrativestring nullable

Legacy narrative field emitted by some analysis paths; prefer overview.narrative_text.