How do I build a deterministic poker game-state workflow with an API?
Use POST /v1/pokerkit/games/state to rebuild a full-information snapshot from a documented game configuration and actions, then use POST /v1/pokerkit/games/step to append one checked next_action.
POST /v1/pokerkit/games/state to obtain the current snapshot and legal_actions; choose an action only through your own training or review UI, then call POST /v1/pokerkit/games/step with that next_action and expected_action_count equal to the action-list length. Store the returned actions as the next deterministic state. Use GET /v1/pokerkit/meta to read the current documented metadata before choosing variant codes or enum vocabulary; it does not validate undocumented formats, expose a live-table feed, or provide strategy.Quick facts
| State endpoint | POST /v1/pokerkit/games/state |
|---|---|
| Step endpoint | POST /v1/pokerkit/games/step |
| Required base fields | Both operations require variant, starting_stacks, and antes. The public example uses variant: NT. |
| State output | The public example returns result.snapshot, including legal_actions, and echoes result.actions. |
| Checked append | Step requires next_action; expected_action_count is the optimistic-concurrency token for the action list being extended. |
| Use boundary | Full-information simulation for training, coaching, hand review, study, and research only; no real-money RTA. |
State versus step
Use state when you need to reconstruct the current game position from a supplied configuration and its actions. Its snapshot exposes factual state such as pot, stacks, board, submitted hole cards, and legal_actions.
Use step only to extend that same supplied action list by one documented next_action. It returns a new snapshot and the extended actions. Neither endpoint returns GTO strategy, player modeling, or a recommended action.
Read the current snapshot
Use JSON and an API key. This request and response are the public pokerkitGamesState docs-code example.
{"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"]}
{"result": {"snapshot": {"terminal": false, "street_index": 0, "actor_index": 0, "pot": 8, "bets": [2, 6], "stacks": [198, 194], "board": [], "hole_cards": [{"player": 0, "cards": ["Ah", "Kh"]}, {"player": 1, "cards": ["Qs", "Qd"]}], "legal_actions": [{"action": "fold"}, {"action": "check_or_call", "amount": 4}, {"action": "complete_bet_or_raise_to", "min": 10, "max": 200}]}, "actions": ["d dh p1 AhKh", "d dh p2 QsQd", "p2 cbr 6"]}}Render or validate only the returned snapshot facts. In this example, legal_actions lists fold, a check-or-call amount, and a complete-bet-or-raise-to minimum and maximum; it is the legal-action surface for the submitted full-information state, not advice about which action to take.
Append one action with concurrency protection
Before appending, retain the exact action list used for the state call. Set expected_action_count to its length and send the intended documented next_action. The public schema describes a mismatch as HTTP 409; refresh your stored action list and rebuild state instead of overwriting a concurrent update.
{"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"], "next_action": "p1 cc", "expected_action_count": 3}
{"result": {"snapshot": {"terminal": false, "street_index": 1, "actor_index": null, "pot": 12, "bets": [0, 0], "stacks": [194, 194], "board": [], "hole_cards": [{"player": 0, "cards": ["Ah", "Kh"]}, {"player": 1, "cards": ["Qs", "Qd"]}], "legal_actions": [{"action": "deal_board"}]}, "actions": ["d dh p1 AhKh", "d dh p2 QsQd", "p2 cbr 6", "p1 cc"]}}The example extends three submitted actions with p1 cc, returns four actions, and advances the snapshot. Continue by treating that returned action list as the input for the next state or step call.
Deterministic workflow and human review
A minimal workflow is: persist configuration plus actions; call state; show the factual snapshot and legal_actions in a training or review UI; have a human select or approve a documented action; call step with that action and the expected count; persist returned actions.
The service rebuilds state from submitted data rather than retaining a live game session. Keep your own audit record of the configuration, action list, human review, and returned snapshot. Do not imply the API validated a player's identity, predicted opponents, or selected a poker strategy.
Full-information and simulation boundary
The public examples include submitted snapshot.hole_cards; the schema describes viewer as reserved and v1 as full-information. Use these endpoints only where every submitted card and action belongs in a training, simulation, or post-session review workflow.
Do not represent this API as hidden-information play, a live-table feed, support for undocumented variants or action formats, player modeling, or strategic advice. Check the current OpenAPI schema and /v1/pokerkit/meta for supported variant codes rather than inferring coverage.
Validation, current contract, and no-RTA
Both public operations declare a 422 validation response. For state, validate the documented configuration and action list. For step, also validate next_action and handle the documented 409 count mismatch by reloading current actions. Use the current authentication, quota, and error documentation for account-level handling.
Pokerai API is for training, coaching, hand review, study, and research only. Real-time assistance at real-money tables is prohibited. Do not use snapshots, legal actions, or step results to automate or instruct a live real-money decision.
Related endpoints
Use the current public contract for state reconstruction and checked action appends; do not infer unsupported game formats or decision features.
| Endpoint | What it does | Use it for |
|---|---|---|
POST /v1/pokerkit/games/state | Rebuild a current full-information snapshot and legal_actions from submitted configuration and actions | A deterministic training, simulation, or post-session review state view |
POST /v1/pokerkit/games/step | Apply one next_action; optional expected_action_count protects the action-list extension | A human-reviewed, checked append to the submitted action history |
SDK, MCP, and related resources
- Developer docs — official SDK and MCP setup alongside authentication and quotas
- API Reference — inspect the current state and step request contracts
- OpenAPI snapshot — machine-readable English contract
- Python SDK — official package entry point
- TypeScript / JavaScript SDK — official package entry point
- MCP server — official package entry point
- Poker hand-history API guide — parse and replay a submitted completed hand
- llms.txt — concise LLM entry point