← All guides
On this page
  1. Home
  2. Guides
  3. How do I make my first GTO poker API request?
Quickstart Start here · 01/06 All products 8 min Beginner

How do I make my first GTO poker API request?

Create a free Pokerai API key, send one authenticated JSON request to POST /v1/gto/preflop, and read the returned action frequencies as a mixed strategy.

Updated Maintained by Pokerai API

Direct answer: Put your key in the Authorization: Bearer <API_KEY> header and send the complete spot as JSON. The response lists the frequency of every available action; it does not choose one recommended move.

Quick facts

EndpointPOST /v1/gto/preflop
AuthenticationBearer API key from the dashboard sign-in
InputHole cards, hero position, and the full preflop action sequence
OutputFold, call, or raise frequencies, with raise sizing when present
QuotaOne presolved lookup for this request; Free includes 1,000 presolved lookups per month
Allowed useTraining, coaching, hand review, study, and research; no real-money RTA

When to use this quickstart

Use it to verify authentication, inspect the response shape, or start a trainer, study tool, hand-review workflow, backend service, or AI agent integration.

When not to use it

Do not use this endpoint as live advice during real-money play. For a custom flop, turn, or river tree, follow the real-time solver workflow in the developer docs instead of treating this preflop lookup as a general postflop solver.

Minimal curl request

Create a key, store it locally as POKERAI_API_KEY, and run this request. Never commit the real key or place it in client-side code.

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

Real response

This captured response is for MP holding 9h9s after a 2.5bb UTG open:

{
  "hole_cards": "9h9s",
  "situation": "Raise",
  "strategy": [
    { "action": "fold", "frequency": 0.254 },
    { "action": "call", "frequency": 0.106 },
    { "action": "raise", "frequency": 0.64, "amount_bb": 9, "sizing_pot": 1 }
  ]
}

The three frequencies sum to 1: fold 25.4%, call 10.6%, and raise to 9bb 64%. Treat this as a distribution to study or sample from, not as a promise that one action will win.

Quota

Pokerai API meters presolved lookups separately from real-time solves. This preflop request uses one presolved lookup. The Free tier includes 1,000 presolved lookups and 25 real-time solves per month; both counters reset monthly and current usage is shown in the dashboard. See pricing for the current public limits.

Common errors

The public OpenAPI contract for this endpoint declares these non-success responses:

HTTPMeaningWhat to do
400Invalid JSON, a missing field, invalid cards, position, or action sequence.Fix the request; do not retry unchanged.
401missing_api_key or invalid_api_key.Check the Bearer header and key.
429quota_exceeded: the monthly presolved quota is exhausted.Wait for the monthly reset or change the account quota.

SDK and MCP options

The official clients follow the same public OpenAPI contract and use the same API key and quota. Full typed examples are in the SDK documentation.

  • Python SDK: pip install pokerai-bet (import as pokerai).
  • TypeScript / JavaScript SDK: npm install @pokerai/client.
  • MCP server for AI agents: npx @pokerai/mcp. Presolved tools are enabled by default; enabling solver tools consumes the separate solve quota.

No real-money RTA

Use Pokerai API for training, coaching, hand review, study, and research only. Real-time assistance at real-money tables is prohibited. The API returns strategy frequencies for your application to interpret; it does not guarantee winnings or select a move for live play.
Next step

Once the curl request succeeds, choose the resource that matches what you are building: