← All guides
On this page
  1. Home
  2. Guides
  3. How do I parse and replay PokerKit .phh hand histories with an API?
Guide Poker semantics · 07/09 Hand review 15 min Advanced

How do I parse and replay PokerKit .phh hand histories with an API?

Use POST /v1/pokerkit/notation/parse to turn one PokerKit .phh string into structured configuration, then use POST /v1/pokerkit/notation/replay to rebuild documented action steps as review snapshots.

Updated Maintained by Pokerai API

Direct answer: POST /v1/pokerkit/notation/parse accepts the required text field containing a PokerKit .phh hand-history string. POST /v1/pokerkit/notation/replay accepts that text or documented configuration plus actions, with optional index for one step. Parse extracts structured hand data; replay returns state snapshots for display and post-session review. For known-card, post-session results, POST /v1/pokerkit/eval/hand evaluates a supplied holding and optional board, while POST /v1/pokerkit/eval/compare ranks two or more supplied holdings and optional board; neither evaluates a hand history, reconstructs missing information, nor returns strategy or a live-play action.

Quick facts

Parse endpointPOST /v1/pokerkit/notation/parse
Replay endpointPOST /v1/pokerkit/notation/replay
Documented inputsParse requires text. Replay accepts text or documented config fields with actions; index is optional.
Documented replay outputThe public example returns result.snapshot and result.step_count.
Use boundaryTraining, coaching, hand review, study, and research only; no real-money RTA.

Parse versus replay

Use parse when your input is a PokerKit .phh text string and you need its structured configuration, including documented fields such as variant, blinds, starting stacks, and actions. Use replay when you need a state view for the submitted history: it can accept the source text, or the documented configuration fields and actions directly.

These endpoints have different jobs. Parse does not create a review timeline or poker recommendation. Replay rebuilds state from the supplied history; it does not convert the hand into solver strategy, equity, or an action recommendation.

Minimal parse request and response

Use JSON and an API key. This request and response are the public pokerkitNotationParse docs-code example.

curl -s https://pokerai.bet/v1/pokerkit/notation/parse \
  -H "Authorization: Bearer $POKERAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"text":"variant = \"NT\"\nactions = [\"d dh p1 AhKh\", \"d dh p2 QsQd\"]\n"}'
{"result":{"variant":"NT","actions":["d dh p1 AhKh","d dh p2 QsQd"]}}

The complete public docs-code example contains additional parsed fields. Treat the returned configuration as the structured representation of the submitted notation, and inspect the current Reference or OpenAPI snapshot for the complete contract.

Replay a hand for display or review

Replay can receive a .phh string in text, or the documented configuration fields and actions. Supply optional index only when you need the snapshot at one documented step index.

curl -s https://pokerai.bet/v1/pokerkit/notation/replay \
  -H "Authorization: Bearer $POKERAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"variant":"NT","antes":[0,0],"blinds_or_straddles":[1,2],"min_bet":2,"starting_stacks":[200,200],"actions":["d dh p1 AhKh","d dh p2 QsQd","p2 cbr 6","p1 f"],"index":2}'
{"result":{"snapshot":{"terminal":false,"street_index":0,"pot":3,"bets":[2,1],"stacks":[198,199],"board":[],"hole_cards":[{"player":0,"cards":["Ah","Kh"]},{"player":1,"cards":["Qs","Qd"]}]},"step_count":5}}

Use snapshot fields such as pot, bets, stacks, board, and legal actions to render the submitted history. The example's step_count is the documented count for that submitted action list.

Full-information boundary

Replay is a full-information reconstruction of what you submit. In the public response example, snapshot.hole_cards contains the submitted players' cards. It is appropriate for a display or review UI only when that information belongs in the submitted completed-hand workflow.

Do not present replay as hidden-card inference, partial-information simulation, a result-accuracy guarantee, or a live decision tool. It rebuilds the documented state from supplied notation or configuration and actions.

When to use it — and when not to

Use these endpoints for post-session hand-history import, a hand-review timeline, a coaching or study display, or research tooling that needs a structured PokerKit notation record and its rebuilt state.

Do not use them to claim support for another hand-history format, to infer missing hand information, to provide live real-money assistance, or to turn snapshots into betting instructions. They do not replace a separate documented endpoint when your task is GTO strategy, equity, or hand evaluation.

Errors and current contract

Both public OpenAPI operations declare a 422 validation error response. For parse, check that text is present and conforms to PokerKit .phh notation. For replay, check text or the documented configuration fields, actions, and optional index against the current Reference or OpenAPI schema before correcting and resubmitting.

Use the current authentication documentation, quota documentation, and error documentation for account-level handling. Do not retry an unchanged invalid request.

No real-money RTA

Pokerai API is for training, coaching, hand review, study, and research only. Real-time assistance at real-money tables is prohibited. Keep parse and replay output out of live-table automation and do not present a snapshot as a live action instruction.

Related endpoints

Use the current public contract for each endpoint rather than inferring extra format or analysis support.

EndpointWhat it doesUse it for
POST /v1/pokerkit/notation/parseParse required text containing PokerKit .phh notation into structured hand dataImporting a documented PokerKit hand history
POST /v1/pokerkit/notation/replayRebuild submitted text or config and actions into snapshots; optional index selects one stepDisplaying or reviewing a submitted completed hand

SDK, MCP, and related resources