PlyMove

Documentation

Docs version 2026-08. 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://plymove-api-production.up.railway.app

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/v1/analyses/positionsyncfen, target_elo (400–3500)
POST/v1/analyses/gameasyncpgn, target_elo; optional output_format
POST/v1/analyses/teaching-momentsasyncpgn, target_elo
POST/v1/analyses/comparesyncfen, moves (SAN[]), target_elo
GET/v1/jobs/{job_id}—Job status
GET/v1/analyses/{analysis_id}—Result payload
GET/v1/analyses/{analysis_id}/annotated.pgn—Annotated PGN file

Optional on most bodies: opponent_elo, engine_depth (4–24, default 16),idempotency_key, client_metadata.

MCP

Tools: explain_game, find_teaching_moments, explain_position, compare_moves.

Configure PUBLIC_MCP_URL to your Alpic /mcp URL before launch copy goes live. Do not assume mcp.plymove.com until DNS resolves.

Agent payments

Staging gateway: https://plymove-agent-gateway.round-cloud-7d27.workers.dev. Flow: unpaid request → HTTP 402 → pay (x402) → retry with payment header → result. Replays of the same payment are idempotent on Core (cached result; no duplicate usage).

Testnet pricing on the gateway is not commercial pricing. See Pricing for commercial models. Deep wallet setup is operator documentation, not required on this public page.

Operations

  • explain_position — sync teaching explanation for a FEN
  • compare_moves — sync learner-relative move comparison
  • find_teaching_moments — async ranked moments from a PGN
  • explain_game — async full-game teaching analysis / annotated PGN

Async jobs

  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://plymove-api-production.up.railway.app/health