API Documentation

Access live poker club traffic data via simple REST endpoints. All responses are JSON.

Authentication

All API requests require an API key. Pass it in one of two ways:

Header (recommended)

Authorization: Bearer pk_pro_abc123...

Query parameter

?apiKey=pk_pro_abc123...

Your API key is scoped to specific clubs. You can only access data for clubs assigned to your key.

Base URL

https://api.yoursite.com/api/v1

All endpoint paths below are relative to this base URL.

Endpoints

GET/v1/traffic

Current traffic snapshot — KPIs, breakdown by game type and buy-in range.

Parameters

Name	Type	Required	Description
clubId	number	No	Filter by specific club (must be in your key scope)

Example Request

curl -H "Authorization: Bearer YOUR_KEY" \
     "https://api.yoursite.com/api/v1/traffic"

Example Response

{
  "totalTables": 47,
  "totalPlayers": 186,
  "avgFillRate": 62,
  "maxBuyin": 50000,
  "byGameType": [
    { "game_type": "NLH", "tables": 31, "players": 124 }
  ],
  "byBuyin": [
    { "range": "Micro (≤500)", "count": 8 }
  ],
  "updatedAt": "2026-04-09 18:30:00"
}

GET/v1/tables

List of active cash tables and tournaments. Filterable by format, game type, and stakes.

Parameters

Name	Type	Required	Description
clubId	number	No	Filter by club
format	string	No	CASH, MTT, SNG, or AOF
gameType	string	No	NLH, PLO4, PLO5, PLO6, PLO4HL, PLO5HL, PLO6HL, 6+
gameGroup	string	No	PLO (all PLO) or PLOHL (all Hi-Lo)
buyinMin	number	No	Min buy-in (useful for MTT/SNG tiers)
buyinMax	number	No	Max buy-in (useful for MTT/SNG tiers)
page	number	No	Page number (default: 1)
limit	number	No	Results per page (default: 50, max: 100)

Example Request

curl -H "Authorization: Bearer YOUR_KEY" \
     "https://api.yoursite.com/api/v1/tables?gameGroup=NL&buyinMin=1000"

Example Response

{
  "tables": [
    {
      "id": 1234,
      "game_type": "NLH",
      "format": "CASH",
      "table_name": "NLH 50/100",
      "players_current": 6,
      "players_max": 8,
      "blind_small": 50,
      "blind_big": 100,
      "buyin": 5000,
      "observed_at": "2026-04-09 18:30:00"
    },
    {
      "id": 5678,
      "game_type": "NLH",
      "format": "MTT",
      "table_name": "Sunday Main Event",
      "tour_state": 2,
      "start_time": 1744300800,
      "prize_pool": 50000,
      "late_reg": 1,
      "bounty_type": 2,
      "satellite_stage": 0,
      "players_current": 142,
      "players_max": 0,
      "buyin": 55
    }
  ],
  "total": 31,
  "page": 1,
  "totalPages": 1
}

Tournament-specific fields (MTT/SNG)

format — CASH, MTT, SNG, or AOF

tour_state — 1=Announced, 2=Registering, 3=Running, 4=Ended

start_time — Unix timestamp of tournament start

prize_pool — Prize pool amount

late_reg — 0=none, 1=active, 2=ended

bounty_type — 0=none, 1=KO, 2=PKO, 3=Mystery

satellite_stage — 0=none, 1-4=step, 9=final

GET/v1/heatmap

Stakes availability over time — how many tables at each stake level per time snapshot.

Parameters

Name	Type	Required	Description
clubId	number	No	Filter by club
format	string	No	CASH, MTT, SNG, or AOF
gameType	string	No	NLH, PLO4, PLO5, PLO6, etc.
gameGroup	string	No	PLO (all PLO) or PLOHL (all Hi-Lo)
from	string	No	Start datetime (ISO format)
to	string	No	End datetime (ISO format)
dayOfWeek	string	No	weekday or weekend

Example Request

curl -H "Authorization: Bearer YOUR_KEY" \
     "https://api.yoursite.com/api/v1/heatmap?gameGroup=NL"

Example Response

{
  "stakes": ["50/100", "25/50", "10/20"],
  "snapshots": [
    {
      "time": "2026-04-09 18:00:00",
      "byStake": {
        "50/100": { "tables": 5, "players": 32, "maxPlayers": 40 },
        "25/50": { "tables": 8, "players": 44, "maxPlayers": 64 }
      }
    }
  ]
}

GET/v1/history

Traffic timeline — NL/PLO table counts and total players over time.

Parameters

Name	Type	Required	Description
clubId	number	No	Filter by club
from	string	No	Start datetime (ISO format)
to	string	No	End datetime (ISO format)
dayOfWeek	string	No	weekday or weekend

Example Request

curl -H "Authorization: Bearer YOUR_KEY" \
     "https://api.yoursite.com/api/v1/history?from=2026-04-01&to=2026-04-09"

Example Response

{
  "timeline": [
    {
      "time": "2026-04-09 12:00:00",
      "nl": 25,
      "plo": 12,
      "total": 37,
      "players": 148
    },
    {
      "time": "2026-04-09 18:00:00",
      "nl": 31,
      "plo": 16,
      "total": 47,
      "players": 186
    }
  ]
}

Error Handling

Status	Meaning	Example
401	Missing or invalid API key	{"error": "Invalid or inactive API key"}
403	Club not in your key scope	{"error": "Access denied for this club"}
429	Rate limit exceeded	{"error": "Rate limit exceeded", "retry_after": 60}

Rate Limits

Rate limits are applied per API key, per minute. The limit depends on your plan:

Plan	Requests/min	Clubs
1-19 clubs	60	$15/club/mo
20-49 clubs	120	$12/club/mo
50+ clubs	300	$10/club/mo

When rate limited, the response includes a retry_after field (in seconds). Data refreshes every 60 seconds, so polling more frequently than once per minute is unnecessary.