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
EndpointWhat it does
POST /v1/solveReads a table image and returns the solver's strategy.
POST /v1/readReads a table image and returns the parsed table only.
POST /v1/solve/stateSolves 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.

ParameterTypeDescription
imagefilePNG, JPEG or WebP, up to 8 MB. Required unless one of the next two is set.
image_urlstringHTTPS URL of the image. We fetch it once.
image_base64stringThe image as base64, for JSON bodies.
gamestringOptional hint: plo4 or plo5. Detected from the image when left out.
big_blindnumberOptional. The big blind in chips, for tables that do not show it. Used to convert chips to big blinds.
hand_idstringOptional. Your id for the hand. Frames that share it are tracked as one hand. See Tracking a hand.
min_confidencenumberOptional, 0 to 1. Below this read confidence the call returns low_confidence and no solution.
max_wait_msintegerOptional. 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.

FieldTypeDescription
idstringId of this call. Quote it when you report a problem.
read.gamestringplo4 or plo5.
read.streetstringpreflop, flop, turn or river.
read.heroobjectHero's position, cards and stack_bb.
read.boardstring[]Board cards dealt so far, such as "Qs".
read.pot_bbnumberPot in big blinds, including bets on this street.
read.to_call_bbnumberWhat Hero must put in to continue. 0 when checked to.
read.playersintegerPlayers dealt in. read.in_hand is how many are still in.
read.lineobjectActions so far, per street. See the notation below.
read.confidencenumberConfidence in the read, 0 to 1.
solution.matchstringexact, or approximate when the nearest solved spot was used.
solution.notestringPresent when the match is approximate. Says what differs.
solution.sourcestringlibrary for a pre-solved spot, live for one solved during the call.
solution.actionsobject[]One entry per available action, with action, frequency and ev_bb. Bets and raises also carry size_pct_pot.
timing_msobjectTime 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 approximate and solution.note says 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" }
  }
}
StatusCodeMeaning
400invalid_requestThe body is malformed or has no image.
401invalid_api_keyThe key is missing, wrong or revoked.
402out_of_requestsThe key has no requests left. Add a pack to continue.
409not_hero_turnHero has no decision to make in this frame. /v1/read still works.
413image_too_largeThe image is over 8 MB.
422unreadable_imagePart of the table could not be read. detail.region says which.
422unsupported_layoutThe table layout is not one we read yet.
422unsupported_gameThe game is outside early-access coverage.
422low_confidenceThe read scored below your min_confidence.
404no_solutionNo solved spot is close enough and a live solve is not possible for this one.
429rate_limitedToo many requests. Wait for the time in Retry-After.
504solve_timeoutA 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.

Early access

Get a key in the next batch.

We are onboarding developers in small groups. Tell us what you are building and how much you expect to call the API. It decides who we onboard first and what we build next.

  • 100 free requests with your key
  • No payment details now
  • One email when your key is ready

Questions? Reach out to @we_will_give_a_username on Telegram.

Games you need

We use your email only to contact you about access.