Home / API Documentation

Poker API Documentation

Comprehensive guide to integrating with the AI Poker Tools API

Overview

The AI Poker Tools API provides programmatic access to advanced poker calculations, odds analysis, and game state evaluation. Our API is designed for developers who want to integrate sophisticated poker analysis into their applications.

Base URL

https://www.aipokertools.com

Authentication

All API requests require authentication using your API key. Include your key in the request headers:

Authorization: Bearer YOUR_API_KEY

Endpoints

POST /api/v1/probabilities

Calculate poker hand probabilities for given cards using Monte Carlo simulation.

Request Body:

{
  "cards": ["Ah", "Kh"]
}

Response:

{
  "success": true,
  "data": {
    "cards": ["Ah", "Kh"],
    "probabilities": {
      "Flush": 0.06486,
      "Four of a Kind": 0.00127,
      "Full House": 0.022,
      "High Card": 0.18114,
      "One Pair": 0.43388,
      "Straight": 0.03136,
      "Straight Flush": 0.00044,
      "Three of a Kind": 0.04321,
      "Two Pair": 0.22184
    },
    "simulations": 100000
  }
}

POST /api/v1/probabilities-enhanced

Calculate enhanced poker statistics including win rates against multiple opponents and detailed hand probability breakdowns for both player and opponents.

Request Body:

{
  "cards": ["Kh", "Kc"],
  "opponents": 3
}

Response:

{
  "success": true,
  "data": {
    "cards": ["Kh", "Kc"],
    "opponents": 3,
    "win_rate": 0.6842,
    "tie_rate": 0.0158,
    "lose_rate": 0.3000,
    "our_hand_probabilities": {
      "One Pair": 0.43388,
      "Two Pair": 0.22184,
      "Three of a Kind": 0.11752,
      "Full House": 0.086,
      "Four of a Kind": 0.00856,
      "Flush": 0.0202,
      "Straight": 0.01216,
      "Straight Flush": 0.00008
    },
    "opponent_hand_probabilities": {
      "One Pair": 0.08768,
      "Two Pair": 0.23586,
      "Three of a Kind": 0.16442,
      "Straight": 0.2099,
      "Flush": 0.13536,
      "Full House": 0.1494,
      "Four of a Kind": 0.01494,
      "Straight Flush": 0.00244
    }
  }
}

Interactive Demo

Try out the API with this interactive poker odds calculator. Select your cards and board cards to see real-time probability calculations.

Poker Odds Calculator

Select your hole cards and community cards to calculate win probabilities

Your Cards

Community Cards

Select at least your two hole cards to calculate odds

Enhanced Demo - Win Rate Analysis

Try the enhanced API that calculates win rates against multiple opponents and shows detailed hand probability breakdowns for both you and your opponents.

Enhanced Poker Analysis

Select your cards and number of opponents to see win rates and probability comparisons

Your Cards

Community Cards

Number of Opponents

3 opponents
Select your two hole cards and set opponent count to analyze win rates

Card Naming Conventions

All cards in the API use a standardized two-character format: Rank + Suit

Ranks

A
Ace
K
King
Q
Queen
J
Jack
T
Ten
9-2
Nine to Two

Suits

h
Hearts ♥
d
Diamonds ♦
c
Clubs ♣
s
Spades ♠

Examples

Ah = Ace of Hearts Kd = King of Diamonds Qc = Queen of Clubs Js = Jack of Spades Th = Ten of Hearts 2s = Two of Spades

Message Formats

Request Format

All POST requests should use JSON format with Content-Type: application/json

Content-Type: application/json
Authorization: Bearer YOUR_API_KEY

{
  "parameter": "value"
}

Response Format

All responses are returned in JSON format:

{
  "success": true,
  "data": {
    // Response data here
  }
}

Error Format

{
  "success": false,
  "error": {
    "code": "INVALID_CARDS",
    "message": "Invalid card format provided",
    "details": "Card 'Xh' is not a valid card"
  }
}

Error Codes

Code Description
INVALID_API_KEY API key is missing or invalid
INVALID_CARDS One or more cards have invalid format
DUPLICATE_CARDS Same card appears multiple times
RATE_LIMIT_EXCEEDED Too many requests in time window
INSUFFICIENT_CREDITS Account has insufficient API credits

Code Examples

Python

import requests
import json

url = "https://www.aipokertools.com/api/v1/probabilities"
headers = {
    "Authorization": "Bearer YOUR_API_KEY",
    "Content-Type": "application/json"
}

data = {
    "cards": ["Ah", "Kh"]
}

response = requests.post(url, headers=headers, json=data)
result = response.json()

if result['success']:
    probabilities = result['data']['probabilities']
    print(f"One Pair: {probabilities['One Pair']:.2%}")
    print(f"Two Pair: {probabilities['Two Pair']:.2%}")
    print(f"Flush: {probabilities['Flush']:.2%}")
else:
    print(f"Error: {result['error']['message']}")

JavaScript

const response = await fetch('https://www.aipokertools.com/api/v1/probabilities', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    cards: ['Ah', 'Kh']
  })
});

const result = await response.json();

if (result.success) {
  const probabilities = result.data.probabilities;
  console.log(`One Pair: ${(probabilities['One Pair'] * 100).toFixed(1)}%`);
  console.log(`Two Pair: ${(probabilities['Two Pair'] * 100).toFixed(1)}%`);
  console.log(`Flush: ${(probabilities['Flush'] * 100).toFixed(1)}%`);
} else {
  console.error(`Error: ${result.error.message}`);
}

Support

Need help with the API? We're here to assist you:

  • Email: api-support@aipokertools.com

Table of Contents

Select a Card

Rank

Suit