← All guides
On this page
  1. Home
  2. Guides
  3. How do I build a poker hand review API workflow?
Guide Build a product · 03/03 Hand review 20 min Advanced

How do I build a poker hand review API workflow?

Build a post-session review flow that accepts only a completed hand, uses deterministic API facts for its cards, board, equity, and strategy, then adds a GTO lookup after the user has chosen a study spot.

Updated Maintained by Pokerai API

Short answer: Keep the workflow asynchronous and study-oriented: parse or replay the completed hand, show verifiable card semantics and equity, then query a matching GTO spot for explanation. Pokerai API provides the facts; an LLM may explain or orchestrate them but does not replace the solver. Keep high-impact output under human review, and do not turn this into real-time advice at a real-money table.

Quick facts

Hand parsingPOST /v1/pokerkit/notation/parse parses public Poker Hand History notation into structured game data.
ReplayPOST /v1/pokerkit/games/state returns a snapshot including pot, stacks, board, hole cards, and legal actions for submitted actions.
SemanticsPOST /v1/pokerkit/hand-report returns texture, tier, draws, outs, and blockers for a hole-card hand and board.
EquityPOST /v1/pokerkit/equity returns Monte-Carlo equities and the sample count.
GTO lookupPOST /v1/gto/preflop returns presolved mixed strategy for a documented preflop action line.

1. Parse or replay the completed hand

Store a hand only after the session, then pass its Poker Hand History text to the notation parser. For a review timeline, submit the structured configuration and actions to the game-state endpoint; its snapshot gives the UI a factual pot, stacks, board, hole-card, and legal-action view.

{"text": "variant = \"NT\"\nante_trimming_status = true\nantes = [0, 0]\nblinds_or_straddles = [1, 2]\nmin_bet = 2\nstarting_stacks = [200, 200]\nactions = [\"d dh p1 AhKh\", \"d dh p2 QsQd\", \"p1 cbr 6\", \"p2 cc\", \"d db Qh7c2d\"]\n"}

{"result": {"variant": "NT", "ante_trimming_status": true, "antes": [0, 0], "blinds_or_straddles": [1, 2], "bring_in": null, "small_bet": null, "big_bet": null, "min_bet": 2, "starting_stacks": [200, 200], "actions": ["d dh p1 AhKh", "d dh p2 QsQd", "p1 cbr 6", "p2 cc", "d db Qh7c2d"], "automations": [{"name": "ANTE_POSTING", "value": "Ante posting"}, …], "author": null, "event": null, "day": null, "month": null, "year": null, "hand": null, "currency": null}}

2. Explain board and hand semantics

At the selected street, call the hand-report endpoint with the player's hole and the board. Render returned texture, made-hand tier, draws, outs, and blockers as labels and evidence; do not infer a recommendation from these descriptive fields.

{"hole": "JhTh", "board": "AsKsQs"}

{"result": {"texture": {"cards": ["As", "Ks", "Qs"], "wetness": {"name": "WET", "value": "Wet"}, "connectivity": {"name": "HIGH", "value": "High"}, "rank_band": {"name": "HIGH", "value": "High"}, "straight_draw": {"name": "OPEN_ENDED", "value": "Open-ended"}, "flush_draw": {"name": "LIVE", "value": "Live"}, "are_two_tone": false, "are_monotone": true, "are_rainbow": false}, "tier": {"category": {"name": "STRAIGHT", "value": "Straight"}, "is_nut": false, "pair_tier": null, "two_pair_tier": null, "three_of_a_kind_tier": null, "kicker_tier": null, "nut_rank": {"name": "NON_NUT", "value": "Non-nut"}}, "draws": {"straight_draw": null, "flush_draw": null, "nut_rank": null}, "outs": {"by_category": {}, "count": 0}}}

3. Estimate equity with its sampling context

For a review comparison, submit the known ranges, board, sample count, and seed to the equity endpoint. Display each returned equity beside sample_count; it is an estimate for the supplied ranges and board, not a promise about the next card or a betting instruction.

{"ranges": [["AA"], ["KK"]], "board": "", "sample_count": 2000, "seed": 7}

{"result": {"equities": [0.8235, 0.1765], "sample_count": 2000}}

4. Attach a GTO lookup for the review explanation

Map a reconstructed preflop action line to the documented preflop lookup. Show the returned strategy array as mixed frequencies and explain that the user chooses according to frequency; keep this review step separate from live play.

curl -s https://pokerai.bet/v1/gto/preflop \
  -H "Authorization: Bearer $POKERAI_API_KEY" -H "Content-Type: application/json" \
  -d '{"hole_cards":"AhKh","positions":{"hero":"MP"},"preflop_version":"6max_RC_100bb_200NL",
       "preflop_actions":[{"position":"SB","action":"small blind","amount":0.5},
                          {"position":"BB","action":"big blind","amount":1},
                          {"position":"UTG","action":"raise","amount":3}]}'

5. Build an explanation UI, not an action prompt

Show a stable sequence: hand timeline, board and hand facts, equity estimate, then the GTO strategy frequencies. Label inputs, returned fields, street, and assumptions. Present alternatives and frequency rather than a single “play now” button.

Training and review only

Accept only hands that have already ended, and use this workflow for training, coaching, hand review, study, and research after a hand. Require human review for consequential coaching or product output. Real-time assistance at real-money tables is prohibited. Do not ingest a live table feed, auto-select an action, or expose an in-hand recommendation interface.

Related resources