PlyMove

Documentation

Docs version 2026-08-storyboard-v2.1. Contracts match the deployed Core service.

Getting started

  1. Request API access and receive a pm_live_… key.
  2. Set PLYMOVE_API_KEY and call POST /v1/analyses/position.
  3. Expect JSON with schema: plymove/explain-position-v1 in under a few minutes on a warm service.

Base URL: https://api.plymove.com

Authentication

  • Authorization: Bearer <api_key>
  • or X-API-Key: <api_key>
  • Agent gateway path uses signed X-Payment-Context (set by the gateway - not by public clients talking to Core directly).

REST API

MethodPathModeBody (required)
POST/v2/storyboard/gamesyncpgn, target_elo; optional max_moments, include_rendered_story, engine_depth
POST/v1/analyses/positionsyncfen, target_elo (400-3500)
POST/v1/analyses/gameasync (legacy v1)pgn, target_elo; optional output_format, verbosity (minimal | standard | detailed)
POST/v1/analyses/teaching-momentsasync (legacy v1)pgn, target_elo; optional verbosity (minimal | standard | detailed)
POST/v1/analyses/comparesyncfen, moves (SAN[]), target_elo
POST/v1/analyses/what-ifsyncalternative_move_san, target_elo; pgn or analysis_id; anchor_ply or move_label
GET/v1/jobs/{job_id}n/aJob status
GET/v1/analyses/{analysis_id}n/aResult payload
GET/v1/analyses/{analysis_id}/annotated.pgnn/aAnnotated PGN file

Optional on most bodies: opponent_elo, engine_depth (4-24, default 16),idempotency_key, client_metadata. Game endpoints also accept verbosity (default standard): controls how many teaching moments are selected — not the model threshold.

MCP

Endpoint: https://mcp.plymove.com/mcp (Streamable HTTP, first-party Cloudflare). Primary whole-game tool: build_game_storyboard (sync storyboard v2). Also: explain_position, compare_moves, analyze_what_if (sync what-if branches). Legacy aliases explain_game and find_teaching_moments route to the same storyboard flow. ChatGPT Apps SDK adapter: https://chatgpt.plymove.com/mcp (same six tools; prepaid server-side key).

  • API key: Authorization: Bearer <key> - no 402; usage on the org rail.
  • Agent-native: no key → HTTP 402 → x402 → retry. Invalid keys return 401 (never x402).

Agent payments

MCP x402 and HTTP agent gateway (https://agent.plymove.com) share the same Core signed payment context onBase mainnet. Unpaid → 402 → pay → retry → result. Replays are idempotent (Neon payment cache; no duplicate usage).

x402 is priced at 1.5× prepaid unit economics. See Pricing.

Operations

  • build_game_storyboard - sync Elo-aware game storyboard (POST /v2/storyboard/game)
  • explain_position - sync teaching explanation for a FEN
  • compare_moves - sync learner-relative move comparison
  • analyze_what_if - sync user-requested alternative at a decision point (legal RAV PGN, eval vs played move, Maia); reuse analysis_id from storyboard
  • explain_game / find_teaching_moments - legacy MCP aliases → storyboard v2 (optional verbosity controls chapter count)

Storyboard max_moments or legacy verbosity: minimal (~3 chapters), standard (~5, default), detailed (~8).

Async jobs (legacy v1)

v1 game analysis remains on REST for backward compatibility. Prefer storyboard v2 for new integrations.

  1. Submit game or teaching-moments → { job_id, analysis_id, status: "queued", request_id }
  2. Poll GET /v1/jobs/{job_id} until status is succeeded or failed
  3. Retrieve GET /v1/analyses/{analysis_id} for structured_result

Status values: queued | running | succeeded | failed.

Errors

Shape: { "error": { "code", "message", "request_id?", "details?" } }

Stable codes: INVALID_PGN, INVALID_FEN, INVALID_MOVES,UNSUPPORTED_ELO, ENGINE_UNAVAILABLE, ANALYSIS_TIMEOUT,QUOTA_DENIED, PAYMENT_DENIED, NOT_FOUND, CONFLICT,INTERNAL_ERROR.

Rate limits

No public HTTP rate-limit headers are documented yet. Practical limits include max PGN size and analysis time budgets on the service. Contact us for volume needs.

Idempotency

Pass idempotency_key in the JSON body (not a header). Uniqueness is per(organization, idempotency_key, operation). Retries return the same analysis/job instead of enqueueing duplicate work. Agent payments additionally cache by payment_reference.

Annotated PGN output

Game analysis can return annotated PGN (output_format: "annotated_pgn" default). Fetch viaGET /v1/analyses/{id}/annotated.pgn (application/x-chess-pgn).

Examples

See Developers for curl and Python. Health check:

curl https://api.plymove.com/health