← All guides
On this page
  1. Home
  2. Guides
  3. How do I analyze a poker hand with an API?
Guide Poker semantics · 04/09 Hand review 12 min Intermediate

How do I analyze a poker hand with an API?

Send a hole-card hand and a flop, turn, or river board to POST /v1/pokerkit/hand-report for a documented factual hand report.

Updated Maintained by Pokerai API

Direct answer: for a combined Hero report, submit hole and board to POST /v1/pokerkit/hand-report. For board-only tasks, use POST /v1/pokerkit/board-report or POST /v1/pokerkit/category-combos with board; use POST /v1/pokerkit/hand-tier, POST /v1/pokerkit/draws, POST /v1/pokerkit/outs, or POST /v1/pokerkit/blockers with hole and board; use POST /v1/pokerkit/hand-strength with hole_range; use POST /v1/pokerkit/nuts for the board's strongest makeable hand and tying combos; and use POST /v1/pokerkit/cards/normalize with cards to validate and normalize card strings. Check each operation's current OpenAPI schema before interpreting its result; use completed hands for training or review—not action selection at a real-money table.

Quick facts

EndpointPOST /v1/pokerkit/hand-report
Required inputhole (two cards) and board (3, 4, or 5 community cards), as defined by the public HandRequest schema
Optional inputhand_type and dead, as defined by the public OpenAPI schema
Documented reportTexture, made-hand tier, draws, outs, and blocker context for the submitted hand and board
Use boundaryTraining, coaching, completed-hand review, study, and research only; no real-money RTA

Input semantics

hole is the player's two hole cards and board is a three-, four-, or five-card community board. Concatenate standard two-character card codes without separators. The public HandRequest schema also allows hand_type and dead; omit them unless a documented workflow requires them.

Minimal request and response

This curl request and response are the shared public pokerkitHandReport example.

curl -s https://pokerai.bet/v1/pokerkit/hand-report \
  -H "Authorization: Bearer $POKERAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"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,"nut_rank":{"name":"NON_NUT","value":"Non-nut"}},"draws":{"straight_draw":null,"flush_draw":null,"nut_rank":null},"outs":{"by_category":{},"count":0}}}

How to interpret the report

texture describes the supplied board: its cards, categorical wetness, connectivity, rank band, available straight and flush draws, and suit-shape booleans. tier classifies the made hand; in the example, category is Straight and is_nut is false. draws records remaining straight or flush draw labels and their nut rank; null here means the example does not report either draw. outs groups improvement cards by category and provides count; this example has an empty group and zero outs.

The public docs describe Hand Report as the combined hero overview for texture, tier, draws, outs, and blockers. The shared public response example above does not include a blockers member, so clients must not require one. To inspect the documented blocker fields, use the separate POST /v1/pokerkit/blockers contract: it reports nut-combo totals and blocked counts, blocker cards, a block fraction, and whether Hero blocks the nuts.

When to use it

Use Hand Report to annotate a completed hand in a trainer, coaching tool, hand-history review, study notebook, or research workflow. It is useful when the UI needs factual board and hand labels before presenting other separately documented analysis.

When not to use it

Do not treat descriptive fields as equity, a solver result, a guarantee, or a recommended move. Do not connect this endpoint to a live-table feed, automate an action from its output, or use it for real-money real-time assistance.

Quota and errors

Hand Report uses the same API key and account quota system as the public PokerKit API. Check quota documentation, pricing, and the dashboard for current account limits and usage rather than hard-coding a limit. The public OpenAPI contract declares a 422 validation response; correct hole, board, and optional fields against the current Reference or OpenAPI schema. For authentication and quota errors, use the current error documentation and do not retry an unchanged invalid request.

SDK, MCP, and related resources

Developer docs provide official SDK and MCP setup alongside authentication and quotas. Inspect the current operation in the API Reference and the machine-readable OpenAPI snapshot. Official entry points are the Python SDK, TypeScript / JavaScript SDK, and MCP server.

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 hand-analysis output out of live-table automation and do not present it as a live action instruction.

Related public operations

Use these separate public contracts when a review needs a narrower factual result.

EndpointTaskUse
POST /v1/pokerkit/hand-reportAnalyze one hand and boardReturn the combined documented hand report.
POST /v1/pokerkit/blockersInspect blocker evidenceRead the documented nut-combo blocker fields separately.

Related resources