{"openapi":"3.1.0","info":{"title":"Notation API","version":"0.1.0","description":"A fully local, hand-curated reference for chess algebraic notation and game-recording formats: a symbol glossary, topic explainers, a plain-English example-move-sequence walkthrough, a field-by-field FEN reference, the PGN tag vocabulary, a notation-terms glossary, side-by-side format comparisons against other games' recording systems, and history notes. Not a chess engine — no move-legality validation.\n\nEvery operation is read-only or compute-only. The same tools are available over MCP (streamable HTTP) at https://notation.connectorbay.com/mcp.","contact":{"name":"Unify Dynamics LLC","email":"hr@unifydynamics.com","url":"https://connectorbay.com/notation/docs"},"termsOfService":"https://connectorbay.com/notation/terms"},"servers":[{"url":"https://notation.connectorbay.com"}],"externalDocs":{"url":"https://connectorbay.com/notation/docs"},"security":[{},{"bearer":[]}],"components":{"securitySchemes":{"bearer":{"type":"http","scheme":"bearer","description":"Optional. A Pro API key raises rate limits; no credentials are required."}},"schemas":{"Error":{"type":"object","properties":{"ok":{"const":false},"error":{"type":"object"}}}}},"paths":{"/v1/tools/symbol_glossary":{"post":{"operationId":"symbol_glossary","summary":"Defines one chess notation symbol — piece letters (K Q R B N), action marks (x, +, #, O-O, O-O-O, =),","description":"Defines one chess notation symbol — piece letters (K Q R B N), action marks (x, +, #, O-O, O-O-O, =),\n    annotation glyphs (! ? !! ?? !? ?!), result markers (1-0, 0-1, 1/2-1/2, *), and evaluation symbols\n    (±, ∓, ∞, ...) — or lists every symbol this reference covers. Use for \"what does x mean in\n    chess notation\", \"what's the difference between + and #\", \"what does O-O mean\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"symbol":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"A notation symbol or its common name to look up; omit to list every symbol.","examples":["K","x","+","#","O-O","=","!","??","1-0"],"title":"Symbol"}},"title":"symbol_glossaryArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/notation_explainer":{"post":{"operationId":"notation_explainer","summary":"A fuller, prose explanation of one broader notation topic: algebraic vs descriptive notation,","description":"A fuller, prose explanation of one broader notation topic: algebraic vs descriptive notation,\n    disambiguation rules, PGN's tag-pair-plus-movetext structure, castling/promotion/check notation, long\n    algebraic (LAN) vs standard algebraic (SAN), ICCF numeric notation, move numbering and the ellipsis for\n    Black-to-move, NAGs, reading a scoresheet, and ECO opening codes. Use for \"explain disambiguation in\n    chess notation\", \"how does PGN store a game\", \"what's long algebraic notation\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"topic":{"description":"A notation topic to explain.","examples":["algebraic vs descriptive","disambiguation","pgn structure","castling notation","promotion notation","long vs short algebraic","iccf numeric notation"],"minLength":1,"title":"Topic","type":"string"}},"required":["topic"],"title":"notation_explainerArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/parse_example":{"post":{"operationId":"parse_example","summary":"Given a short algebraic move sequence or single move you supply, walks through what each token means","description":"Given a short algebraic move sequence or single move you supply, walks through what each token means\n    in plain English: which piece moves where, why a disambiguating letter/number is there if one is\n    present, whether it's a capture, castling, promotion, check, or checkmate, and what any trailing\n    annotation (!, ?, etc.) means. This is an educational walkthrough of the notation syntax in the string\n    you give it — it does NOT validate that the position is reachable or that the move is actually legal on\n    a real board; it never checks anything against an actual game state. If given something that looks like\n    a FEN position string instead of a move sequence, it says so and points to fen_field_explainer instead.\n    Use for \"what does exd8=Q+ mean\", \"walk me through 1. e4 e5 2. Nf3 Nc6 3. Bb5\", \"what does Nbd7 mean and\n    why the b\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"notation_string":{"description":"A short, made-up algebraic move sequence or single move to walk through.","examples":["1. e4 e5 2. Nf3 Nc6 3. Bb5","exd8=Q+","O-O-O+","Nbd7","Qh4e1","12...Qxd4"],"maxLength":300,"minLength":1,"title":"Notation String","type":"string"}},"required":["notation_string"],"title":"parse_exampleArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/fen_field_explainer":{"post":{"operationId":"fen_field_explainer","summary":"Explains one of FEN's six space-separated fields (piece placement, active color, castling","description":"Explains one of FEN's six space-separated fields (piece placement, active color, castling\n    availability, en passant target square, halfmove clock, fullmove number) with an example value and\n    notes, or returns all six in order when no field is given. Use for \"what's the third field in a FEN\n    string\", \"what does the en passant field in FEN mean\", \"explain FEN field by field\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"field_name":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"A FEN field name or its 1-6 position; omit to list all six.","examples":["piece placement","active color","castling availability","en passant target","halfmove clock","fullmove number","3"],"title":"Field Name"}},"title":"fen_field_explainerArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/pgn_tag_reference":{"post":{"operationId":"pgn_tag_reference","summary":"Looks up one PGN tag pair (what it holds, whether it's part of the mandatory Seven Tag Roster, and an","description":"Looks up one PGN tag pair (what it holds, whether it's part of the mandatory Seven Tag Roster, and an\n    example) or lists every tag this reference covers, roster tags first. Use for \"what does the ECO tag\n    hold\", \"what are the seven required PGN tags\", \"how do you mark a custom starting position in PGN\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"tag_name":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"A PGN tag name to look up; omit to list the whole reference.","examples":["Event","Site","Date","Result","WhiteElo","ECO","TimeControl","FEN"],"title":"Tag Name"}},"title":"pgn_tag_referenceArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/format_comparison":{"post":{"operationId":"format_comparison","summary":"Lines up two named notation/recording systems side by side: what each records (a move, a position, or","description":"Lines up two named notation/recording systems side by side: what each records (a move, a position, or\n    a full game), its coordinate scheme, how it identifies pieces (if at all), roughly when/why it arose,\n    and whether it's human-readable and/or machine-parseable. Covers chess's own systems (algebraic,\n    descriptive, long algebraic, ICCF numeric, FEN, PGN) plus, for contrast, other games' conventions (Go\n    coordinate notation and SGF, xiangqi, shogi, draughts, backgammon, Scrabble, contract bridge). If a name\n    isn't recognized, the error lists every valid system id. Use for \"algebraic vs descriptive notation,\n    what's different\", \"how does chess notation compare to Go notation\", \"PGN vs FEN, what's the difference\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"a":{"description":"First notation system or format to compare.","examples":["algebraic","descriptive","fen","pgn","go coordinate notation"],"minLength":1,"title":"A","type":"string"},"b":{"description":"Second notation system or format to compare.","examples":["long algebraic","iccf numeric","xiangqi notation","scrabble notation","bridge notation"],"minLength":1,"title":"B","type":"string"}},"required":["a","b"],"title":"format_comparisonArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/term_glossary":{"post":{"operationId":"term_glossary","summary":"Defines general notation and game-recording vocabulary — ply, half-move, full move, SAN, LAN, FEN,","description":"Defines general notation and game-recording vocabulary — ply, half-move, full move, SAN, LAN, FEN,\n    PGN, NAG, tag pair, movetext, ECO code, scoresheet, disambiguator, rank, file, square coordinate,\n    ellipsis, underpromotion, coordinate notation, portable format — distinct from symbol_glossary's\n    in-move symbols. Use for \"what's a ply\", \"what's the difference between SAN and LAN\", \"what's a NAG\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"term":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"A specific notation/recording term to look up; omit to list all.","examples":["ply","SAN","LAN","NAG","tag pair","movetext","ECO code","disambiguator"],"title":"Term"}},"title":"term_glossaryArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/history_note":{"post":{"operationId":"history_note","summary":"Short, verified historical notes on how these notation systems came about: algebraic notation's","description":"Short, verified historical notes on how these notation systems came about: algebraic notation's\n    18th-19th century roots, FIDE's 1981 mandate that retired descriptive notation, David Forsyth's\n    newspaper diagram notation behind FEN, Steven Edwards's early-1990s FEN/PGN standards, ICCF's numeric\n    notation, and Go's SGF format. Use for \"when did algebraic notation become standard\", \"who invented\n    FEN\", \"history of PGN\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"topic":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"A history topic or keyword to search for; omit to list all notes.","examples":["algebraic","FIDE","FEN","PGN","ICCF","SGF"],"title":"Topic"}},"title":"history_noteArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}}}}