v2

latestOpenAPI 3.1.0Proprietary2026-07-2622331.9 KB

Analysis

Analyze a chess position

Analyze a chess position with Stockfish + coaching response.

Main use cases:

Live game analysis - Get best move suggestions during games
Board evaluation - Show position assessment to users
Q&A bot - Answer user questions about positions

What you get:

Stockfish evaluation in centipawns
Best move recommendation
Categorical position assessment (equal, slight advantage, winning, etc.)
Natural language coaching response

Response fields: response, fen, best_move, best_move_uci, evaluation, assessment

Example request:

{
  "position": "rnbqkbnr/pppppppp/8/8/4P3/8/PPPP1PPP/RNBQKBNR b KQkq e3 0 1",
  "question": "What should I play?",
  "skill_level": "intermediate"
}

post/analyze_position

Request body

positionstring required

Position in FEN notation or PGN moves

questionstring nullable

User's question about the position

personalitystring

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

last_movestring nullable

Last move played in SAN notation (for tactical context)

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

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

include_stockfishboolean

Run Stockfish engine analysis

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 — values below 256 truncate coaching mid-sentence because the model's internal reasoning consumes part of the budget.

Example request

{
  "position": "rnbqkbnr/pppppppp/8/8/4P3/8/PPPP1PPP/RNBQKBNR b KQkq e3 0 1",
  "question": "What should I play here?",
  "last_move": "Nf3",
  "reasoning_effort": "low",
  "max_tokens": 300
}

Response

Position analysis with coaching. Evaluation is integer centipawns (White's perspective); forced mate uses the ±10000 sentinel.

responsestring required

Natural-language coaching for the position: the best plan and why it works.

fenstring required

The analysed position in Forsyth-Edwards Notation (echoed from the request).

best_movestring nullable

Best move in Standard Algebraic Notation (e.g. 'Nxe5'). Null when the position is terminal (checkmate/stalemate).

best_move_ucistring nullable

Best move in UCI coordinate notation (e.g. 'f3e5'), for drawing arrows on a board. Null on terminal positions.

evaluationinteger nullable

Position evaluation in centipawns from White's perspective (positive favours White). A forced mate returns the sentinel +10000 or -10000 (no numeric mate distance). Null on terminal positions.

assessmentstring required

Categorical read of the evaluation: one of equal, slight_white, slight_black, winning_white, winning_black, decisive_white, decisive_black, or unknown.

Example response

{
  "assessment": "slight_white",
  "best_move": "Nxe5",
  "best_move_uci": "f3e5",
  "evaluation": 41,
  "fen": "rnbqkb1r/pppp1ppp/5n2/4p3/4P3/5N2/PPPP1PPP/RNBQKB1R w KQkq - 2 3",
  "response": "The position is roughly equal. Capturing with Nxe5 challenges Black immediately while keeping development on track."
}