API reference · v1 preview
Send a table. Get the solve.
Rangefinder takes an image of a poker table and returns two things: what it read from the image, and the solver's strategy for Hero's decision.
Preview. The API is in private early access. Endpoints and field names on this page can change before general availability. Request access to get a key.
Overview
All requests go over HTTPS to one base URL. Responses are JSON.
https://api.rangefinderapi.com/v1
| Endpoint | What it does |
|---|---|
POST /v1/solve | Reads a table image and returns the solver's strategy. |
POST /v1/read | Reads a table image and returns the parsed table only. |
POST /v1/solve/state | Solves a spot you describe as JSON. No image. |
Early access covers PLO4 and PLO5 cash games, heads-up to 6-max, on every street.
Authentication
Send your key as a bearer token. Keys start with rf_live_ and are issued when you join early access.
Authorization: Bearer rf_live_3f9a0c7e12b4d6a8
Call the API from your server. A key in a browser or a desktop app can be copied by anyone who uses it.
Quickstart
Post a screenshot as multipart form data.
curl https://api.rangefinderapi.com/v1/solve \
-H "Authorization: Bearer $RANGEFINDER_KEY" \
-F image=@table.png
The response holds the parsed table in read and the strategy in solution.
{
"id": "slv_7f3k2m9q",
"read": {
"game": "plo4",
"street": "flop",
"hero": { "position": "BTN", "cards": ["As", "Ks", "Jd", "Td"], "stack_bb": 96.5 },
"board": ["Qs", "9d", "4c"],
"pot_bb": 7.5,
"to_call_bb": 0,
"players": 6,
"in_hand": 2,
"line": { "preflop": "F-F-F-R-F-C", "flop": "X" },
"confidence": 0.98
},
"solution": {
"match": "exact",
"source": "library",
"actions": [
{ "action": "check", "frequency": 0.38, "ev_bb": 4.17 },
{ "action": "bet", "size_pct_pot": 33, "frequency": 0.22, "ev_bb": 4.18 },
{ "action": "bet", "size_pct_pot": 75, "frequency": 0.4, "ev_bb": 4.19 }
]
},
"timing_ms": { "read": 184, "solve": 41, "total": 239 }
}
POST /v1/solve
Reads the table in an image and returns the strategy for Hero's pending decision. Send multipart/form-data with an image file, or a JSON body with image_url or image_base64.
| Parameter | Type | Description |
|---|---|---|
image | file | PNG, JPEG or WebP, up to 8 MB. Required unless one of the next two is set. |
image_url | string | HTTPS URL of the image. We fetch it once. |
image_base64 | string | The image as base64, for JSON bodies. |
game | string | Optional hint: plo4 or plo5. Detected from the image when left out. |
big_blind | number | Optional. The big blind in chips, for tables that do not show it. Used to convert chips to big blinds. |
hand_id | string | Optional. Your id for the hand. Frames that share it are tracked as one hand. See Tracking a hand. |
min_confidence | number | Optional, 0 to 1. Below this read confidence the call returns low_confidence and no solution. |
max_wait_ms | integer | Optional. How long a live solve may run before the best available answer is returned. Default 3000, maximum 10000. |
curl https://api.rangefinderapi.com/v1/solve \
-H "Authorization: Bearer $RANGEFINDER_KEY" \
-H "Content-Type: application/json" \
-d '{
"image_url": "https://example.com/frames/hand-812-turn.png",
"hand_id": "hand-812",
"min_confidence": 0.9,
"max_wait_ms": 4000
}'
Response
A successful call returns 200 with these fields.
| Field | Type | Description |
|---|---|---|
id | string | Id of this call. Quote it when you report a problem. |
read.game | string | plo4 or plo5. |
read.street | string | preflop, flop, turn or river. |
read.hero | object | Hero's position, cards and stack_bb. |
read.board | string[] | Board cards dealt so far, such as "Qs". |
read.pot_bb | number | Pot in big blinds, including bets on this street. |
read.to_call_bb | number | What Hero must put in to continue. 0 when checked to. |
read.players | integer | Players dealt in. read.in_hand is how many are still in. |
read.line | object | Actions so far, per street. See the notation below. |
read.confidence | number | Confidence in the read, 0 to 1. |
solution.match | string | exact, or approximate when the nearest solved spot was used. |
solution.note | string | Present when the match is approximate. Says what differs. |
solution.source | string | library for a pre-solved spot, live for one solved during the call. |
solution.actions | object[] | One entry per available action, with action, frequency and ev_bb. Bets and raises also carry size_pct_pot. |
timing_ms | object | Time spent on read and solve, and the total. |
Action values
fold, check, call, bet, raise and allin. Frequencies across the actions add up to 1. EV is in big blinds for Hero's exact hand, measured from this decision, so folding is always 0.
Line notation
Each street is a string of tokens in the order the players acted, joined by dashes: F fold, X check, C call, B bet, R raise, A all-in. The line ends where Hero's decision begins, so "flop": "X-B" means a check, then a bet, and now it is Hero's turn.
POST /v1/read
Takes the same input as /v1/solve and returns id, read and timing_ms without a solution. Use it when you only need the table state, or to check how well your layout is read before you solve anything.
curl https://api.rangefinderapi.com/v1/read \
-H "Authorization: Bearer $RANGEFINDER_KEY" \
-F image=@table.png
POST /v1/solve/state
Skips the image. Describe the spot as JSON and get the same solution object back. Use it when you already track the hand yourself.
curl https://api.rangefinderapi.com/v1/solve/state \
-H "Authorization: Bearer $RANGEFINDER_KEY" \
-H "Content-Type: application/json" \
-d '{
"game": "plo5",
"hero": { "position": "BB", "cards": ["Ac", "Qd", "Jc", "Th", "2h"], "stack_bb": 200 },
"board": ["Ks", "7c", "4h", "Qh"],
"players": 3,
"pot_bb": 31.5,
"to_call_bb": 13.5,
"line": { "preflop": "F-R-R-C", "flop": "X-X", "turn": "B" }
}'
Tracking a hand
One screenshot shows where a hand is. It does not always show how it got there, and the solver needs both. There are two ways to give it the history.
- Send frames with a
hand_id. Post frames as the hand goes on and reuse the same id. Rangefinder keeps the action line across them and each response is solved with the full history. - Send a single frame. The line is inferred from the pot, the bets on the table and the stacks. When more than one line fits, the answer is marked
approximateandsolution.notesays what was assumed.
If you already know the line, /v1/solve/state takes it directly.
Errors
Errors use standard HTTP status codes and a JSON body with a stable code.
{
"id": "slv_c81n4x0d",
"error": {
"code": "unreadable_image",
"message": "Could not read Hero's cards.",
"detail": { "region": "hero_cards" }
}
}
| Status | Code | Meaning |
|---|---|---|
| 400 | invalid_request | The body is malformed or has no image. |
| 401 | invalid_api_key | The key is missing, wrong or revoked. |
| 402 | out_of_requests | The key has no requests left. Add a pack to continue. |
| 409 | not_hero_turn | Hero has no decision to make in this frame. /v1/read still works. |
| 413 | image_too_large | The image is over 8 MB. |
| 422 | unreadable_image | Part of the table could not be read. detail.region says which. |
| 422 | unsupported_layout | The table layout is not one we read yet. |
| 422 | unsupported_game | The game is outside early-access coverage. |
| 422 | low_confidence | The read scored below your min_confidence. |
| 404 | no_solution | No solved spot is close enough and a live solve is not possible for this one. |
| 429 | rate_limited | Too many requests. Wait for the time in Retry-After. |
| 504 | solve_timeout | A live solve did not finish within max_wait_ms and no earlier answer was available. |
Limits and balance
Each key has a rate limit. Every response carries X-RateLimit-Limit and X-RateLimit-Remaining, and a 429 also carries Retry-After in seconds.
Requests are prepaid. Your first 100 are free, and after that you add packs. Every response shows what is left in X-Requests-Remaining. Only successful responses use up a request.
Image guidelines
- Send the whole table, not a crop. Seats, stacks, the pot and the action buttons all carry information.
- Keep the image at least 900 pixels wide. Native resolution is best, and upscaling does not help.
- Use screenshots. A photo of a monitor is not supported in early access.
- Keep overlays, chat windows and other tables off the cards and the pot.
- Capture after the cards and bets have stopped moving. A frame taken mid-animation is the most common cause of
unreadable_image.
Acceptable use
Rangefinder is built for study, hand review, training and broadcast tools.
Most poker operators prohibit real-time assistance during play. Do not use the API, or let your users use it through your product, to get help with a hand in progress in a game where the operator or the rules forbid it. You are responsible for following the terms of any platform your product touches, and we may revoke keys that are used to break them.